Ground shadows for 3D objects (#1515)

[obiot]

Closes #1515.

castGroundShadow gives a Mesh, a Sprite3d billboard or a whole InstancedMesh scatter a soft blob shadow on the ground — the thing 2.5D scenes had no way to get, and without which characters and props read as floating however carefully they are placed.

Deliberately not simulated: for the paper-thin billboards a 2.5D game is made of, a shadow map costs far more than this engine wants to spend and looks worse, because a flat silhouette has to be special-cased to cast anything sensible. What the player needs is contact — where the object stands, and how far off the ground it is mid-jump.

Using it

On by default (the new castGroundShadow application setting), controllable at three levels, most specific first:

new Mesh(x, y, { model: "crate", castGroundShadow: true, shadowGroundY: 0 });  // per object
level.load("diorama", { castGroundShadow: true, shadowGroundY: 0 });           // per glTF scene
new Application(w, h, { cameraClass: Camera3d, castGroundShadow: false });     // application-wide

The two blanket forms skip meshes with no vertical extent — a flat plane lying on the floor is the floor, and shadowing it with itself smears the whole ground. A per-object opt-in is an explicit instruction and bypasses that.

2D games are untouched whatever the setting says: the shadow rides the retained Camera3d path only, so the Canvas renderer and the 2D-camera path draw none.

Notes for reviewers

The blob is an ellipse, not a disc — built from the caster's own model-space footprint carried through its transform, so it matches the object's aspect ratio and turns with it. Read from currentTransform, not the model matrix, because a billboarded Sprite3d builds that from a camera-facing basis and the blob would otherwise spin with the camera.

Shadows are deferred to the end of the mesh pass. A blob writes no depth (so two overlapping at one ground height blend instead of fighting), which leaves it nothing to defend itself with — and a ground plane routinely sorts after the props standing on it. Depth testing stays on, so a shadow is still correctly hidden behind geometry genuinely in front of it. The queue drains when the renderer leaves mesh mode (not on a lit/unlit switch, and not while a mask is being stencilled in or inside a post-effect bracket, where the device state is not the scene's) and at the end of the camera's own draw, inside its FBO bracket.

The instanced tier costs ONE extra draw for an entire scatter, regardless of instance count: the blobs are read from the same instance buffer the meshes draw from, through a standalone shader that reads only the transform rows — so per-instance colour and emissive cannot leak into them.

Backward compatibility: an object that does not cast pays nothing — no extra draw, no extra state, no changed pipeline key — and the shared falloff texture and quads are allocated lazily, so an application with no shadows builds neither.

Two fixes to shared machinery came out of this and are worth a look on their own:

• registerShader deduped on module source alone, silently handing any later caller the first registration's vertex layout. One module can legitimately serve several layouts; now keyed on both, with the compiled module still shared.
• WebGPU pipelines gain a conditional depthWrite axis, appended to the key only when false, so existing pipelines stay byte-identical.

Testing

50 tests in ground_shadow.spec.js plus loader and pipeline coverage, across the backward-compatibility contract, opt-in precedence, the deferred queue, resource lifetime, and pixels. The last matter most here: every draw-count, GL-state, matrix and uniform assertion passed while the feature rendered nothing at all, three separate times. Only readPixels caught it. Each new test was verified to fail with its fix reverted.

Both GPU backends verified on all 14 examples. Shown in Per-material Textures (Mesh), Billboard Sprites (Sprite3d), glTF Scene (whole scene via level.load) and Instanced Forest (InstancedMesh).

Docs: CHANGELOG, both READMEs, and the Working-in-3D, glTF, supported-assets and 2.5D Games wiki pages — the last two carried caveats this removes.

Out of scope, deliberately: real shadow mapping, and a public Mesh.blend (#1516) — the blend/depth capability here is internal to the shadow draw, because exposing it means owning back-to-front sorting for arbitrary translucent geometry.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QVjYzf76AEU3wJk766JAQi

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.