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

# 程序化 3D 场景

把场景组织为可单独修改、共享空间规则的模块。沿用用户指定的引擎和资产约束；使用 Three.js/TSL 或海湾剖面构图时，阅读 [Tideglass Cove 案例](references/tideglass-cove.md)；制作铁路、道路或沿路径运动的微缩场景时，阅读 [山间铁路案例](references/mountain-railway.md)；制作建筑开合、舞台编排或发光装置时，阅读 [太阳神庙案例](references/sun-temple.md)。案例的尺寸、色板和算法是可选方法，不是每个场景的默认配置。

## 1. 构图与参数

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

## 2. 共享空间接口

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

```text
terrainHeight(x,z)          地表高度
waterHeight(x,z,time)       水面高度，含潮位和事件波
waterGradient(x,z,time)     水面坡度或法线来源
boundary / obstacleFields  边界及障碍包络
time / tide / breeze       共用时间与环境状态
routePointAt(s/L)          按弧长采样路径位置
routeTangentAt(s/L)        对应切线与方向
routeDistance(x,z)         地表到路径的距离
routeIntervals            车站、桥梁、隧道等路径区段
```

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

路径场景先确定中心线、弧长及净空，再生成轨道/道路、路基、桥隧与沿线设施。桥区保留下方地形，隧道区保留山体覆盖；不要把所有区段都压平成路面高度。改变控制点后刷新弧长缓存。路径最近点的离散采样仅作近似，精确净空应再检查几何。

## 3. 资产生成

根据形状选择表示方式：

| 形状 | 优先考虑的方法 | 先检查什么 |
| --- | --- | --- |
| 连续陆海表面 | 高度场、局部平滑遮罩 | 坡度、落脚点、边界 |
| 石块、躯干、细长物 | 变化截面、中心线、参数曲面 | 比例、截面过渡、法线 |
| 拱洞、连通岩体 | 隐式标量场与等值面提取 | 空腔、采样步长、薄壁 |
| 车身、窗洞、框架 | 二维轮廓、带孔挤出 | 开孔、倒角、共有边界 |
| 柱头、花瓶、轴对称雕饰 | 半径与高度轮廓、旋转曲面 | 顶底封口、轴向和分段数 |
| 重复门框、檐口与机械建筑 | 截面挤出、截头体、分组实例 | 洞口净空、相邻面和移动范围 |
| 树冠、叶片 | 主轴与侧生小叶 | 叶根连接、自由端权重 |

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

- 隧道等空腔不能仅靠抬高高度场表示；在入口裁掉挡住净空的面片，并与衬砌共用截面。射线检查入口，包络检查完整运动范围。
- 建筑地基采样旋转后 footprint 的多个地表点，再从水平基础向实际地形补侧墙；不要只采样建筑中心。沿线分布同时避开轨道、河流、房屋、灯具和主镜头视线。

## 4. 材质与光照

- 先定大色块、粗糙度和光照方向，再添加纹理。低频调色、中频结构、高频凹凸分别控制幅度。
- 区分位置、法线、颜色的作用：凹凸细节不能修复错误轮廓，发光材质不能代替所有间接光。
- 标记依赖局部坐标的材质，合批时保留其坐标含义；需要世界连续纹理时再统一世界坐标。
- 发光装置分别控制主体 emissive、外轮廓光晕和照亮环境的灯。透明光效检查深度测试、深度写入、混合与绘制次序；固定平面效果要验证侧视角，不能仅凭发光外观声称使用 Bloom 或体积光。
- 昼夜切换同步更新环境反射、主光、补光、水色和局部灯，避免只改背景。

## 5. 水体与接触

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

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

## 6. 动画与行为

- 导入人物时记录网格、贴图、骨架与动作各自来源和许可；不要把程序化环境描述成全程序化资产。核对单位、朝向、骨骼命名、动作绑定、蒙皮权重和材质透明性，再调整缩放与动画速度。导入告警不能只靠过滤日志解决。
- 建筑演出用一个归一化总进度映射到各部件的时间区间，位姿由当前进度计算，避免重复点击后跳回起点。需要平稳启停时可用 `6u^5-15u^4+10u^3`；回摆是可选艺术曲线，不能当作刚体求解。
- 人物、门和平台有依赖时设置守卫：角色返回到安全位置后再关闭支撑结构；中途反向应保留当前位置，明确转身与动作混合。路径位移和骨骼动画分别控制，核对脚步、速度与平台高度；需要自适应地形时再补落脚采样或 IK。
- 植物以共享锚点和分层权重实现树干、叶柄、叶尖运动；关节处先跟随整体位移，再叠加局部位移。
- 动作有明显阶段时使用状态机。曲线路径连接保留端点速度，快速接触用子步和接触时刻细化。
- 行为避障可用保守椭球、胶囊和边界投影；需要真实刚体交互时再接入物理系统。
- 入水等事件提供接触位置、时间、方向和强度，由涟漪、水滴、水膜共同消费；粒子回收也采样共享水面。
- 交互参数按秒平滑，例如 `alpha = 1-exp(-k*dt)`，避免每帧固定插值带来的设备差异。
- 沿路径推进保存距离 `s` 和速度 `v`，通过 `u=mod(s/L,1)` 采样；不要把普通曲线参数的线性增长当作匀速。
- 长车身用前后支承点的弦决定姿态，每个转向架再取自己的切线并转回车体局部坐标。减速到目标点可用 `vLimit=sqrt(2*a*d)`，配合加减速限制、停留时间和子步；这仍是路径运动模型，不是刚体模拟。静态合批的车轮不会因此自动旋转。
- 植物给顶点保存弯曲、摆动权重，给实例保存阵风相位。可见材质与阴影深度材质使用同一位移函数，避免叶片移动而阴影静止。
- 自动镜头由运动对象经过的区段或事件触发。转场采样整条相机轨迹的地形净空，平滑插值位置和目标；与手动控制交接时停止自动接管。

## 7. 合批与画面检查

- 静止的实例矩阵、变形法线和阴影按变化标记更新；角色动作仍可能要求阴影刷新。内嵌 Base64 与重复加载角色会增加包体及内存，产品化时评估外部二进制、共享网格与独立动作。截断 delta 会丢失时间，需要保留真实时长时使用积累器与子步。
- 合并静态对象前按材质、透明性、图层、阴影和交互角色分组；保留动态部件和局部坐标依赖。
- 重复粒子优先实例化；分别统计主画面、反射、折射及阴影的成本。
- 先从离屏纹理尺寸和刷新频率、像素比调节质量；降低网格细节前确认瓶颈。
- 用实际运行截图检查主镜头与窄屏、昼夜、高低潮和一次关键交互。每次扩展模块后，对照前一版主画面。
- LOD 保存相同实例的位置和色板，只改几何与局部动效；进入/退出细节档采用两个距离阈值，避免镜头在边界反复切换。需要主镜头保留细节时，单独设置其主体阈值。
- 在 PBR 着色器中追加纹理或高光时保留原处理；在片元亮度和粗糙度上改出湿润感，不为每个细节追加重合网格。合批后重新确认材质的坐标语义和标牌 UV。
- 阴影、反射和主视图可用不同刷新频率。性能统计包含实际离屏 pass；GPU timer 异步读取，支持缺失时标为不可用。不要将单次帧率写成普遍性能承诺。

## 交付

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