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.

fix(render): a depth program seeds the samplers a vertex hook reads, so the terrain takes part in the depth prepass with its own heights

yhhe33735b6899f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c6a9501c9..90b036d15 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ published separately; it ships inside the editor.
### Added
-- **A depth prepass for the opaque scene.** A quality level can draw the opaque meshes twice, depth alone first, so a pixel is shaded for the surface that is in front of it and not for every one drawn there on the way: `QualityProfile.depthPrepass` (on for `high` and `medium`, off for `low` and with the quality system off), and `renderer_setDepthPrepass` for a host without one. Cut-out leaves take part, with the coverage their own shader writes. The surfaces with a vertex hook (the terrain) do not. On the Terrain & Water example, on an RTX 3060, a frame is 4 to 36 ms shorter, most where trees stand thick.
+- **A depth prepass for the opaque scene.** A quality level can draw the opaque meshes twice, depth alone first, so a pixel is shaded for the surface that is in front of it and not for every one drawn there on the way: `QualityProfile.depthPrepass` (on for `high` and `medium`, off for `low` and with the quality system off), and `renderer_setDepthPrepass` for a host without one. Cut-out leaves take part, with the coverage their own shader writes. A surface whose material bends its vertices with a hook takes part too, unless it is also a cut-out. On the Terrain & Water example, on an RTX 3060, a frame is 4 to 39 ms shorter, most where trees stand thick.
- **A third mesh for a plant.** A part of a world's plants can name `lod2Mesh` and its kind `lod2Distance`: past that distance the third mesh stands in for the cheaper one, until the kind stops being drawn as itself. The Terrain & Water example's trees have one (a tenth of the triangles, made by `tools/plant-lod2.mjs`) from 80 m, which takes 9 to 15 ms off a frame on an RTX 3060 where trees stand between 60 and 170 m. `tools/terrain-water-cost.mjs` measures what each part of that example costs a frame headless, and `docs/TERRAIN_WATER_GPU_COST.md` has the numbers.
- **A generated world on worker threads.** A planet provider can give the engine its generator as `workerSource` (the text of a self-contained module), and the world's placements and the planet's pages (heights, normals, and the paint by the biomes) are then worked out by a pool of workers (`runtime/jobs.ts`), byte for byte what the main thread works out, while the main thread only puts each answer in the world as it arrives. Laying out a planet's world no longer costs the frame: 2 to 8 frames a second while it was laid out became 60.
- **A flat world's generation on worker threads too.** Laying out a `WorldGen` over a `Terrain` (a field or noise ground, with its baked water) is worked out by the same pool of workers, from the ground and the water handed over as data, byte for byte what the main thread works out. Stopping the terrain-water example no longer leaves the editor at 2 frames a second: it is back at 60.
@@ -32,6 +32,10 @@ published separately; it ships inside the editor.
- **A lit surface takes its shadow in fewer operations.** The shadow lookup of a light with a size (the sun's penumbra) worked a `sin`, a `cos` and a `sqrt` for each of its forty-eight taps and a whole matrix for each of the sixteen that look for a blocker; the taps are a table now, turned once a pixel, and the matrix is applied to the light's direction once. Inside a shadow, where every blocker tap hits, it returns at once, and a penumbra a texel or two wide is averaged over 8 or 16 taps, not 32. The picture is the same to the pixel gates on WebGL2 and WebGPU; a frame of the Terrain & Water example is 3 to 10 ms shorter on an RTX 3060.
+### Fixed
+
+- **A material's vertex hook reads its own textures when it casts a shadow.** The program a caster is drawn with into a shadow map had its texture samplers left on unit 0, so a hook that reads a texture (the terrain's height pages) read another texture there, and the terrain cast the shadow of heights that were not its own. The samplers are set on the units the material declares them on, as the program it is drawn with in colour has them.
+
## [0.95.0] - 2026-10-25
### Added
diff --git a/docs/TERRAIN_WATER_GPU_COST.md b/docs/TERRAIN_WATER_GPU_COST.md
index cc25974f3..7da2ef1d5 100644
--- a/docs/TERRAIN_WATER_GPU_COST.md
+++ b/docs/TERRAIN_WATER_GPU_COST.md
@@ -130,7 +130,7 @@
- `DrawList::execute` 多了 `DrawPass`:先 `DepthPrepass`,再 `ColorAfterPrepass`(参与的 draw 用 `depthEqual`、不再写深度)。
- 质量档位加 `depthPrepass`:high、medium 开,low 关,质量系统关掉时也关。分块 GPU(手机)上这一遍是几何画两次,所以默认不开。
-**没做的:**顶点被材质弯曲的 draw(地形、风吹的植被)不参加。试过让地形的深度程序走 `shadowProgram`,中远景地形块的深度与着色那遍对不上,整块不画出来;原因没有查清,所以关掉了(默认机位去掉它没有损失,地形自己没有过度绘制)。
+**带顶点钩子的材质**(地形)一开始被排除了:让地形的深度程序走 `shadowProgram`,中远景地形块的深度与着色那遍对不上,整块不画出来。原因见下一节,后来修好,地形现在也参加。
**同一个包里的开关前后**(`no-prepass` 是 `depthPrepass: false`,RTX 3060,1080p,每个值 5 组 12 帧):
@@ -147,3 +147,27 @@
**检查:**帧对比没有看到空洞或光晕;与上一个构建的像素差,树和花的带状区域有 0.12% 的像素差大于 24,在同一个包两次运行 0.01% 的参照之上,看截图是远处镂空卡片边缘的取样不同,和重叠的共面卡片在 `LEQUAL` 下谁盖谁。像素验收:原来的 128 个网格/阴影/深度/天空相关的场景在 WebGL2 通过、WebGPU 通过(`device-loss-*` 的四个在 WebGPU 上先前就失败);新增 11 个 `*-prepass` 孪生场景(同一画面、预通道开着,并要求至少有一个 draw 参加),WebGL2 与 WebGPU 都通过。WebGPU 上没有量帧耗时。
**限制:**只在一块 NVIDIA 显卡的 D3D11 上量过;预通道要求两个程序的位置逐位相同,靠 `invariant` 保证,在别的驱动上没有试过(出问题时的表现是着色那遍的像素被深度测试挡掉,画面上有洞)。
+
+## 地形为什么对不上(2026-10-26)
+
+`MaterialStore::variantProgram`(着色那遍的程序)建好之后调 `seedSamplers`:把材质用 `#pragma param … texture` 声明的采样器设到它声明的纹理单元上。`shadowProgram`(深度程序,阴影图用,预通道也用)建好之后**没有**调,所以它的采样器全是默认的 0 号单元。地形的顶点钩子读 `u_heightPages`(高度页),深度程序读到的是 0 号单元上别的纹理,顶点的高度错了,写进预通道的深度和着色那遍的深度就不是同一个。近处的块高度页恰好和 0 号单元差得不大,中远景的块整块落在深度测试之外,画不出来。
+
+修法是一行:`shadowProgram` 建好程序后同样 `seedSamplers(*shader, material)`。
+
+**这也是一个旧的阴影缺陷:**地形(和任何顶点钩子读纹理的材质)往阴影图里画时一直在读 0 号单元的纹理,所以它投出的阴影用的不是它自己的高度。修好之后阴影图里的地形才是画面里的地形。WebGPU 的纹理按组与单元绑定,没有这个问题。
+
+**防回归:**夹具 `prepass-hook`:一个立方体,材质的顶点钩子读一张黑纹理把顶点往眼睛方向抬(网格自己的纹理是白的)。程序读对了纹理,立方体不动,画出来;读成 0 号单元的白纹理,深度程序把它抬走,着色那遍的深度测试挡掉整个立方体。`prepass-hook`(无预通道)和 `prepass-hook-prepass` 两个场景,WebGL2 与 WebGPU 都通过;把 `seedSamplers` 那一行拿掉重编,WebGL2 上 `prepass-hook-prepass` 变红、`prepass-hook` 仍是绿的。
+
+**地形参加之后的帧耗时**(`no-prepass` 对比,同一个包;这一轮机器比前几轮热,绝对值偏高):
+
+| 机位 | 没有预通道 ms | 有预通道 ms | 差 |
+|---|---|---|---|
+| 默认 | 34.0 | 30.2 | −3.8 |
+| 花海 | 81.5 | 42.6 | −39.0 |
+| 湖边 | 88.0 | 60.4 | −27.6 |
+| 湖与河口 | 71.9 | 48.0 | −23.9 |
+| 沿河 | 57.3 | 42.2 | −15.1 |
+
+和地形不参加时(上一节)比,差别在机器的波动里:地形自己几乎没有过度绘制,所以它参加与否对速度没有可见影响;这一步的意义是:任何带顶点钩子的不透明材质(风吹的植被、被弯曲的网格)现在都能参加预通道,且深度是对的。
+
+镂空且带顶点钩子的材质仍不参加(它的覆盖率程序只为 `Model` 着色器写)。
diff --git a/fixtures/scenes/prepass-hook.esscene b/fixtures/scenes/prepass-hook.esscene
new file mode 100644
index 000000000..9ec480e12
--- /dev/null
+++ b/fixtures/scenes/prepass-hook.esscene
@@ -0,0 +1,78 @@
+{
+ "version": 4,
+ "name": "PrepassHook",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 400
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 200,
+ "nearPlane": 1,
+ "farPlane": 2000,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Panel",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 3.0,
+ "z": 0.2
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "opaque": true,
+ "lit": false,
+ "cullBackfaces": true,
+ "material": "/scenes/prepass-hook/hook.esmaterial",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/fixtures/scenes/prepass-hook/hook.esmaterial b/fixtures/scenes/prepass-hook/hook.esmaterial
new file mode 100644
index 000000000..cf39a0af6
--- /dev/null
+++ b/fixtures/scenes/prepass-hook/hook.esmaterial
@@ -0,0 +1,11 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "hook.esshader",
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true,
+ "properties": {
+ "u_tint": { "r": 0, "g": 1, "b": 0, "a": 1 }
+ }
+}
diff --git a/fixtures/scenes/prepass-hook/hook.esshader b/fixtures/scenes/prepass-hook/hook.esshader
new file mode 100644
index 000000000..93205a64d
--- /dev/null
+++ b/fixtures/scenes/prepass-hook/hook.esshader
@@ -0,0 +1,142 @@
+#pragma shader "PrepassHook"
+#pragma version 300 es
+#pragma domain Lit
+#pragma param u_lift texture default(black)
+#pragma param u_liftBy float default(40)
+#pragma param u_tint color default(0,1,0,1)
+
+// A vertex hook that reads a texture, as the terrain's does: it lifts a vertex toward the eye by what the texel says. The texture is black, so
+// nothing is lifted — unless a program reads another unit's texture for it (the mesh's own is white), which lifts the depth a prepass writes off
+// the depth the colour pass lands on, and the cube is not drawn at all.
+#pragma vertexoffset
+void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {
+ local.z += texelFetch(u_lift, ivec2(0), 0).r * u_liftBy;
+}
+#pragma end
+
+#pragma vertexoffset wgsl
+fn esMaterialVertex(local : ptr<function, vec3f>, localNormal : ptr<function, vec3f>, uv : vec2f) {
+ (*local).z = (*local).z + textureLoad(u_lift, vec2i(0), 0).r * mc.u_liftBy;
+}
+#pragma end
+
+#pragma fragment
+precision mediump float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+
+out vec4 fragColor;
+
+void main() {
+ fragColor = vec4(u_tint.rgb, 1.0);
+}
+#pragma end
+
+#pragma fragment wgsl full
+// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
+// Regenerate after changing the GLSL stages above.
+// source-hash: 946c59b289c94f25
+// assembled-hash: 490053aeb58d469e
+struct MaterialConstants {
+ u_liftBy: f32,
+ u_tint: vec4<f32>,
+}
+
+struct FrameConstants {
+ u_projection: mat4x4<f32>,
+ u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
+ u_renderOrigin: vec4<f32>,
+}
+
+struct TimeConstants {
+ u_time: vec4<f32>,
+ u_viewport: vec4<f32>,
+}
+
+struct Light {
+ posDir: vec4<f32>,
+ color: vec4<f32>,
+ spot: vec4<f32>,
+ shadow: vec4<f32>,
+ shadowMap: vec4<f32>,
+ falloff: vec4<f32>,
+}
+
+struct LightConstants {
+ u_ambient: vec4<f32>,
+ u_lights: array<Light, 16>,
+ u_mask2DRect: vec4<f32>,
+ u_shadowMatrix: array<mat4x4<f32>, 16>,
+ u_shadowTile: array<vec4<f32>, 16>,
+ u_shadowParams: vec4<f32>,
+ u_envIrradiance: array<vec4<f32>, 9>,
+ u_envParams: vec4<f32>,
+ u_envTint: vec4<f32>,
+ u_reflParams: vec4<f32>,
+ u_reflBox: array<vec4<f32>, 30>,
+ u_bakedTint: vec4<f32>,
+ u_tiledLights: array<Light, 96>,
+ u_tileMask: array<vec4<u32>, 192>,
+ u_tileInfo: vec4<f32>,
+}
+
+struct ProbeConstants {
+ u_probeIrradiance: array<vec4<f32>, 1000>,
+ u_probeTail: vec4<f32>,
+}
+
+struct PlanarConstants {
+ u_planarProjection: mat4x4<f32>,
+ u_planarParams: vec4<f32>,
+}
+
+var<private> g_hairShadow: f32;
+var<private> fragColor: vec4<f32>;
+@group(0) @binding(1)
+var<uniform> unnamed: MaterialConstants;
+@group(0) @binding(0)
+var<uniform> unnamed_1: FrameConstants;
+@group(0) @binding(3)
+var<uniform> unnamed_2: TimeConstants;
+@group(1) @binding(16)
+var u_lift_est: texture_2d<f32>;
+@group(1) @binding(24)
+var u_lift_ess: sampler;
+@group(0) @binding(2)
+var<uniform> unnamed_3: LightConstants;
+@group(0) @binding(7)
+var<uniform> unnamed_4: ProbeConstants;
+@group(0) @binding(9)
+var<uniform> unnamed_5: PlanarConstants;
+var<private> v_probeSlot_1: f32;
+@group(1) @binding(7)
+var u_shadow2D_est: texture_2d<f32>;
+@group(1) @binding(15)
+var u_shadow2D_ess: sampler;
+@group(1) @binding(6)
+var u_lightShape2D_est: texture_2d<f32>;
+@group(1) @binding(14)
+var u_lightShape2D_ess: sampler;
+var<private> v_color_1: vec4<f32>;
+var<private> v_texCoord_1: vec2<f32>;
+
+fn main_1() {
+ g_hairShadow = 0f;
+ let _e198 = unnamed.u_tint;
+ let _e199 = _e198.xyz;
+ fragColor = vec4<f32>(_e199.x, _e199.y, _e199.z, 1f);
+ return;
+}
+
+@fragment
+fn fs_main(@location(6) @interpolate(flat) v_probeSlot: f32, @location(0) v_color: vec4<f32>, @location(1) v_texCoord: vec2<f32>) -> @location(0) vec4<f32> {
+ v_probeSlot_1 = v_probeSlot;
+ v_color_1 = v_color;
+ v_texCoord_1 = v_texCoord;
+ main_1();
+ let _e7 = fragColor;
+ return _e7;
+}
+#pragma end
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index c949687ee..9e7102727 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -1066,8 +1066,10 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
if (key.depthShaderId != 0) ++prepassTaken; else ++prepassCutout;
} else {
if (key.materialId != 0 && ctx.materials && ctx.materials->hasVertexHook(key.materialId)) {
- // A material that bends its vertices: left out until its depth is shown to be the colour pass's own.
- ++prepassBent;
+ // A material that bends its vertices: the depth program carries the same bend.
+ key.depthShaderId = ctx.materials->shadowProgram(key.materialId, ctx.resources, resident->hasNormals, skinned,
+ resident->hasTangents);
+ if (key.depthShaderId != 0) ++prepassTaken; else ++prepassBent;
} else {
const u32 depthVariant = meshDrawFor(ctx, registry, entity, mesh, resident, true, warned_bones_).variant;
key.depthShaderId = meshProgram(ctx, depthVariant);
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index 411a49f81..b4fbb8185 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -163,6 +163,8 @@ u32 MaterialStore::shadowProgram(u32 materialId, resource::ResourceManager& reso
variants[shape] = {};
return 0;
}
+ // The samplers the hook reads (the terrain's height pages) sit on the units the material declares them on; a program left unseeded reads unit 0.
+ seedSamplers(*shader, material);
const u32 program = shader->getProgramId();
variants[shape] = handle;
return program;
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b7db28710..8b74d32f5 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2982,4 +2982,6 @@ export const NOTED = {
{"note":"A lit surface takes its shadow in fewer operations."},
"feat(render): the opaque scene can be drawn twice, depth alone first, so a pixel is shaded for the surface in front of it":
{"note":"A depth prepass for the opaque scene."},
+ "fix(render): a depth program seeds the samplers a vertex hook reads, so the terrain takes part in the depth prepass with its own heights":
+ {"note":"A material's vertex hook reads its own textures when it casts a shadow."},
};
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 55a1a4250..df5389f43 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -680,6 +680,8 @@ export const SCENES = [
// A GENERATED twin on a mesh. A generated vertex stage is frozen at the batch
// source, so WebGPU refused the pipeline; the two halves read the uv varying.
{ id: "mat-generated-mesh", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-generated-mesh.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.3,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.7,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },
+ // A vertex hook that reads a texture (the terrain's way of lifting a vertex): the cube stands where the hook puts it, and is drawn.
+ { id: "prepass-hook", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/prepass-hook.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },
{ id: "mat-decal-flat", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-decal-flat.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },
{ id: "mesh-material", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_ASSET: "/scenes/white-triangles.esmesh", ESTELLA_VERIFY_MESH_MATERIAL: "/scenes/mesh-material/tintonly.esmaterial", ESTELLA_VERIFY_SCENE: "/scenes/mesh-material.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-material.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.30,\"y\":0.556,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.5,\"y\":0.12,\"rgb\":[0,0,0],\"tol\":30}]" } },
// What a normal is FOR: two coplanar triangles, one white colour, normals
@@ -908,7 +910,7 @@ export const SCENES = [
*/
const PREPASS_TWINS = [
// Scenes that draw opaque meshes already.
- 'mesh-opaque', 'mesh-instanced', 'corpus-cutout-edge', 'mesh-normalmap', 'mesh-shadow-cutout', 'mesh-shadow', 'sun-shadow',
+ 'mesh-opaque', 'mesh-instanced', 'prepass-hook', 'corpus-cutout-edge', 'mesh-normalmap', 'mesh-shadow-cutout', 'mesh-shadow', 'sun-shadow',
// The same scenes with their meshes made opaque (fixtures/scenes/*-opaque.esscene), for what a mesh can be besides a rigid one that is lit:
// skinned, morphing.
{ id: 'mesh-skin', scene: 'mesh-skin-opaque.esscene' }, { id: 'mesh-morph-shaped', scene: 'mesh-morph-opaque.esscene' },