melonjs 20.3.0 → 20.5.0

package/skills/melonjs-performance/SKILL.md

@@ -81,7 +81,16 @@ Two rules that cause subtle bugs when missed:
   successfully recycled object never sees it. Pair event subscriptions with
   `onActivateEvent` / `onDeactivateEvent` instead, or you leak handlers.
 
-Engine classes are poolable too: `pool.pull("me.Tween", target)`.
+Engine classes are poolable too: `pool.pull("Tween", target)`. The canonical
+names are unprefixed — `Entity`, `Collectable`, `Trigger`, `Light2d`,
+`Particle`, `Sprite`, `NineSliceSprite`, `Renderable`, `Text`, `BitmapText`,
+`ImageLayer`, `Tween`, `ColorLayer`.
+
+`pool.register` additionally aliases every name under an `me.` prefix, pointing
+at the same entry, so `pool.pull("me.Tween")` resolves identically — and the
+same alias is registered with the Tiled object factory, which is why a map
+authored against melonJS 1.x still finds its classes. Prefer the unprefixed
+name in new code; do not "correct" an `me.`-prefixed one, it is not broken.
 
 ## `scale()` is multiplicative
 
@@ -126,6 +135,11 @@ collapse to one.
 between a hundred trees and a hundred thousand. glTF scenes using
 `EXT_mesh_gpu_instancing` load as an `InstancedMesh` automatically.
 
+It trades per-object control for the draw call: the set gets ONE depth sort key
+and ONE ground shadow, and `removeInstance` swaps the last instance into the
+hole so held indices go stale. Scenery yes; anything the game removes or
+queries one at a time, usually not. See `melonjs-3d` for the decision table.
+
 ## Update loops
 
 - `update(dt)` should **return `true` only when something changed**. Returning
@@ -146,6 +160,49 @@ between a hundred trees and a hundred thousand. glTF scenes using
   GPU release. Images, by contrast, only lose their loader-side reference; the
   renderer's texture cache is not purged by unloading.
 
+## The first frame of a scene is not like the others
+
+A freeze the first time a level appears, and never again, is almost always
+**shader linking**, not your scene build. Measure before assuming: procedural
+geometry is usually trivial next to it.
+
+Programs are created lazily. The mesh batcher keys a variant on the feature
+combination it is asked for (lit, instanced, instance colours, instance data,
+fog) and links it on the first draw that needs it — and `compileProgram` calls
+`getProgramParameter(LINK_STATUS)` right after `linkProgram`, which blocks until
+the driver finishes. That whole cost lands inside one frame.
+
+How to tell them apart, all from the page:
+
+```js
+// 1. is it the build, or the draw?  time your own setup
+const t0 = performance.now(); buildLevel(); console.log(performance.now() - t0);
+
+// 2. how long is the bad frame?  rAF deltas, not averages
+let last = performance.now();
+const tick = () => { const n = performance.now();
+  if (n - last > 40) console.log("long frame", (n - last).toFixed(0));
+  last = n; requestAnimationFrame(tick); };
+
+// 3. is it programs?  count them, and when
+const gl = WebGL2RenderingContext.prototype, link = gl.linkProgram;
+gl.linkProgram = function (p) { console.count("linkProgram"); return link.call(this, p); };
+```
+
+The tell is that the second entry into the same scene is cheap: one measured
+case went 852ms of stall (worst frame 479ms) on first entry to 277ms (worst
+102ms) on the second, because the programs were already cached.
+
+Two things follow. Cut the number of programs — identical `ShaderEffect`s each
+link their own, so preload one as a `"shader"` asset and share it. And pay what
+remains behind the loading screen by drawing the scene once there and discarding
+it (see `melonjs-loading-assets`).
+
+Do not profile this on a software rasterizer — headless Chromium falls back to
+SwiftShader, where the absolute numbers are wildly pessimistic and the JS
+profile shows the time as `(program)`, outside JS entirely. Ratios transfer;
+milliseconds do not.
+
 ## Where the costs actually are
 
 In rough order for a typical 2D game:
