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.
水体系统设计(RM-138)
状态:W0 到 W10 已实现并在本机验收(见 9.1),目标真机未验收。写于 2026-10-23;下文第 1 到 8 节是当时的设计,保留原样。
2026-10-24 起,水的结构改为“水体区域”:水体不再各自建网格,而是作为输入烘进一个 WaterZone,由一个跟随相机的网格画出整个水面,见 §3.1;第 3、5 节里“每种形态各出网格”“水体自带材质与波参数”“倾斜水面”的说法已被取代。依据是本仓库当前代码和 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 的小游戏包不带它。
四个职责分开(卡片要求),各自只通过一份契约说话:
- 水面采样契约
WaterSurface:sample(x, z, t) → { height, normal, flow, depth, inside }。CPU 与着色器共用同一组波参数和同一个公式, 所以浮力读到的高度就是屏幕上画出来的高度。这是整个系统的脊梁。 - 几何:各形态产出网格;波位移用材质的顶点偏移钩子,公式与 CPU 采样一致。
- 着色:现有 Water 着色器的延伸(流向、水下视角、焦散、交互涟漪作为输入)。
- 物理交互:
Floating组件只依赖契约和 3D 物理,不依赖渲染模块。
3.1 现行架构:水体区域(2026-10-24 重构)
各形态各建一张网格时,河流流进湖或海的地方是两个表面的接缝:两个高度、两套波浪、河口处横着一条岸线泡沫、河带的边露在湖面上。重构后:
水体是输入,不是网格。 WaterBody 只留 form(Ocean/Lake/River)、sizeX、sizeZ、boundary、shoreWidth(三种形态都用)、flowSpeed(河)、waveHeight。
material、cellSize、cells、rings、waveLength、waveSpeed、waveDirection、ripples、rippleSize、rippleSpeed、rippleDamping、foamFade 移到区域上。
WaterZone 组件(sdk/src/water/zone.ts):sizeX、sizeZ(以实体为中心的区域,只看 x、z)、resolution(较长一边的纹素数)、material、
三个共用波参数、水面网格的 cellSize/cells/rings、涟漪五项。它把区域内所有水体烘成一张 WaterField,每个纹素存:
- 水面高度(湖的水位、河流曲线最近处的高度、海平面);
- 到最近岸线的有符号距离(水上为正),决定裁切与岸边泡沫;
- 波高(水体
waveHeight× 向岸与变浅的平静系数)及平静系数本身; - 水流(河流的,在起点和终点各一个河宽内渐入渐出),以及水在地形之上的深度。
两个水体相接处按纹素在各自内部的深浅加权混合(过渡一个半纹素),所以河口与湖、海之间没有接缝;湖和河优先,海取剩下的;没有水的纹素取最近水面的高度。
场景没有 WaterZone 时,自动给一个覆盖所有湖和河的隐式区域(组件默认值,格子放大到能从区域内任何位置覆盖整个区域);只有海时整个水面就是海。
只用找到的第一个 WaterZone、第一个海洋。海在区域外继续延伸(着色器参数 u_oceanOn/u_oceanLevel/u_oceanWaves)。烘焙在 CPU 上,水体、区域或地形变化时整张重烘。
一个水面。 buildOceanMesh 的多圈网格跟随相机,就是整个水面;顶点钩子逐纹素读区域的高度纹理(高低两字节编码,先解码再混合),场纹理(岸线距离、水流、平静系数)按线性过滤读取。
波由区域共用,每处的高度 = 水体 waveHeight × 岸边平静系数 × 天气(WeatherDrive.Wind)。
采样契约不变,数据源变了。 Waters.sample/disturb/rippleAt/heightAt 读同一张烘好的场;WaterSample.entity 是那里占水最多的水体。涟漪由区域保留(一个跟随相机的窗口),天气驱动下雨时雨滴落进涟漪。
取消的能力。 不再支持倾斜水面(水体只能绕上方向旋转);每水体一个材质改为每区域一个材质。移除的公开导出:ShoreField、UNKNOWN_DEPTH、GroundDepth、buildBoxMesh、buildRectMesh、
RectOptions、buildRiverMesh;新增 WaterZone、WaterField、currentShare(移到 zone.ts)、WaterZoneData、FieldSample 类型。
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. 数据模型草案
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 的实现为准,上面只定形状。现行字段见 §3.1(区域重构后)。
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 采样的高度与着色器位移的高度逐点相等(容差内)。
9.1 验收记录(2026-10-23,本机)
下面每一项都由编辑器检查或命令实测得到,环境是这台机器(Windows、Electron 隐藏窗口、集成显卡一类的软硬件,数字只在同机同场景内可比)。 目标真机没有验收,卡片不标整卡完成。
| 条目 | 结果 | 依据 |
|---|---|---|
| 水平与倾斜水面 | 通过 | water-body:几何边缘与公式在 3 像素内;倾斜水体单独验证 |
| 相机移动、离屏 | 通过 | water-lifecycle:相机移到 5000 个单位外,涟漪窗口跟到,水体仍在;回来后窗口回位 |
| 遮挡 | 通过 | water-lifecycle:水面上方的不透明方块的像素是方块自己的颜色;water-glass:半透明板按像素排序 |
| 删除重建、改形态 | 通过,无泄漏 | water-lifecycle:删除再重建 5 次,资源普查的纹理数(2)、纹理字节(246784)、着色器(11)、引用行(2)逐次相同;湖→海→河→湖后不增长 |
| 设备恢复 | 通过 | water-lifecycle(WebGL2):真实的上下文丢失与恢复后设备回到正常,湖的轮廓覆盖(0.621)和泡沫都与丢失前一致,日志无错误。WebGPU 设备没有可丢的上下文,不适用 |
| 两个后端的固定机位像素 | 通过 | water-body/look/under/river/float/ripple/glass/quality 在 WebGL2 和 WebGPU 都通过 |
| 契约一致性 | 通过 | water-body:CPU 公式与画出的几何;单元测试 water*.test.ts |
| 帧耗时 | 已记录 | 见下 |
| Web/小游戏导出 | 通过,有一条发现 | 见下 |
帧耗时(water-cost,编辑器视口,同一机位与太阳,floor 在水下;每帧毫秒;视口都跑满 60 fps):
| 无水 | 海 | 湖 | 湖+128 格涟漪 | 河 | |
|---|---|---|---|---|---|
| WebGL2 CPU / GPU | 0.37 / 0.57 | 0.45 / 1.98 | 0.63 / 4.23 | 0.89 / 5.09 | 0.64 / 2.88 |
| WebGPU CPU / GPU | 0.47 / 0.60 | 0.51 / 1.78 | 0.53 / 4.25 | 1.01 / 4.76 | 0.50 / 2.65 |
湖比海贵是因为它的水面铺满了视口(像素多),不是顶点多;128 格涟漪的 CPU 增量约 0.3 到 0.5 毫秒。反射开关与档位切换的前后对比没有量:water-quality 只验证档位改变了什么,没有记录它省了多少。
**注(2026-10-24):**区域重构取消了倾斜水面,验收表“水平与倾斜水面”一行的倾斜部分只是当时的记录;湖、海、河的耗时也是重构前每水体一张网格时量的,重构后没有重测。
导出(estella export,blank 模板加一个 WaterBody 的副本对比原模板,--minify,editor 的 wasm,只说量级):
| 不含水 | 含水 | 差 | |
|---|---|---|---|
| web 的 sdk 目录 | 1,513,617 | 1,530,867 | +17,250 字节 |
| wechat 的 game-bundle.js | 1,095,783 | 1,118,163 | +22,380 字节(2.0%) |
含水时才带 esengine/water 模块(导出里出现 sdk/water),不含水的包没有它。发现及处理:builtin:water 的着色器源码(约 38 KB)和 Terrain、Foliage、Hair、Skin、Eye 的(各 6 到 10 KB)原先都放在核心的 builtinShaders.ts 里,所以不含水的包也带着这些字符串,压缩不动字符串。已改成各模块安装时注册自己的模板(registerBuiltinShaderTemplate):水、地形、植被各随自己的模块,Hair、Skin、Eye 是新的 esengine/character-shaders 模块;导出时由材质的 shader: 'builtin:…' 决定带哪个模块。改后空白项目导出:web 的 sdk 目录 1,513,617 → 1,433,641 字节(−80 KB),WeChat 的 game-bundle.js 1,095,783 → 1,015,282 字节(−7.3%);含水的项目 wechat 1,118,163 → 1,078,127。完整入口(编辑器、node)仍然安装全部模块,所以它们的着色器目录不变。
仍留在核心的水:core-content 重新导出了水的组件与插件代码(WaterBody、WaterPlugin 等,让脚本能从 esengine 取到它们),所以不含水的包还带着这部分 JS(量级几十 KB 以内,未单独量)。
另一条发现:esengine/water 和 esengine/spline 子路径在 W8 之前一直没有被构建进 dist(package.json 写了出口,但 rolldown 与 rollup 的入口里没有它们),W8 已补上。
10. 需要你确认的
- 一个
WaterBody加三种形态,还是三个独立组件。我建议前者。 - 样条作为独立原语先做(W3),而不是只给河流做内部的曲线。我建议前者,因为镜头轨道等也要它。
- W8 的界面设计稿:确认本文范围后,我会先出实际控件的设计稿给你,再实现。