melonjs 20.4.0 → 20.5.0

package/skills/melonjs-effects-and-shaders/SKILL.md

@@ -25,6 +25,34 @@ app.viewport.addPostEffect(new VignetteEffect(app.renderer));
 `renderable.shader = …` is **deprecated since 19.2.0**, and its setter destroys
 whatever it replaces. Use `addPostEffect` / `getPostEffect` / `removePostEffect`.
 
+### A camera effect covers the HUD too
+
+A camera's post-effect brackets the **entire** world draw — floating children
+included. So the obvious way to write a full-screen pass also washes over every
+HUD label in that world, which is rarely what you want.
+
+To land a pass *after* the world but *before* the HUD, host the effect on a
+screen-filling floating renderable ordered below the HUD's z instead:
+
+```js
+const quad = new Sprite(0, 0, { image: anyImage });
+quad.anchorPoint.set(0, 0);
+quad.scale(viewW / anyImage.width, viewH / anyImage.height);
+quad.floating = true;                 // its own uv is now screen space
+quad.blendMode = "additive";
+quad.addPostEffect(myEffect);
+world.addChild(quad, HUD_Z - 10);     // BELOW the labels, not above
+```
+
+Two things follow from the quad filling the frame: its own `uv` is screen space
+(so a pass like this needs none of the `screen_uv` / `screen_texture` builtins),
+and the incoming `color` is the quad's own texture, which a body that paints
+from scratch can ignore entirely.
+
+Depth here is easy to get backwards — a higher z draws **later**, i.e. on top.
+Verify it by returning a flat colour from the body for one frame: whatever it
+tints is what the pass covers.
+
 ## Toggle with `enabled`, do not remove
 
 **`removePostEffect()` destroys the effect** — it calls `effect.destroy()` and
@@ -80,7 +108,34 @@ one `@group(3) @binding(0) var<uniform>` struct — so a single `setUniform` cal
 feeds whichever backend is live. `setTime` is a convenience for a `uTime`
 uniform and silently does nothing if the shader does not declare one.
 
-Shaders can also be preloaded as assets with loader type `"shader"`.
+### One effect is one program — prefer preloading, and share
+
+A `ShaderEffect` compiles and links in its **constructor**, and the link is
+checked with `getProgramParameter(LINK_STATUS)` straight after `linkProgram` —
+a blocking call. So the cost is paid on whatever frame the effect is
+constructed, and *n* identical effects cost it *n* times. `clone()` does not
+avoid it: it constructs a new effect and links a new program.
+
+Preload it instead. Loader type `"shader"` takes a `src` **or inline source via
+`data`**, compiles at load time (inside the loading screen), and hands back a
+**shared** instance:
+
+```js
+loader.preload([{ name: "ramp", type: "shader", data: myFragmentBody }]);
+// …then, for every label that wants it:
+label.addPostEffect(loader.getShader("ramp"));
+```
+
+Sharing one instance across renderables is safe *because* the loader sets
+`effect.shared`. Without that flag a renderable's teardown destroys its post
+effects, which would free the program out from under everything else still
+using it. Uniforms live on the effect, so a shared instance means one set of
+uniform values — fine when the look is uniform, and the reason to clone (and
+pay a link) when it is not.
+
+Note this covers **your** effects only. The engine's own mesh/quad shader
+variants are compiled lazily per feature combination on first draw and cannot be
+preloaded — see `melonjs-loading-assets` for the warm-up that covers those.
 
 ### Screen-reading builtins
 
@@ -109,6 +164,43 @@ Two places where a straight port really does differ:
   uniform (initialise it to `1.0`) and multiply vertical offsets by it; the
   renderer feeds `-1` on that path and `+1` everywhere else.
 
+## A ShaderEffect cannot shade a mesh on WebGPU
+
+The single-effect fast path swaps the renderable's program outright instead of
+rendering through an offscreen target. On WebGL that works for a `Mesh` too, so
+a custom mesh shader is a `ShaderEffect` away. **On WebGPU it does not** — the
+renderer says so in its own source, warns once, and then keeps the built-in
+mesh shading.
+
+Nothing throws. The mesh simply draws with its plain texture, which looks like
+a broken shader, a bad binding, or a texture that failed to load — and since
+`video.AUTO` prefers WebGPU where it is available, this is the default outcome
+on most desktops. It cost several hours here: the symptom was a water surface
+rendering flat white, and alpha, bindings, transparency and lighting were all
+eliminated before the backend was.
+
+2D renderables are unaffected: `Sprite`, `Text` and the rest go through the
+quad path, which hosts effects on both backends. So a gradient fill for text,
+or a refraction over a sprite, is fine — it is specifically the mesh path.
+
+If you need a genuinely custom mesh shader that runs everywhere, supply a full
+dual-language `GLShader` rather than a fragment body, and declare the fog
+uniforms yourself (see `melonjs-3d`).
+
+## Extra textures bind in setTexture order
+
+`setTexture("uFoo", …)` assigns bindings **1 and 2** to the first extra
+texture, **3 and 4** to the second, and so on. The WGSL must match:
+
+```wgsl
+@group(3) @binding(1) var uFoo : texture_2d<f32>;
+@group(3) @binding(2) var uFooSampler : sampler;
+```
+
+Copying a two-texture effect and deleting one leaves the survivor declared at
+3/4 while it is bound at 1/2 — the program fails to build and the effect is
+silently dropped.
+
 ## Blend modes
 
 Fourteen modes; thirteen of them are honoured by all three renderers:

