---
name: procedural-3d-scene
description: 用代码生成、复现或迭代风格化 3D 场景，组织构图、参数化资产、共享地形与水面、材质、动画和渲染成本。适用于海岛、营地、庭院等可交互场景及程序化 Demo；只有水体着色或现成资产摆放时不必使用完整流程。
---

# 程序化 3D 场景

把场景组织为可单独修改、共享空间规则的模块。沿用用户指定的引擎和资产约束；使用 Three.js/TSL 或海湾剖面构图时，阅读 [Tideglass Cove 案例](references/tideglass-cove.md)。该案例的尺寸、色板和算法是可选方法，不是每个场景的默认配置。

## 1. 构图与参数

- 先用占位体确定主体、背景、前景及主镜头；同时检查窄屏时主体是否被裁切。
- 将主体位置、尺寸、朝向、色板写成可编辑的参数表。结构性的布局用明确参数，小尺度变化再使用带种子的随机数。
- 给不同资产独立随机流或稳定的资产种子，避免新增一棵树就改变整座场景。
- 保留一份生成配置和可重复的预览状态，方便比较每次修改。

## 2. 共享空间接口

按实际场景需要定义接口，而不是让各模块各写一套近似值：

```text
terrainHeight(x,z)          地表高度
waterHeight(x,z,time)       水面高度，含潮位和事件波
waterGradient(x,z,time)     水面坡度或法线来源
boundary / obstacleFields  边界及障碍包络
time / tide / breeze       共用时间与环境状态
```

几何、物体落脚、接触检测、湿度及泡沫使用同一坐标约定和时间。需要 CPU 接触与 GPU 位移时，共用波参数；至少在几个固定点对照两端的采样结果。若使用近似梯度，记录省略的导数项，检查反射和高光是否仍然稳定。

## 3. 资产生成

根据形状选择表示方式：

| 形状 | 优先考虑的方法 | 先检查什么 |
| --- | --- | --- |
| 连续陆海表面 | 高度场、局部平滑遮罩 | 坡度、落脚点、边界 |
| 石块、躯干、细长物 | 变化截面、中心线、参数曲面 | 比例、截面过渡、法线 |
| 拱洞、连通岩体 | 隐式标量场与等值面提取 | 空腔、采样步长、薄壁 |
| 车身、窗洞、框架 | 二维轮廓、带孔挤出 | 开孔、倒角、共有边界 |
| 树冠、叶片 | 主轴与侧生小叶 | 叶根连接、自由端权重 |

先完成轮廓和连接，再叠加噪声。相邻部件复用同一边界或中心线。需保持形状的插值可选单调三次 Hermite，避免嘴部、尾柄等收窄区域过冲。

## 4. 材质与光照

- 先定大色块、粗糙度和光照方向，再添加纹理。低频调色、中频结构、高频凹凸分别控制幅度。
- 区分位置、法线、颜色的作用：凹凸细节不能修复错误轮廓，发光材质不能代替所有间接光。
- 标记依赖局部坐标的材质，合批时保留其坐标含义；需要世界连续纹理时再统一世界坐标。
- 昼夜切换同步更新环境反射、主光、补光、水色和局部灯，避免只改背景。

## 5. 水体与接触

有水时按需逐层加入，并保留单独查看各层的方式：水面位移 → 反射 → 深度折射 → 路径吸收与 Fresnel → 泡沫 → 湿度历史与焦散 → 事件涟漪。

- 平面反射适合大体平坦的水域；镜像相机基于平均水位，细波可扭曲采样。
- 屏幕空间折射检查深度有效性、界面前后关系和采样跳变，失败时回退；它缺少屏外信息。
- 岸边与独立岩石采用不同接触来源：地形高度差适合岸线，截面距离纹理适合岩脚。
- 湿度等有记忆的效果保存状态，并按秒衰减；涟漪等局部事件使用固定容量池。
- 剖面场景的水顶面、侧面与地形边界共享波函数和轮廓，检查高低潮时的接缝。

## 6. 动画与行为

- 植物以共享锚点和分层权重实现树干、叶柄、叶尖运动；关节处先跟随整体位移，再叠加局部位移。
- 动作有明显阶段时使用状态机。曲线路径连接保留端点速度，快速接触用子步和接触时刻细化。
- 行为避障可用保守椭球、胶囊和边界投影；需要真实刚体交互时再接入物理系统。
- 入水等事件提供接触位置、时间、方向和强度，由涟漪、水滴、水膜共同消费；粒子回收也采样共享水面。
- 交互参数按秒平滑，例如 `alpha = 1-exp(-k*dt)`，避免每帧固定插值带来的设备差异。

## 7. 合批与画面检查

- 合并静态对象前按材质、透明性、图层、阴影和交互角色分组；保留动态部件和局部坐标依赖。
- 重复粒子优先实例化；分别统计主画面、反射、折射及阴影的成本。
- 先从离屏纹理尺寸和刷新频率、像素比调节质量；降低网格细节前确认瓶颈。
- 用实际运行截图检查主镜头与窄屏、昼夜、高低潮和一次关键交互。每次扩展模块后，对照前一版主画面。

## 交付

交付可运行场景、生成配置、共享接口说明和实际截图。简述当前采用的近似与未运行的状态。复用参考项目的代码或资产时保留来源和许可证；不要从程序化代码推断作者使用过哪些 AI 工具。