Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: water system design for RM-138

yhhc2bd60fe8c67
diff --git a/docs/WATER_DESIGN.md b/docs/WATER_DESIGN.md
new file mode 100644
index 000000000..e58f0d969
--- /dev/null
+++ b/docs/WATER_DESIGN.md
@@ -0,0 +1,165 @@
+# 水体系统设计(RM-138)
+
+状态:**设计稿,未实现,未确认**。写于 2026-10-23。依据是本仓库当前代码和 RM-138 卡片的正文;竞品一栏只写通用常识,
+**未逐条核对官方文档**,上板前需要补来源。涉及编辑器界面的部分,卡片要求先出控件设计稿并获得确认,本文只给范围,不给界面。
+
+## 1. 现状(已核对代码)
+
+**已有**
+- `builtin:water`(`sdk/src/render/builtinShaders.ts`):四组行进波加涟漪,画在法线里;折射;按实测深度的吸收与颜色;Fresnel 反射;
+ 岸边与浪尖泡沫。文档在 `graphics/materials.mdx` 的 Water 一节。
+- `PlanarReflection` 组件与镜像相机(`src/esengine/ecs/components/PlanarReflection.hpp`,RM-044)。
+- 材质的顶点偏移钩子(`#pragma vertexoffset`、`vertexbounds`),Foliage 用它做摆动;阴影通道会带上同一份钩子。
+- `Terrain` 组件与 `sampleHeight`(`sdk/src/terrain/`),可选模块的注册方式(`addEntryPlugin`,`esengine/terrain` 子路径)。
+- 3D 物理的射线和重叠查询(`sdk/src/physics3d/Physics3DQueries.ts`)。
+
+**没有(这就是要补的)**
+- 波不位移几何,所以岸线、天际线和漂浮物都不受波影响。
+- 水面必须水平;倾斜或弯曲会按水平着色。
+- 水只折射不透明场景,水下的半透明物体看不到。
+- 没有大海(无限大、远近分级)、湖泊(边界与水位)、溪流河流(样条、流向、流速)。
+- 没有样条原语(搜索 `sdk/src`、`src/esengine` 没有 Spline)。
+- 没有浮力,没有水下效果,没有涟漪交互,没有焦散,没有岸边浪。
+- 没有任何创作工具:编辑器里没有水体面板,也没有边界或样条的编辑。
+
+## 2. RM-138 与"限制全部支持"的对照
+
+| 来源 | 要求 | 本设计的位置 |
+|---|---|---|
+| 卡片阶段一 | 通用水面组件、材质参数、法线波纹、Fresnel、深浅水颜色,平面反射可选 | W1 |
+| 卡片阶段二 | 深度吸收、折射、岸边泡沫,避免采样正在写入的颜色附件 | 已有,W7 补齐半透明 |
+| 卡片阶段三 | 流向、交互涟漪、水下效果、浮力;浮力独立于渲染模块 | W3、W4、W5、W6 |
+| 卡片编辑器 | 沿用 Details 与材质创作,先设计确认再实现 | W8,先出设计稿 |
+| 卡片架构 | 采样、反射、物理各有职责;2D 项目不带 3D 水体模块;复用画质档位 | §3、§7 |
+| 卡片验收 | 水平/倾斜、移动、遮挡、离屏、删除重建、设备恢复;两后端像素;帧耗时记录;导出回归 | §9 |
+| 限制 1 | 波不移动几何 | W1(位移几何) |
+| 限制 2 | 水面必须水平 | W1(用水体自己的上方向) |
+| 限制 3 | 只折射不透明场景 | W7 |
+| 限制 4 | 无浮力 | W4 |
+| 用户补充 | 大海、溪流 | W1(海)、W3(河)、W2(湖) |
+
+## 3. 架构
+
+**一个 `WaterBody` 组件,三种形态**(Ocean、Lake、River),外加共用的渲染底座。理由:三者的着色、深度、泡沫、水下、浮力是同一套,
+差别只在几何和流向的来源。不做三个组件,也不做一个"万能"组件加一堆互不相干的字段。
+
+```
+WaterBody { form: Ocean | Lake | River, level, waves[], material, quality… }
+ ├─ Ocean 以相机为中心的多级网格(clipmap),无边界
+ ├─ Lake 多边形边界 + 水位,与地形相交处自然收口
+ └─ River 沿 Spline 的条带 + 流向图 + 每点宽度与流速
+```
+
+**可选模块**:`esengine/water` 子路径,和 terrain、foliage、timeline 同一个方式(`addEntryPlugin`、`installOptionalPlugins`、
+`targetSupport` 的证据项、api-surface 快照)。2D 项目和只用 2D 的小游戏包不带它。
+
+**四个职责分开**(卡片要求),各自只通过一份契约说话:
+
+1. **水面采样契约 `WaterSurface`**:`sample(x, z, t) → { height, normal, flow, depth, inside }`。CPU 与着色器共用同一组波参数和同一个公式,
+ 所以浮力读到的高度就是屏幕上画出来的高度。这是整个系统的脊梁。
+2. **几何**:各形态产出网格;波位移用材质的顶点偏移钩子,公式与 CPU 采样一致。
+3. **着色**:现有 Water 着色器的延伸(流向、水下视角、焦散、交互涟漪作为输入)。
+4. **物理交互**:`Floating` 组件只依赖契约和 3D 物理,不依赖渲染模块。
+
+## 4. 分期
+
+估时按"一天一张卡、大卡两天"的口径,**是估计,不是承诺**。顺序按依赖排。
+
+**W0 · 文档章节与模块骨架(0.5 天)**
+- 把 Water 从 `materials.mdx` 搬到专门的章节 `graphics/water.mdx`(中英文),侧栏加入口,章节随各期实现增长,**只写已实现的**。
+- `esengine/water` 模块骨架与接线。
+
+**W1 · 水面组件、位移波、任意朝向、大海(2 天)**
+- `WaterBody` 组件与 `WaterSurface` 契约(CPU 波公式)。
+- Gerstner 波组,顶点偏移钩子位移几何,阴影与深度通道同步。
+- 水面用水体自己的上方向和世界法线着色,去掉"水平"假设;倾斜水面的反射裁剪跟随它的平面。
+- Ocean:以相机为中心的多级网格,远处波按距离淡出,天际线随波起伏。
+
+**W2 · 湖泊、岸线、水深图(2 天)**
+- Lake:多边形边界网格,水位。
+- 从 `Terrain`(以及碰撞体)烘一张水体局部的水深图:驱动波在岸边衰减、泡沫、颜色,而不是只靠屏幕深度。
+- 波到岸边收口,岸线有浪。
+
+**W3 · 样条与河流(3 天)**
+- 新原语 `Spline`(Bezier/Catmull、弧长参数化、每点宽度),这是河流和以后的路径、镜头轨道共用的基础。
+- River:条带网格,沿样条生成流向图,双相位流动 UV 着色,流速与宽度变化,岩石和落差处的泡沫。
+
+**W4 · 浮力(2 天)**
+- `Floating` 组件:多点采样 `WaterSurface`,通过 3D 物理施加浮力与阻尼;`inside` 判定供游泳、涉水使用。
+- 独立于渲染模块;在没有渲染的服务端也能跑。
+
+**W5 · 水下(2 天)**
+- 相机进入水体的判定(用契约),水下后处理:吸收雾、色偏、水线、从下往上看水面(全反射与斯涅尔窗)。
+
+**W6 · 交互涟漪与泡沫持久(2 天)**
+- 水体局部高度场(波动方程),WebGPU 走计算、WebGL2 走乒乓渲染;物体入水和移动产生涟漪与尾波;脚本接口 `disturb(pos, radius, strength)`。
+- 泡沫随时间衰减的持久层。
+
+**W7 · 半透明与水的顺序(2 天)**
+- 水面以下的半透明物体先于水绘制并进入场景拷贝,水面以上的在水之后,取代"只折射不透明场景"。
+
+**W8 · 创作工具(3 天,先设计)**
+- Details 面板、湖泊边界的点编辑、河流的样条工具(加点、拖点、宽度与流速手柄)、视口内预览。
+- **先出实际项目控件的设计稿并得到确认,再实现。** 同时按 Unity、Unreal 的真实字段来对照,不发明它们没有的抽象。
+
+**W9 · 焦散、画质档位、小游戏预算(2 天)**
+- 焦散投影到水下表面;画质三档(波数、反射分辨率、涟漪网格);低档与小游戏退化为不带位移与反射的轻量路径。
+
+**W10 · 验收(贯穿)**
+- 见 §9。
+
+合计约 20 天的量级。每一期都能单独交付,并各自附场景、门禁与文档。
+
+## 5. 数据模型草案
+
+```ts
+WaterBody {
+ form: 'ocean' | 'lake' | 'river'
+ level: number // 世界高度;倾斜时用 Transform
+ waves: { amplitude, wavelength, direction, steepness, speed }[] // Gerstner 组,上限由画质档位定
+ material: asset // builtin:water 或其实例
+ boundary?: Vec2[] // lake
+ spline?: entity // river
+ flowSpeed?: number // river 基准流速
+ quality: 'inherit' | 'low' | 'medium' | 'high'
+ reflection: 'environment' | 'planar'
+}
+```
+
+字段名与取值以 W1 的实现为准,上面只定形状。
+
+## 6. 与竞品的对照(未核实)
+
+- Unity HDRP 的水系统:同一组件分 Ocean/Sea、River、Pond 三种表面,有水排除体、电流图、水下;浮力靠示例。
+- Unreal 的 Water 插件:Ocean、Lake、River、Custom 四种水体,河与湖由样条描述,有水区域(Water Zone)管理多个水体,
+ 自带浮力组件与 Gerstner 波。
+- 两者都把"水体 = 一个有形态的组件,几何由样条或边界描述",与本设计一致。**官方文档未逐条核对。**
+
+## 7. 性能与画质
+
+- 复用现有画质档位与渲染缩放(RM-054)。波数、反射分辨率、涟漪网格、焦散都挂在档位上。
+- 反射降频由作者显式选择,默认不限制主场景帧率。
+- 大海网格用剔除和 LOD 控制三角形数;河流和湖泊只在可见时更新。
+- 所有优化以同设备同场景的实测 CPU/GPU 耗时、绘制次数和资源占用证明。
+
+## 8. 风险
+
+- **WebGL2 没有逐渲染目标的独立混合状态**,所以不做需要它的方案(例如加权混合 OIT);W6、W7 都按这个约束设计。
+- **位移几何与阴影、深度、运动矢量、反射通道的一致性**:每个通道都要用同一份钩子,否则波的阴影和倒影会错位。
+- **样条是新基础设施**,河流和以后的镜头轨道依赖它,范围要克制(只做 Bezier/Catmull 与弧长)。
+- **水深图的烘焙**依赖地形或碰撞体;没有地形时退回屏幕深度。
+- **涟漪的 WebGL2 路径**要在没有计算着色器的前提下限制网格大小。
+
+## 9. 验收(对应卡片)
+
+- 水平与倾斜水面、移动物体与相机、遮挡、离屏、删除重建、设备恢复,各有场景。
+- WebGL2 与 WebGPU 的固定机位像素验收,加动态场景;静态设计稿不算运行效果。
+- 同设备同场景记录反射开关与档位切换的 CPU/GPU 耗时、绘制次数、资源占用。
+- Web 与小游戏导出,旧项目回归;目标真机验收单独记录,不标整卡完成。
+- 契约的一致性测试:CPU 采样的高度与着色器位移的高度逐点相等(容差内)。
+
+## 10. 需要你确认的
+
+1. **一个 `WaterBody` 加三种形态**,还是三个独立组件。我建议前者。
+2. **样条作为独立原语先做**(W3),而不是只给河流做内部的曲线。我建议前者,因为镜头轨道等也要它。
+3. **W8 的界面设计稿**:确认本文范围后,我会先出实际控件的设计稿给你,再实现。