Add per-object ground shadow scaling

[snowyukitty]

Description

A wide, flat-bottomed prop can hide its ground shadow entirely, and the footprint currently has no per-object size control. Add shadowScale (default 1) beside shadowOpacity so games can enlarge or tighten the blob independently of the object's size.

The setting works on Mesh, Sprite3d, and InstancedMesh and can be changed at runtime. It scales the footprint without changing the shadow's ground position or opacity; non-positive or non-finite values hide the shadow while leaving the object visible. Instanced shadow geometry refreshes when the scale changes and remains cached otherwise.

Type of change

• Bug fix
• New feature
• Documentation update
• Performance improvement
• Refactoring (no functional changes)

Checklist

• I have read the Contributing Guide
• My code follows the existing code style (pnpm lint passes)
• I have tested my changes locally (pnpm test --run --maxWorkers=2 passes)
• I have added tests that cover my changes
• The build succeeds (included in pnpm lint and pnpm test)

Validation uses Chromium with WebGL required. The full suite reports 7,553 passed and 11 skipped. The ground-shadow suite passes 72 tests, including 20 new cases for scaling, live changes, invalid values, instanced geometry caching, and rendered pixels outside a wide prop. On the original source, all 20 new cases fail as expected; the unmodified 52-test suite still passes.

Related issues

Part of #1631: implements item 1, per-object shadow scale. Items 2 and 3 remain open.

[obiot]

this is awesome, thank you for the contribution ! will review & merge asap as part of the 20.8 release

[obiot]

Thanks for this — it is a well-made PR, and the testing in particular is better than most. I verified your claims rather than taking them on trust and they hold up exactly:

• tests/ground_shadow.spec.js runs 72 passed, 0 skipped here (the requireWebGL helper only skips on a genuinely absent renderer, so these really execute).
• Reverting just the three source files to master and keeping your tests gives 20 failed / 52 passed — precisely the 20 new cases you described, and the pre-existing 52 untouched.
• Full suite 7554 passed, lint gate clean.
• Your "instanced geometry refreshes when the scale changes" claim is correct, and for the right reason: getInstancedShadowQuad keys on ${lit}:${version}:${halfX}:${halfZ} and the scale now feeds halfX/halfZ, so the key moves and the quad is rebuilt.

The design matches what #1631 asked for — shadowScale, default 1, beside shadowOpacity, footprint only, with non-positive and non-finite values hiding the blob without hiding the mesh.

One blocking gap: it does not reach a GLTFModel

GLTFModel forwards only two of the shadow settings to the parts it builds (src/level/gltf/GLTFModel.js:287-291):

castGroundShadow: /* … */,
shadowGroundY: options.shadowGroundY,

shadowOpacity was already missing (pre-existing, not yours) and shadowScale is missing too — so from a GLTFModel the new setting is unreachable without walking the children and assigning .shadowScale on each part by hand.

That matters because the motivating case in #1631 is "a wide, flat-bottomed prop", and the one consumer in this repo is exactly that and exactly a GLTFModel — the boat in the Jungle Rabbit example, which already does:

new GLTFModel(gltf("boat"), {
    castGroundShadow: true,
    shadowGroundY: WATER_LEVEL + SHADOW_LIFT,
})

A BOAT_SCALE 44 hull on water is the case the feature exists for, and today it cannot opt in. Could you add shadowScale: options.shadowScale alongside shadowGroundY there, with the matching @param on the constructor doc? Adding shadowOpacity in the same place would be welcome too, but that one is pre-existing so entirely your call whether to fold it in.

Changelog: style, not content

No merge conflict (I dry-ran it), but #1710 landed an hour ago and rewrote the whole 20.8.0 section into a terser house style, so your entry will arrive written to the old one. Current style is a bold lead-in, one or two sentences, no trailing full stop, and no blank line between entries. Something like:

- **`Mesh#shadowScale`**: the ground shadow's footprint independent of the object's size, on `Mesh`, `Sprite3d` and `InstancedMesh`. `1` by default; non-positive or non-finite hides the blob without hiding the object

It should also sit with the other ### Added entries rather than after a blank line at the end of the section.

Two small notes, neither blocking

1. The InstancedMesh path rebuilds by quad.destroy() + new Mesh(...), so a game that animates shadowScale on an instanced scatter re-uploads retained GPU geometry every frame. The JSDoc says the change "rebuilds its shadow quad", which is accurate but reads as a neutral fact; worth making it a warning, e.g. "changing it on an InstancedMesh rebuilds retained geometry, so avoid animating it per frame".

2. it.for([0.5, 2, 1e-8]) on the instanced path is a nice edge case, but 1e-8 passes the > 0 guard and builds a quad with half-extents around 1e-8. Harmless, just worth knowing the guard's boundary is "positive and finite" rather than "visible".

Happy to merge once the GLTFModel forwarding and the changelog entry are in. Thanks again — the mutation evidence in the description made this much faster to review.

[obiot]

I'm also adding #1631 on top of this, so that the light3d shadow is "complete" for now, thanks again

[obiot]

FYI, I use this opportunity to also close related tickets, and now we have all this working :
https://melonjs.github.io/melonJS/examples/#/ground-shadows