Container: keep floating children out of the depth sort

[obiot]

The bug

floating = true opts a renderable out of the perspective projection — it is drawn in screen space — but it was still being ordered by distance from the camera in _sortDepth.

Its pos is then not a place in the world, so that distance means nothing. Parking a HUD at a large z to mean "in front" is the intuitive move, and it did the opposite: a score at z = 10000 sorted to the far end of the scene, and every tree in the level drew over it.

Nothing errors. The HUD is simply behind the game.

The fix

Floating children sort ahead of everything else, so draw's reverse walk draws them last:

const aFloating = a.floating === true;
const bFloating = b.floating === true;
if (aFloating !== bFloating) {
    return aFloating ? -1 : 1;
}

Ordering among floating siblings is left to the existing distance math, unchanged, and non-floating children are untouched.

The clause deliberately follows the same reverse-walk convention as the distance math it sits above rather than inventing a second one — so flipping draw's loop to iterate forwards means negating this comparator as a unit, and the clause flips with it.

Tests

4 new:

• a floating child draws last however far away its z puts it
• and also when its z is nearer than everything
• every floating child sits above every world child
• the order of non-floating children is untouched

That last one is asserted as an invariant — sort a set of children, then sort the same set with a floating sibling added, and compare the non-floating subsequence — rather than pinning an absolute order. My first draft did pin one and failed: _sortDepth measures against a module-level camera cache that a bare harness does not control, so the concrete sequence is environment-dependent. Testing the invariant is both correct and what the change actually promises.

Full suite: 6,463 passing, 267 files. eslint 0 errors, biome clean.

Docs

melonjs-3d gains a HUDs and other floating renderables section — floating children are always drawn on top whatever their z, and the "give it a big z to put it in front" instinct is exactly backwards — plus a symptom row:

symptom	cause
a HUD draws behind the scenery	before 20.4 floating joined the depth sort; give it floating = true and no z games

How it was found

Building a 3D example: the score sat behind the trees. The workaround was re-parking the HUD just in front of the moving camera every frame, which is the sort of thing nobody should have to discover.

🤖 Generated with Claude Code

https://claude.ai/code/session_012Aa37KGXZcnVrbn1yG4j1N

[Copilot]

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

[obiot]

Strengthened the tests after review — the first version did not actually test the fix.

Container.sort() defers the sort, so reading getChildren() straight after it returns the array in insertion order. Every assertion was passing on insertion order alone: the suite was green against an engine with the bug still in it. Switched to sortNow(), the synchronous path the engine uses per frame.

Verified by mutation — with the fix removed, 2 of the 7 fail; with it restored, all pass:

=== with the fix REMOVED ===
  × draws a floating child last however far away its z puts it
  × keeps every floating child above every world child
  Tests  2 failed | 5 passed (7)
=== fix restored ===
  Tests  7 passed (7)

Also added three guards for the 2D comparators, which this change deliberately does not touch — that is where the real regression risk was. Forcing floating on top under sortOn: "z" would silently break every layout with a floating backdrop behind its sprites, so those pin that a floating child is still ordered by z there, both above and below a sprite.

Confirmed end to end as well: in a 3D scene with the HUD back at depth: 10000 and its per-frame workaround deleted, the score now draws over the scenery.

Full suite 6,466 passing, 267 files.

[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.