@@ -170,6 +227,8 @@ In rough order for a typical 2D game:
 | everything updates even when idle | `update()` returning `true` unconditionally |
 | memory grows with long music | missing `stream: true` |
 | slow only on some machines | Canvas fallback — no GPU tilemap path |
+| a freeze the first time a level shows, never again | shader variants linking on first draw — warm them behind the loading screen |
+| the same scene stutters once per entry | a derived texture rebuilt per stage: the texture cache keys on the image object, so each rebuild is a new upload |
 
 ## Related skills
 

package/skills/melonjs-physics/SKILL.md

@@ -120,6 +120,19 @@ this.body.setVelocity(vx, vy);
 this.body.force.x = this.body.maxVel.x;
 ```
 
+`maxVel` is what turns a force into a speed, so the two are set together. Use
+the setters rather than writing the vectors — both take an optional THIRD
+argument for the depth axis, left unchanged when omitted, so a 2D call keeps
+its behaviour:
+
+```js
+this.body.setMaxVelocity(3, 15);   // walk speed, jump speed
+this.body.setFriction(0.4, 0);     // ground drag, none vertically
+```
+
+`friction` here is per-axis per-step velocity damping, not a surface
+coefficient — see the built-in quirks below.
+
 Under matter and planck, `syncFromPhysics()` copies the engine body's position
 back onto `renderable.pos` after every step, so a direct write is simply erased
 — no error. The built-in world integrates `pos` in place instead, so a write
@@ -227,6 +240,69 @@ Two prerequisites that produce empty results rather than errors:
 - On the **built-in** adapter, the broadphase is cleared and rebuilt inside
   `world.update()`, so querying before the first update returns nothing.
 
+## 3D collision: `Box3d` and the Z pushback
+
+The narrowphase is not 2D-only. `Box3d` is the one shape with a depth extent,
+and a `Box3d`-vs-`Box3d` contact is resolved in three dimensions — it is the
+only pair in the engine that can push back along **Z**.
+
+```js
+import { Box3d } from "melonjs";
+
+// centre offset from the body, then half-extents on each axis
+rock.body.addShape(new Box3d(0, 0, 0, 40, 60, 40));
+boat.body.addShape(new Box3d(0, 0, 0, 30, 40, 60));
+```
+
+Reach for this for anything moving in the XZ plane under a `Camera3d` — a
+runner dodging obstacles, a 2.5D platformer, pickups on a course. Hand-rolling
+a distance check there is the usual mistake, and it throws away the
+penetration vector the response already carries.
+
+**Read the Z axis off the response, not `overlapN`.** The MTV is a single
+axis, so exactly one of `overlapN.x`, `overlapN.y` and `overlapNZ` is
+non-zero:
+
+```js
+onCollision(response, other) {
+    if (response.overlapNZ !== 0) {
+        // a depth-only contact: overlapN / overlapV are BOTH zero here
+        this.pos.z -= response.overlapZ;
+    }
+    return true;
+}
+```
+
+That is deliberate: a collision resolved along Z leaves the 2D fields at zero,
+so an existing 2D `onCollision` applies no push rather than a wrong one.
+
+**Mixed pairs degrade to 2D.** `Box3d` against a `Polygon`, `Rectangle`,
+`RoundRect` or `Ellipse` tests the box's XY footprint and treats the planar
+shape as unbounded along Z. Only `Box3d`-vs-`Box3d` gives a depth result, so
+give BOTH sides a `Box3d` when you want one.
+
+This is the narrowphase and is independent of the 3D broadphase queries above
+— `querySphere` / `raycast3d` need `world.sortOn === "depth"`; `Box3d` shapes
+do not.
+
+**Bounds are what the broadphase sorts by, and they come from the SHAPE.**
+Every item is filed by its renderable's 2D `getBounds()`, so an object with no
+extent cannot be placed and silently collides with nothing. A `Mesh` takes its
+extent from its geometry and a `GLTFModel` from its part meshes, so both report
+where they are without being told. A body's shapes do **not** contribute, so a
+custom collidable built on a bare `Container` has no extent until you give it
+one:
+
+```js
+// a container reports an EMPTY bounds until it has a size of its own
+group.resize(width, height);
+```
+
+`enableChildBoundsUpdate` also gives it one, but it re-measures the whole child
+list on every update — reach for it only when the extent genuinely IS the
+members' union and moves with them (a flock, a squad), not to give a fixed
+group a size.
+
 ## Built-in world quirks
 
 These are specific to the default world and surprise people arriving from a
@@ -308,6 +384,8 @@ use them. `adapter.capabilities` (`constraints`,
 | crash or a null body when spawning from `onCollisionStart` | world mutated during contact dispatch (locked world under planck) |
 | `raycast` / `queryAABB` finds nothing | `isKinematic` still `true`, or no `world.update` yet (built-in) |
 | `querySphere` / `raycast3d` is not a function | 2D adapter, or built-in without a 3D broadphase (`sortOn !== "depth"`) |
+| a 3D contact reports no overlap to push against | read `overlapNZ` / `overlapZ` — a Z-axis MTV leaves `overlapN` / `overlapV` at zero |
+| two 3D objects never separate in depth | one of them carries a planar shape; a mixed pair is tested as the box's XY footprint, unbounded along Z |
 | `response.depth` / `response.normal` are `undefined` | reading a legacy `onCollision` response — it carries `overlap` / `overlapN` |
 | `onCollisionEnd` handler throws on `response` | built-in dispatches it with `undefined` |
 | off-screen bodies stop simulating | built-in gating on `inViewport`; set `alwaysUpdate` |

package/skills/melonjs-renderables/SKILL.md

@@ -145,7 +145,36 @@ at `enabled === false` and no-ops every method rather than throwing — and
 backend at runtime, an effect that works on your machine may do nothing on
 another.
 
-## 5. `Vector3d.set(x, y)` silently zeroes `z`
+## 5. Opacity cascades; `setChildsProperty` assigns
+
+`alpha` composes down the tree. Fading a container fades everything inside
+it, and the values multiply — a child at `0.5` inside a parent at `0.5` draws
+at `0.25`. Each renderable keeps its own value; the composition happens at
+draw time and is undone when the renderable is finished.
+
+```js
+model.alpha = 0.3;                             // fades the whole rig
+container.setChildsProperty("alpha", 0.3, true); // REWRITES each child's alpha
+```
+
+The two are not interchangeable. `setChildsProperty` is a bulk assignment: it
+changes what the children *are*, so their own `alpha` now reads `0.3` and
+stays that way after the container goes back to full. Reach for it when you
+mean to change the children, and for `alpha` when you mean to fade a subtree.
+
+Do not assign alpha down a hierarchy by hand. The renderer composes it as it
+walks the tree, so setting it at more than one level multiplies: in a rig
+nested three deep, `0.3` applied at every level lands parts on `0.3`, `0.09`
+and `0.027` depending where they sit. The symptom does not look like an
+opacity problem — a model whose parts hold *different* opacities, and which
+appears to change opacity as it turns, because turning changes which parts
+face the camera.
+
+A useful consequence: a `GLTFModel` is a `Container`, so `model.alpha` fades
+every part of a loaded rig — which is what you want for a ghost, a fade-in,
+or a reflection.
+
+## 6. `Vector3d.set(x, y)` silently zeroes `z`
 
 ```js
 v.set(10, 20);        // z becomes 0, not "unchanged"
