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.

17.1 KB
Raw Blame

水体系统设计(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 的小游戏包不带它。

四个职责分开(卡片要求),各自只通过一份契约说话:

  1. 水面采样契约 WaterSurface:sample(x, z, t) → { height, normal, flow, depth, inside }。CPU 与着色器共用同一组波参数和同一个公式, 所以浮力读到的高度就是屏幕上画出来的高度。这是整个系统的脊梁。
  2. 几何:各形态产出网格;波位移用材质的顶点偏移钩子,公式与 CPU 采样一致。
  3. 着色:现有 Water 着色器的延伸(流向、水下视角、焦散、交互涟漪作为输入)。
  4. 物理交互: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. 需要你确认的

  1. 一个 WaterBody 加三种形态,还是三个独立组件。我建议前者。
  2. 样条作为独立原语先做(W3),而不是只给河流做内部的曲线。我建议前者,因为镜头轨道等也要它。
  3. W8 的界面设计稿:确认本文范围后,我会先出实际控件的设计稿给你,再实现。