package/skills/melonjs-loading-assets/SKILL.md

@@ -46,11 +46,107 @@ The type strings are melonJS-specific — this is not a generic loader:
 | `"binary"` | raw data, bitmap font `.fnt` descriptors |
 | `"fontface"` | web fonts (`.ttf`, `.woff`) |
 | `"aseprite"` | Aseprite JSON + image |
-| `"shader"` | GLSL/WGSL shader sources |
+| `"shader"` | GLSL/WGSL shader sources — `src` **or** inline via `data` |
 | `"obj"` / `"mtl"` | Wavefront models and materials |
 | `"gltf"` / `"glb"` | glTF scenes |
 | `"js"` | scripts |
 
+## What belongs in the manifest — and what cannot
+
+Preloading is not only for things with a URL. Three tiers, and the middle one
+is the one people miss.
+
+**1. Assets with a source.** Everything in the type table above. Note `"shader"`
+takes **inline source** as well as a `src`, via the `data` field:
+
+```js
+import { myRamp } from "./myRamp";   // a GLSL fragment body, in your own module
+
+loader.preload([
+    { name: "ramp", type: "shader", data: myRamp },
+]);
+const fx = loader.getShader("ramp");   // shared, already compiled
+```
+
+This matters more than it looks. A `ShaderEffect` compiles its program in its
+**constructor**, and `compileProgram` calls `getProgramParameter(LINK_STATUS)`
+immediately after `linkProgram` — a blocking call that forces the driver to
+finish. So building one during a scene costs that link on the frame it appears,
+and building three identical ones costs it three times. Preloaded as an asset it
+is compiled at load time, behind the loading screen, and the loader hands out a
+**shared** instance (`effect.shared === true`), which is what stops one
+renderable's teardown freeing it out from under the others. `clone()` does NOT
+help here — it constructs a new effect, and therefore links a new program.
+
+**2. Derived assets — build once, after the preload.** Canvases you bake,
+`NoiseTexture2d`, `TextureAtlas`: the loader cannot carry these, but they must
+not be rebuilt per scene either. The renderer's texture cache is keyed by the
+**image object**, so a freshly baked canvas is a brand new GPU texture with a
+new mip chain — rebuild one per stage and a title → play → game-over cycle
+uploads four copies of the same pixels. Build them once after `preload`
+resolves and share them, the way the platformer example builds its
+`TextureAtlas` into a module the scenes read from.
+
+**3. The engine's own shader variants — not preloadable at all.** The mesh
+batcher compiles a program per *feature combination* (lit, instanced, instance
+colours, instance data, fog — fog joins the key), lazily, on the first draw that
+needs it. There is no loader type for these and no API to warm the cache: the
+only lever is to **draw** that combination once while the loading screen is
+still up, then throw the scene away — the compiled programs stay in the
+renderer. Worth doing for a heavy 3D scene, where first-draw linking is easily a
+few hundred ms and lands as a freeze on the first frame of the first level.
+
+```js
+await loader.preload(resources);
+buildScene(app);                       // same geometry the level uses
+await twoFrames();                     // event.GAME_AFTER_DRAW
+removeOnlyWhatYouAdded(app);           // keep the programs, drop the scene
+state.change(state.PLAY);
+```
+
+**It borrows the LOADING stage's world, and that has three teeth**, all learned
+the hard way:
+
+- **Never tear down with `app.world.reset()`.** It clears *every* child of that
+  world, the loading screen's own included, and the screen goes blank for the
+  rest of the load. Snapshot `app.world.children` first and remove only what
+  you added.
+- **Restore anything the warm-up changes that the loading screen shows** — the
+  renderer's `backgroundColor` above all, or the warm-up flashes its own empty
+  first frame.
+- **Under a `Camera3d` it will hide the built-in loading screen, and there is no
+  clean way around it** — see below.
+
+### `DefaultLoadingScreen` lives in the WORLD, not on the screen
+
+The built-in loading screen is written for a `Camera2d`. Its progress bar and
+logo are added with `app.world.addChild(bar, 1)` / `addChild(logo, 2)` and are
+**`floating === false`** — ordinary world-space renderables. They read as an
+overlay only because that stage's world is otherwise empty.
+
+So with `cameraClass: Camera3d`, anything you add to that world is in the scene
+*with* them, and a 3D scene simply swallows them: the depth buffer puts terrain
+in front of a bar sitting at z = 1. What does NOT rescue it, all tried:
+
+- **Raising their `z`** — for a mesh on the `Camera3d` path `pos.z` IS world
+  depth, so the scene's own z values are geometry, not layering, and the bar
+  still loses to the depth test.
+- **`moveToTop()`** — it early-returns for a child already at index 0, which the
+  loading screen's children always are, having been added before anything else.
+  It silently does nothing.
+- **Flipping them to `floating = true`** for the duration — the scene still
+  covers them.
+
+If you want a warm-up (or any 3D behind a loading screen), write your own
+loading stage and draw its progress UI as **floating** renderables over the
+scene. That is also the nicer result: the player watches the level assemble
+instead of a logo. Budget it as real work, not a one-liner — and weigh it
+against what the warm-up actually saves.
+
+One more limit: a warm-up only covers the combinations it actually draws.
+Renderables the real level has and the warm-up does not will still link on
+entry.
+
 ## Two conventions that produce 404s
 
 **Audio `src` is a directory.** The loader appends the asset name plus each

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
 
@@ -151,6 +160,49 @@ queries one at a time, usually not. See `melonjs-3d` for the decision table.
   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:
@@ -175,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` |