@@ -155,6 +184,37 @@ v.set(10, 20, v.z);   // keep it
 `pos` is an `ObservableVector3d`, whose `set(x = 0, y = 0, z = 0)` does the same
 — so `this.pos.set(x, y)` wipes the object's depth.
 
+## 7. A settings key the class never reads is silently ignored
+
+A settings object is a plain literal: nothing rejects a key, so a name that
+belongs somewhere else does nothing at all and says nothing about it.
+
+```js
+// WRONG — only the RENDERER reads a `blendMode` setting, never a renderable
+const glow = new Sprite3d(x, y, { image: "sun", blendMode: "additive" });
+
+// right: it is a property
+glow.blendMode = "additive";
+```
+
+The same shape catches `transparent` on a `GLTFModel` (its parts carry it —
+`model.setChildsProperty("transparent", true, true)`) and any `Mesh` setting
+handed to a class that forwards only a curated subset. If a visual option
+appears to do nothing, check whether the class actually reads it before
+tuning the value.
+
+## 8. `isRenderable` does not hide anything
+
+It gates `updateBounds`, not drawing. Setting it `false` leaves the object on
+screen and merely stops its bounds tracking, which is worse than doing nothing.
+
+```js
+sprite.isRenderable = false;   // WRONG — still drawn, bounds now stale
+sprite.alpha = 0;              // hides it
+```
+
+Use `alpha` for a blink, or remove the child for a long absence.
+
 ## Update and draw
 
 ```js
@@ -207,6 +267,8 @@ Hand-rolled equivalents miss the batching and the multi-backend support.
 | custom draw offset by half the size | centred `anchorPoint` default not zeroed |
 | spatial query never finds an object | `isKinematic` left `true` — not in the broadphase |
 | `z` unexpectedly 0 after a `set` | `Vector3d.set(x, y)` defaults `z` to 0 |
+| a settings option appears to do nothing | the class never reads that key — see section 7 |
+| `isRenderable = false` did not hide the object | it gates bounds, not drawing — use `alpha` |
 
 ## Related skills
 

package/skills/melonjs-renderer-backends/SKILL.md

@@ -132,6 +132,14 @@ event.on(event.ONCONTEXT_RESTORED, (renderer) => {
 });
 ```
 
