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(perf): the cascades are not unculled, they are large

yhh1eff00d8a72e
diff --git a/docs/TERRAIN_WATER_GPU_COST.md b/docs/TERRAIN_WATER_GPU_COST.md
index 63f9340a1..640ea2bd9 100644
--- a/docs/TERRAIN_WATER_GPU_COST.md
+++ b/docs/TERRAIN_WATER_GPU_COST.md
@@ -267,4 +267,21 @@
**结论:这个示例已经在最便宜的一端,没有可以拿的。**一张 160 米的图在耗时和近处的画面上都不输级联;级联只会在“要看很远的阴影”时才值得,而且每多一个就是多画一遍投射体。如果要把阴影看到更远,代价是级联(2 个,到 200 米,约 +1 到 6 ms),不是把范围放大(免费,但纹素变粗)。
-**一个发现:**四个级联的阴影绘制数是一个级联的四倍多(默认 2163 对 642),说明每个级联都在画整个范围内的投射体,没有按各自那一段剔除;这是级联模式下耗时的来源,值得单独看,没有在这里改。
+**四个级联的阴影绘制数是一个级联的四倍多,这一点后来查清了,见下一节:不是剔除没做。**
+
+## 级联为什么都画了差不多所有的投射体(2026-10-26)
+
+**问题:**4 个级联的阴影绘制数是 1 个的 4 倍多,是不是每个级联都画了整个范围的投射体,没有按各自那一段剔除?
+
+**量法:**临时在 `executeShadowPass` 里给每张图记它收集到的绘制数和实例数,在 `buildShadowPlan` 里记每个级联的半径和投射距离(量完已拿掉,没有留在引擎里)。太阳范围改为 0,4 个级联,花海机位:
+
+| 设置 | 级联 | 半径(米) | 绘制数 | 实例数 |
+|---|---|---|---|---|
+| 到场景尽头(默认) | 0 / 1 / 2 / 3 | 89 / 173 / 339 / 1350 | 1076 / 1221 / 1221 / 1221 | 7872 / 9027 / 9027 / 9027 |
+| 到 200 米 | 0 / 1 / 2 / 3 | 15 / 31 / 66 / 224 | 151 / 439 / 984 / 1221 | 1345 / 3554 / 7269 / 9027 |
+
+**结论:剔除是做了的,而且是对的;绘制数多是因为级联太大。**每张图收集的是它那一段的包围球在光方向上拉出的柱体里的东西(一个投射体可以在柱体外的任何地方,只要它的影子落在这一段里,所以柱体要一直拉向光源)。这样到 200 米时第一级只收 151 个绘制,往后逐级变多,是剔除在起作用。默认的范围是“场景尽头”,这个世界有 28 公里宽的地形,四段的半径是 89、173、339、1350 米:第一段就已经包住了周围 120 米内所有植物能投影的范围,后面几段更是,所以每张图都收到几乎全部(最多 9027 个实例,受植物自己的阴影距离 120 米限制)。
+
+这也解释了为什么级联模式下近处的阴影不比一张图好:默认范围下第一级的纹素是 2 × 89 米 / 1024 ≈ 17 厘米,和一张 160 米的图(15.6 厘米)差不多。
+
+**能改的是 `shadowDistance`,不是剔除**:给个有限的值(这个示例到 200 米,第一级纹素约 3 厘米),级联才真的把近处分出去,绘制数也跟着降(默认机位 2163 → 805,花海 4739 → 2795);但前面的表说它仍比一张图贵 4 到 14 ms。把默认的“场景尽头”改成别的值会改变所有项目远处的阴影,没有在没有人看过画面的情况下动它。
diff --git a/tools/terrain-water-cost.mjs b/tools/terrain-water-cost.mjs
index b06769b2c..2d13a9bc4 100644
--- a/tools/terrain-water-cost.mjs
+++ b/tools/terrain-water-cost.mjs
@@ -237,6 +237,7 @@ try {
}
if (!r) { table[v.id] = { label: v.label, failed: true }; continue; }
table[v.id] = { label: v.label, ...r };
+ if (argv.includes('--probe')) console.log(' ' + Object.entries(r.counters).filter(([k]) => k.startsWith('probe.')).map(([k, x]) => `${k.replace('probe.', '')}=${x}`).join(' '));
console.log(`${v.id.padEnd(17)} ${r.ms.toFixed(2).padStart(7)} ms [${r.min.toFixed(2)}..${r.max.toFixed(2)}] cpu ${r.cpu.toFixed(2)} draws ${r.counters['batch.draws'] ?? '?'} shadow ${r.counters['render.shadow.draws'] ?? '?'} tris ${((r.counters['render.triangles'] ?? 0) / 1e6).toFixed(2)}M prepass ${r.counters['render.prepass.draws'] ?? '?'} (meshes taken ${r.counters['render.prepass.taken'] ?? '?'}, cut-out ${r.counters['render.prepass.cutout'] ?? '?'}, bent ${r.counters['render.prepass.bent'] ?? '?'}, none ${r.counters['render.prepass.noProgram'] ?? '?'}) ${r.errors.length ? 'ERRORS ' + r.errors[0] : ''}`);
}
} finally {