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(render): the cascades and the shadow distance act only on a sun with no extent, and what each setting costs the Terrain & Water example

yhh74bbd4496da1
diff --git a/docs/TERRAIN_WATER_GPU_COST.md b/docs/TERRAIN_WATER_GPU_COST.md
index a4ab63976..63f9340a1 100644
--- a/docs/TERRAIN_WATER_GPU_COST.md
+++ b/docs/TERRAIN_WATER_GPU_COST.md
@@ -236,3 +236,35 @@
多重采样关掉后水的成本:默认机位 3.0 → 2.4,沿河 3.1 → 6.1(这一组的基准漂得厉害,不下结论)。
**结论:不值得现在优化。**水一共 1 到 5 ms(平均 2.7),是这个示例里最小的一块(植物 22 到 68,阴影 12 到 38,多重采样 5 到 8),而且没有一个现成的旋钮可以动它。真要动,杠杆只有两个,都得先单独量:折射用的场景拷贝(缩小分辨率或只拷水面范围),和水面片元里的反射步进(20 步)。
+
+## 阴影范围:级联数与 shadowDistance(2026-10-26)
+
+**先说一个前提:这个示例的太阳有固定范围**(`shadowExtent: 16000`,即 160 米),阴影是**一张**那么大的图,`shadowCascades` 和 `shadowDistance` 在它身上不起作用(`ext16-casc-1` 与基准一样:+0.1、+0.6、−0.1、−1.9 ms,噪声)。级联只在太阳的 `shadowExtent` 为 0 时才有(阴影按视锥切成几段),所以下面的“级联”各行都把太阳的范围改成了 0。
+
+帧耗时,相对基准(基准:默认 28.4、花海 38.7、湖边 41.1、湖与河口 42.3 ms;每个值 4 组 12 帧):
+
+| 设置 | 默认 | 花海 | 湖边 | 湖与河口 | 阴影绘制数(默认 / 花海) |
+|---|---|---|---|---|---|
+| 示例原样(一张 160 米的图) | 0 | 0 | 0 | 0 | 432 / 1221 |
+| 范围 80 米(一张图) | −0.5 | +1.0 | 0 | −2.2 | 144 / 1069 |
+| 范围 320 米(一张图) | +0.4 | +0.1 | −0.8 | −2.3 | 641 / 1221 |
+| 1 级联,到场景尽头 | +1.0 | −0.2 | −1.2 | −2.5 | 642 / 1221 |
+| 2 级联 | +2.6 | +4.7 | +4.5 | +2.9 | 1262 / 2442 |
+| 3 级联 | +3.4 | +8.3 | +10.0 | +7.4 | 1659 / 3606 |
+| 4 级联 | +10.6 | +12.2 | +14.1 | +11.1 | 2163 / 4739 |
+| 4 级联,到 100 米 | +2.7 | +8.3 | +7.9 | +8.3 | 395 / 1941 |
+| 4 级联,到 200 米 | +3.8 | +10.3 | +11.0 | +14.0 | 805 / 2795 |
+| 4 级联,到 400 米 | +4.5 | +13.1 | +13.8 | +15.7 | 1253 / 3789 |
+| 2 级联,到 100 米 | +2.1 | +2.7 | +1.9 | +3.9 | 381 / 1357 |
+| 2 级联,到 200 米 | +1.2 | +3.1 | +4.0 | +5.8 | 643 / 1733 |
+
+**耗时跟着阴影图里重画的投射体走**(阴影绘制数栏):每多一个级联,树和草就在那一张图里再画一遍,植物这样稠的场景里一个级联就是 3 到 4 ms。一张图的范围(80 米、160 米、320 米)几乎不花钱,因为投射体只画一遍。
+
+**画面差别**(同一个包,相对原样;两次运行之间云和水就会变,所以只数两次基准里都不变的像素;对照是“什么也没改”的 `ext16-casc-1`,平均差 0.3 到 0.6,差大于 24 的像素 0%,湖与河口那一视角对照本身就有 2.0):
+
+- 2 到 4 个级联、到不同距离、一张 80 米或 320 米的图:平均差 1.0 到 2.6(湖与河口 4.2 到 6.1,那一视角的对照本身是 2.0),差大于 24 的像素 0.3% 到 1.3%(湖与河口 1.9% 到 3.9%)。截图里(花海近处的树下)看不出区别:近处的软阴影和原样一样。
+- **1 个级联明显更差**(平均差 2.7 到 7.7,差大于 24 的像素 2.3% 到 6.9%):一个级联铺满整个视野,纹素太粗,近处地面上的树影整片没有了。
+
+**结论:这个示例已经在最便宜的一端,没有可以拿的。**一张 160 米的图在耗时和近处的画面上都不输级联;级联只会在“要看很远的阴影”时才值得,而且每多一个就是多画一遍投射体。如果要把阴影看到更远,代价是级联(2 个,到 200 米,约 +1 到 6 ms),不是把范围放大(免费,但纹素变粗)。
+
+**一个发现:**四个级联的阴影绘制数是一个级联的四倍多(默认 2163 对 642),说明每个级联都在画整个范围内的投射体,没有按各自那一段剔除;这是级联模式下耗时的来源,值得单独看,没有在这里改。
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index 859de5fc4..7749a2fcd 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -17,6 +17,10 @@ export interface QualityProfile {
msaaSamples: 1 | 2 | 4 | 8;
shadowAtlasSize: number;
shadowCellSize: number;
+ /**
+ * The cascades a perspective sun's shadow is split into, and how far (in world units, 0 for as far as the scene reaches) they reach. Both act only on
+ * a sun whose `shadowExtent` is 0: one with an extent draws a single map of that size and uses neither. Each cascade draws the casters again.
+ */
shadowCascades: number;
shadowDistance: number;
/**
diff --git a/tools/terrain-water-cost.mjs b/tools/terrain-water-cost.mjs
index 7582db868..b06769b2c 100644
--- a/tools/terrain-water-cost.mjs
+++ b/tools/terrain-water-cost.mjs
@@ -67,6 +67,7 @@ const noLayer = (layer) => (w) => { for (const b of w.biomes) b.recipes = b.reci
const forParts = (fn) => (w) => { for (const p of Object.values(w.plants)) for (const part of [...p.parts, ...(p.far ?? [])]) fn(part); };
const TREES = ['oak', 'beech', 'birch', 'willow', 'pine-ridge', 'pine-lakeside'];
const trees = (fn) => (w) => { for (const k of TREES) fn(w.plants[k]); };
+const sun = (fn) => (d) => { for (const l of comp(d, 'Light')) if (l.data.type === 1) fn(l.data); };
const quality = (level, profile) => (cfg) => { cfg.quality = { ...cfg.quality, mode: level, ...(profile ? { profiles: { [level]: profile } } : {}) }; };
/** Each variant: what to take away, relative to `base`. Edits to the scene, or to the package's quality config. */
@@ -117,6 +118,14 @@ const VARIANTS = [
{ id: 'msaa-2-nofxaa', label: 'msaa 2x, no fxaa', config: quality('high', { msaaSamples: 2, skipEffects: ['fxaa'] }) },
{ id: 'msaa-4-nofxaa', label: 'msaa 4x, no fxaa', config: quality('high', { skipEffects: ['fxaa'] }) },
{ id: 'msaa-2', label: 'msaa 2x', config: quality('high', { msaaSamples: 2 }) },
+ // The sun's shadow: the example's sun has a fixed extent (one map of that size), which leaves the cascades and the distance unused; extent 0 gives
+ // the sun cascades split over the view, `shadowCascades` of them out to `shadowDistance` (0: as far as the scene reaches).
+ { id: 'ext-8000', label: 'one shadow map of half the extent', scene: sun((l) => { l.shadowExtent = 8000; }) },
+ { id: 'ext-32000', label: 'one shadow map of twice the extent', scene: sun((l) => { l.shadowExtent = 32000; }) },
+ { id: 'ext16-casc-1', label: 'authored extent, one cascade requested (unused)', config: quality('high', { shadowCascades: 1 }) },
+ ...[1, 2, 3, 4].map((n) => ({ id: `casc-${n}`, label: `cascades: ${n}, as far as the scene reaches`, scene: sun((l) => { l.shadowExtent = 0; }), config: quality('high', { shadowCascades: n }) })),
+ ...[10000, 20000, 40000].map((m) => ({ id: `casc-4-d${m / 100}`, label: `cascades: 4, out to ${m / 100} m`, scene: sun((l) => { l.shadowExtent = 0; }), config: quality('high', { shadowCascades: 4, shadowDistance: m }) })),
+ ...[10000, 20000].map((m) => ({ id: `casc-2-d${m / 100}`, label: `cascades: 2, out to ${m / 100} m`, scene: sun((l) => { l.shadowExtent = 0; }), config: quality('high', { shadowCascades: 2, shadowDistance: m }) })),
{ id: 'cascades-2', label: 'two shadow cascades', config: quality('high', { shadowCascades: 2 }) },
{ id: 'atlas-2048', label: 'shadow atlas 2048', config: quality('high', { shadowAtlasSize: 2048, shadowCellSize: 512 }) },
{ id: 'scale-75', label: 'render scale 0.75', config: quality('high', { renderScale: 0.75 }) },