+## Test on the backend your users get, not the one your harness picks
+
+`video.AUTO` prefers WebGPU where it exists. Headless Chromium usually has no
+GPU adapter and falls back to WebGL, so an automated suite can pass every run
+while the WebGPU path is broken — the two differ in real, throwing ways (see
+below). Pin the backend explicitly when it matters: `renderer: video.WEBGPU`,
+or the `#webgpu` / `#webgl` URI fragment on a page you can open by hand.
+
 ## Practical differences
 
 - **Frame capture orientation differs**: row 0 of a `toFrameTexture()` capture is
@@ -147,6 +155,15 @@ event.on(event.ONCONTEXT_RESTORED, (renderer) => {
   accents, ruinous for hundreds of objects. `normal`, `additive`, `multiply`,
   `screen` and `exclusion` are ordinary fixed-function state and cost nothing
   extra.
+- **WebGPU rejects a zero-sized image source; WebGL shrugs at it.** Uploading a
+  0-width or 0-height canvas throws
+  `OperationError: GPUQueue.copyExternalImageToTexture: External image state is
+  not valid`, from a stack that reads `drawImage → addQuad → getBinding`. WebGL
+  uploads the same source without complaint, so this is a class of bug that
+  cannot appear on one backend and stops the game dead on the other. The usual
+  source is a `Text` whose string is empty or whitespace-only — it measures to
+  nothing, so its glyph canvas has no width. Give a placeholder label a real
+  glyph and hide it with `alpha`/position instead of blanking its text.
 - **3D meshes do not honour blend modes.** The mesh pass draws with its own
   depth/blend state; asking for one of the advanced modes logs a one-time
   `blend mode "…" is not supported for 3D meshes` warning and falls back to
@@ -163,6 +180,8 @@ event.on(event.ONCONTEXT_RESTORED, (renderer) => {
 | a solid box where an effect should be | carrier drawn while the effect is disabled |
 | nothing renders at all on an old device | `video.WEBGL` pinned; WebGL 1 is rejected, not downgraded |
 | ported shader is vertically flipped | the WebGL capture is bottom-up, the WebGPU one top-down |
+| `copyExternalImageToTexture: External image state is not valid` | a zero-sized upload source — most often a `Text` with an empty or whitespace-only string |
+| runs on the test machine, dies on the dev's | the harness fell back to WebGL and never exercised WebGPU |
 | a blended mode is ignored on a mesh | meshes fall back to `"normal"`; look for the one-time warning |
 | textures vanish after the tab is restored | cached raw GPU handles not re-acquired on context restore |
 

package/skills/melonjs-scenes-and-state/SKILL.md

@@ -74,6 +74,45 @@ app.freeze(150);                             // brief hit-stop (proxies state.fr
 `state.change`. The `"mask"` form needs its fourth argument, an `Ellipse` or
 `Polygon`; without one it warns and falls back to a direct switch.
 
+### A Stage's own `update()` is NOT paused
+
+This one is easy to get wrong and hard to see. `Application.update` calls both
+of these **unconditionally**:
+
+```js
+this.isDirty = this.world.update(this.updateDelta);
+this.isDirty = state.current().update(this.updateDelta) || this.isDirty;
+```
+
+Only `Container.update` consults the pause — it reads `state.isPaused()` and
+skips every child that is not `updateWhenPaused`. So world children (entities,
+sprites, meshes, a `GLTFModel`) freeze correctly, while **the Stage subclass's
+own `update()` keeps running**.
+
+A game that keeps its logic in entities pauses for free and never notices. A
+game that drives the simulation from `Stage.update` — common for an endless
+runner, where one object moves and the world scrolls past it — keeps simulating
+through `pauseOnBlur` with its world frozen. The signature is bizarre and very
+misleading: the scenery scrolls on, the player character stands still in world
+space and slides off the screen, and it all snaps back on focus. It reads as a
+culling or animation bug, not a pause bug.
+
+Guard it explicitly:
+
+```js
+update(dt) {
+    super.update(dt);
+    if (state.isPaused()) {
+        return true;        // world children are already frozen for you
+    }
+    // …simulation…
+}
+```
+
+Worth knowing that `pauseOnBlur` (default `true`) fires on a window `blur`, not
+only on tab `visibilitychange` — so clicking another window on the same screen
+triggers it while the canvas is still fully visible.
+
 ## The update loop
 
 There is no loop you own. Logic goes in `update(dt)` overrides, or a
@@ -160,6 +199,21 @@ save.add({ hiscore: 0 });      // once; idempotent, loads any stored value
 save.hiscore = 1200;           // plain assignment writes to localStorage
 ```
 
+**In TypeScript, keep what `add()` returns.** The namespace carries a
+`[key: string]: unknown` index for keys registered anywhere, so reading
+`save.hiscore` off it gives you `unknown`. `add()` hands back the same
+namespace typed with the keys you just registered, which is the handle to
+keep:
+
+```ts
+const store = save.add({ hiscore: 0, lives: 3 });
+store.hiscore = 1200;          // number, no cast
+if (score > store.hiscore) { /* ... */ }
+```
+
+Chained calls accumulate, so `save.add({ a: 0 }).add({ b: "" })` is typed with
+both.
+
 ## Symptom → cause
 
 | symptom | cause |
@@ -169,6 +223,8 @@ save.hiscore = 1200;           // plain assignment writes to localStorage
 | a tween finishes in 1000 ms whatever you pass | `to()` takes `{ duration }`, not a number |
 | object frozen while its state updates | `update()` not returning `true` |
 | timers fire behind a pause menu | `window.setTimeout` instead of `timer.setTimeout` |
+| the world freezes on blur but the game keeps advancing | simulation lives in `Stage.update`, which the pause does not gate — only `Container.update` checks `state.isPaused()` |
+| the player character is left behind and scrolls off after a lost window | same cause: the stage advanced the camera while its world children were paused |
 | a tween does nothing | `.start()` never called |
 | effect stops during a hit-stop | tween needs `updateWhenPaused = true` |
 | crash after a stage switch | callback ran during teardown — guard with `state.isCurrent` |

package/skills/melonjs-tilemaps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-tilemaps
-description: "Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers. Covers the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax."
+description: "Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers. Covers the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, level.load, level.load async, await level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax."
 license: MIT
 ---
 
@@ -33,18 +33,37 @@ also skip `src` and pass the map inline via `data` (with `format: "json"` or
 `"xml"`).
 
 `level.load(levelId, options)` accepts `container` (default `game.world`),
-`onLoaded` (default `game.onLevelLoaded`), `flatten` (default `game.mergeGroup`)
-and `setViewportBounds` (default **`true`**). It throws `level <id> not found`
-for an unknown id.
+`onLoaded` (default `game.onLevelLoaded`), `flatten` (default `game.mergeGroup`),
+`setViewportBounds` (default **`true`**) and `async` (default `false`). It throws
+`level <id> not found` for an unknown id — synchronously, in both forms, because
+that is a typo rather than a load failure.
 
 **`level.load` is deferred while the game loop is running.** It calls
-`state.stop()` and finishes the load in a `setTimeout`, so it returns `true`
-before anything is in the world. Do follow-up work from the `onLoaded` callback
-or an `event.LEVEL_LOADED` listener, not on the next line.
+`state.stop()` and finishes the load on a timer, after the current frame, so by
+default it returns `true` before anything is in the world. Two ways to sequence
+work after it:
 
-`level.reload()`, `level.next()`, `level.previous()`, `level.getCurrentLevelId()`
-and `level.levelCount()` round out the namespace. `flatten: false` wraps each
-Tiled object group in its own `Container` named after the group.
+```js
+// await it
+await level.load("map1", { async: true });
+// the world is populated here
+
+// ...or use the callback / event, which fire in both forms
+level.load("map1", { onLoaded: () => this.spawnPlayer() });
+```
+
+`async: true` is the only thing that changes the return value — everything else
+behaves identically, `onLoaded` included. Without it the call returns a boolean,
+so `await level.load("map1")` is not an error and does not await the load:
+`await true` resolves immediately, while the load is still sitting on a timer.
+Pass the flag when you mean to await.
+
+`level.reload()`, `level.next()` and `level.previous()` take the same `async`
+option and resolve the same value they return — so `if (level.next())` becomes
+`if (await level.next({ async: true }))`. Running out of levels reports `false`
+either way rather than throwing. `level.getCurrentLevelId()` and
+`level.levelCount()` round out the namespace. `flatten: false` wraps each Tiled
+object group in its own `Container` named after the group.
 
 ## Spawning entities from Tiled objects
 
@@ -177,7 +196,8 @@ unanimated layer into the offscreen-bake path instead.
 | symptom | cause |
 |---|---|
 | a Tiled object becomes a plain shape with no behaviour | its class/name does not match any registered factory, or it was registered after `level.load` |
-| the world is still empty right after `level.load` | the load is deferred via `setTimeout` while the loop runs — use `onLoaded` / `LEVEL_LOADED` |
+| the world is still empty right after `level.load` | the load is deferred to a timer while the loop runs — `await level.load(id, { async: true })`, or use `onLoaded` / `LEVEL_LOADED` |
+| `await level.load(id)` returned `true` rather than a promise | without `async: true` the call returns a boolean; `await true` resolves immediately and the load has not run yet — pass the flag when you mean to await |
 | `level <id> not found` | the map was never preloaded, or the asset `name` differs from the id passed to `load` |
 | `unknown or invalid resource type` | asset `type` set to `"tmj"` / `"tsj"` — use `"tmx"` / `"tsx"` with the `.tmj` / `.tsj` file |
 | camera will not scroll | `setViewportBounds: false`, or the map was added with `addTo()` (which defaults to `false`) |