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): the acceptance record, with frame costs, export sizes and the findings

yhh196372333ddc
diff --git a/desktop b/desktop
index 5214b1553..ecaf8469b 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 5214b155343b8339b9a20611674e64a46ceca8d5
+Subproject commit ecaf8469bd358b1e543a11af22eaf6035f77cd2f
diff --git a/docs/WATER_DESIGN.md b/docs/WATER_DESIGN.md
index e58f0d969..1a664ba66 100644
--- a/docs/WATER_DESIGN.md
+++ b/docs/WATER_DESIGN.md
@@ -158,6 +158,42 @@ WaterBody {
- 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` 只验证档位改变了什么,没有记录它省了多少。
+
+**导出**(`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` 里,所以不含水的包也带着这 38 KB 字符串,压缩不动字符串。要让它们跟模块走,得改着色器模板表的注册方式(编辑器的着色器目录、管线的数据纹理审计、加载器都读这张表),是一件单独的事,这里没做。
+另一条发现:`esengine/water` 和 `esengine/spline` 子路径在 W8 之前一直没有被构建进 `dist`(`package.json` 写了出口,但 rolldown 与 rollup 的入口里没有它们),W8 已补上。
+
## 10. 需要你确认的
1. **一个 `WaterBody` 加三种形态**,还是三个独立组件。我建议前者。