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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(render): a shadow pass draws depth, not what the material says
yhh701df0cf4763
diff --git a/desktop/public/scenes/mesh-shadow-material.esscene b/desktop/public/scenes/mesh-shadow-material.esscenenew file mode 100644index 000000000..96e3dce2a--- /dev/null+++ b/desktop/public/scenes/mesh-shadow-material.esscene@@ -0,0 +1,150 @@+{+ "version": 1,+ "name": "MeshShadowMaterial",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 10+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 300,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Ground",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": -200+ },+ "scale": {+ "x": 600,+ "y": 600,+ "z": 1+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "/scenes/shadow-quad.esmesh",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Blocker",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 150,+ "y": 150,+ "z": 1+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "/scenes/shadow-quad.esmesh",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "enabled": true,+ "material": "/scenes/mesh-shadow-material/blockmat.esmaterial"+ }+ }+ ]+ },+ {+ "id": 3,+ "name": "Sun",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Light2D",+ "data": {+ "type": 1,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "intensity": 1,+ "direction": {+ "x": 0.5,+ "y": 0+ },+ "meshShadows": true+ }+ }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/mesh-shadow-material/blockmat.esmaterial b/desktop/public/scenes/mesh-shadow-material/blockmat.esmaterialnew file mode 100644index 000000000..1f4b27b18--- /dev/null+++ b/desktop/public/scenes/mesh-shadow-material/blockmat.esmaterial@@ -0,0 +1,9 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "blockmat.esshader",+ "blendMode": 0,+ "depthTest": true,+ "depthWrite": true,+ "properties": {}+}diff --git a/desktop/public/scenes/mesh-shadow-material/blockmat.esshader b/desktop/public/scenes/mesh-shadow-material/blockmat.esshadernew file mode 100644index 000000000..c131bbf31--- /dev/null+++ b/desktop/public/scenes/mesh-shadow-material/blockmat.esshader@@ -0,0 +1,24 @@+#pragma shader "BlockerMaterial"+#pragma version 300 es+#pragma domain Unlit2D++#pragma fragment+precision mediump float;++out vec4 fragColor;++// A constant, so the pixel says one thing only: the material ran, in the pass it+// belongs to. What it must NOT do is run in the shadow pass — an occluder there+// writes packed depth, and a material that reached it would write this red into+// the atlas instead (and sample the atlas it was writing, through the shadow+// sampler its mesh variant declares).+void main() {+ fragColor = vec4(1.0, 0.0, 0.0, 1.0);+}+#pragma end++#pragma fragment wgsl+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ return vec4f(1.0, 0.0, 0.0, 1.0);+}+#pragma enddiff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cppindex fea0879a5..63d78d11e 100644--- a/src/esengine/renderer/draw/DrawList.cpp+++ b/src/esengine/renderer/draw/DrawList.cpp@@ -234,22 +234,14 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,if (stencil != GfxStencilMode::Off) {device.setStencilReference(cmd.stencil_ref);}- // The batch shader declares 8 samplers, and WebGL2 invalidates a draw if any- // referenced sampler unit lacks a complete texture — even units the per-vertex- // branch never samples. For the Batch layout, fill the unused slots with a- // STABLE white texture: those units then stay pinned across draws, so the- // per-slot bind cache makes them no-ops and only slot 0 rebinds per texture- // change (filling with this draw's own tex re-pointed all 8 units each time).- // Other layouts bind only the samplers they declare.- if (cmd.layout_id == LayoutId::Batch) {+ // A draw that samples binds every unit its shader declares, not only the+ // ones it reads: an untouched unit holds what the last draw put there, in+ // any pass. The fill is a STABLE white, so unused units cost no rebind.+ if (cmd.texture_count > 0) {for (u8 slot = 0; slot < MAX_CMD_TEXTURE_SLOTS; ++slot) {u32 tex = (slot < cmd.texture_count) ? cmd.texture_ids[slot] : white_texture_id;device.bindTexture(slot, TextureHandle{tex});}- } else {- for (u8 slot = 0; slot < cmd.texture_count; ++slot) {- device.bindTexture(slot, TextureHandle{cmd.texture_ids[slot]});- }}if (cmd.hasPersistentGeometry()) {diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex a47369f2d..37b7336b4 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -248,19 +248,6 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {}if (mesh.cullBackfaces) key.cull = static_cast<u8>(CullMode::Back);- // Casting into a shadow map: every occluder is opaque and depth-tested for- // this pass whatever it is in the camera's, because the map holds the- // NEAREST occluder and a blended one would let a later draw overwrite it.- if (ctx.shadow_pass) {- key.stage = RenderStage::Opaque;- key.blend = BlendMode::None;- key.depthTest = true;- key.depthWrite = true;- key.materialId = 0;- key.shadowTextureId = 0;- key.envTextureId = 0;- }-// Material resolve mirrors SpritePlugin: an unregistered handle falls back to// the default batch shader; a material owns shading fully, so it takes// precedence over the lit toggle.@@ -278,6 +265,19 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {if (litProgram != 0) key.shaderId = litProgram;}+ // Casting into a shadow map: opaque and depth-tested whatever the camera's+ // pass makes it, and none of the three ways to describe a surface — lit, a+ // normal map, a material. LAST, so the pass outranks all three.+ if (ctx.shadow_pass) {+ key.stage = RenderStage::Opaque;+ key.blend = BlendMode::None;+ key.depthTest = true;+ key.depthWrite = true;+ key.materialId = 0;+ key.shadowTextureId = 0;+ key.envTextureId = 0;+ }+// Resident geometry: only the transform is written for the frame. Its// vertices are local-space and untouched, so the CPU loop below — which// exists to bake world space into every vertex — is skipped entirely.diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 282f6065c..9656ec850 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -1481,7 +1481,13 @@ void WebGPUDevice::flushBindGroup() {WGPUBindGroupEntry texEntries[kTextureSlots * 2];u32 texCount = 0;for (u32 unit = 0; unit < kTextureSlots; ++unit) {- auto it = textures_.find(texture_slots_[unit]);+ // A pass may not sample what it draws into: WebGPU rejects the whole+ // COMMAND BUFFER for it, not the draw. The dummy stands in — reading+ // one's own attachment is undefined under every backend anyway.+ const u32 bound = texture_slots_[unit];+ const bool feedback = bound != 0 && (bound == pass_color_texture_ ||+ bound == pass_depth_texture_);+ auto it = feedback ? textures_.end() : textures_.find(bound);const TextureRec* rec = (it != textures_.end()) ? &it->second : dummy;if (!rec) continue;const u32 tb = textureBindingForUnit(unit);@@ -1580,6 +1586,8 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {WGPUTextureView dsView = nullptr;pass_ds_format_ = WGPUTextureFormat_Undefined;pass_color_format_ = surface_format_;+ pass_color_texture_ = 0;+ pass_depth_texture_ = 0;pass_is_surface_ = desc.target == FramebufferHandle::Default;if (desc.target != FramebufferHandle::Default) {auto fbIt = framebuffers_.find(static_cast<u32>(desc.target));@@ -1594,6 +1602,7 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {}targetView = texIt->second.view;pass_color_format_ = texIt->second.format;+ pass_color_texture_ = fbIt->second.color0;pass_width_ = texIt->second.width;pass_height_ = texIt->second.height;if (fbIt->second.depthStencil != 0) {@@ -1601,6 +1610,7 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {if (dsIt != textures_.end()) {dsView = dsIt->second.view;pass_ds_format_ = dsIt->second.format;+ pass_depth_texture_ = fbIt->second.depthStencil;}}} else {diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 84023f6e6..2792d9bfc 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -467,6 +467,10 @@ private:u32 pass_height_ = 0;WGPUTextureFormat pass_ds_format_ = WGPUTextureFormat_Undefined;WGPUTextureFormat pass_color_format_ = WGPUTextureFormat_RGBA8Unorm;+ /// What this pass draws INTO, so flushBindGroup can refuse to also sample it.+ /// 0 = none (the surface, which nothing can hold as a texture anyway).+ u32 pass_color_texture_ = 0;+ u32 pass_depth_texture_ = 0;WGPUCommandEncoder encoder_ = nullptr;WGPURenderPassEncoder pass_ = nullptr;void* surface_window_ = nullptr; ///< Native window the surface was made for.diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cppindex 34daf6758..d90423da0 100644--- a/tests/renderer/test_batch_builder.cpp+++ b/tests/renderer/test_batch_builder.cpp@@ -101,8 +101,8 @@ TEST_CASE("appendIndexedDraw: non-Batch stream uses its own stride for baseVerteREQUIRE(h.list.commandCount() == 2);CHECK(h.list.command(0).layout_id == LayoutId::Shape);- // A textureless non-Batch draw must not claim a sampler slot (execute() binds- // only texture_count units for non-Batch layouts).+ // A textureless draw must not claim a sampler slot: texture_count is what+ // execute() binds, and zero of them is what "declares no sampler" looks like.CHECK(h.list.command(0).texture_count == 0);CHECK(h.list.command(1).vertex_byte_offset == 4 * sizeof(TestShapeVertex));// Indices rebased by the SHAPE stride (4 records), not the Batch stride.@@ -377,6 +377,51 @@ TEST_CASE("execute: a merged mesh draw asks the device for its instances in oneCHECK(h.device.lastDrawIndexCount == 36);}+TEST_CASE("execute: a sampling draw pins every sampler unit it does not use") {+ // A unit a draw leaves alone keeps what the draw BEFORE it bound, across passes+ // and frames. So a draw states its whole sampler block or none of it: one that+ // leaves unit 2 alone samples the shadow atlas a shadow pass is drawing into.+ Harness h;+ MaterialStore materials;+ const u32 white = 99;++ BatchDrawKey key = meshKey(5, /*textureId=*/7); // albedo only: texture_count == 1+ pushMeshInstance(h, key, 1.0f);+ h.list.finalize(h.pool);+ h.pool.upload();+ h.list.execute(h.device, h.pool, materials, white);++ u32 boundAt[MAX_CMD_TEXTURE_SLOTS] = {};+ bool seen[MAX_CMD_TEXTURE_SLOTS] = {};+ for (const auto& [unit, tex] : h.device.bindLog) {+ REQUIRE(unit < MAX_CMD_TEXTURE_SLOTS);+ boundAt[unit] = static_cast<u32>(tex);+ seen[unit] = true;+ }+ for (u32 unit = 0; unit < MAX_CMD_TEXTURE_SLOTS; ++unit) {+ CHECK(seen[unit]); // no unit left to whatever ran before+ CHECK(boundAt[unit] == (unit == 0 ? 7u : white));+ }+}++TEST_CASE("execute: a textureless stream declares no sampler and is left alone") {+ // The other half of the same rule: the shape stream samples nothing, so it+ // declares nothing, so there is no binding for stale state to land in.+ Harness h;+ MaterialStore materials;++ TestShapeVertex sverts[4] = {};+ BatchDrawKey key = quadKey(0);+ key.layoutId = LayoutId::Shape;+ appendIndexedDraw(h.pool, h.list, h.clips, sverts, 4, BATCH_QUAD_INDICES, 6, key);++ h.list.finalize(h.pool);+ h.pool.upload();+ h.list.execute(h.device, h.pool, materials, 99);++ CHECK(h.device.bindLog.empty());+}+TEST_CASE("clip state is stamped onto commands from every stream") {Harness h;Entity clipped{5};diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 5927b13f8..0a386d43a 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -72,6 +72,11 @@ export const SCENES = [// The blocker itself stays lit — shadowing one's own caster is the classic bug.{ id: "mesh-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.708,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.167,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },+ // The same scene with a MATERIAL on the occluder, over three frames because a+ // stale sampler unit needs a previous frame. Red at the centre says the material+ // ran in the CAMERA's pass; black at 0.708 says the occluder still cast.+ { id: "mesh-shadow-material", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-material.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "3", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.708,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.167,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },+// The same question through a PERSPECTIVE camera, which is what a 3D scene uses:// coverage derived from the camera's NDC z=0 slice is the whole view for the// orthographic one above and a sliver near the near plane for this one.