melonjs 20.12.0 → 20.14.0

package/skills/melonjs-plugins/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-plugins
-description: "Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, on-screen touch controls, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, GamepadPlugin, gamepad-plugin, touch controls, virtual joystick, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered."
+description: "Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, on-screen touch controls, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, GamepadPlugin, gamepad-plugin, touch controls, virtual joystick, floating joystick, floating button, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered."
 license: MIT
 ---
 
@@ -13,13 +13,13 @@ This trips people up, so it is worth stating first:
 | | how it is installed |
 |---|---|
 | **Plugins** | `plugin.register(Class, name?, ...args)` — after `await app.init()` |
-| **Physics adapters** | an `Application` **setting** (`physic:`), before `init()` |
+| **Physics adapters** | an `Application` **setting** (`physic:`), before `init()`; or `app.world.setAdapter()` on a running game |
 
 ```js
 // the adapter is chosen at construction …
 const app = new Application(800, 600, {
     parent: "screen",
-    physic: new PlanckAdapter({ gravity, pixelsPerMeter }),
+    physic: await PlanckAdapter.create({ gravity, pixelsPerMeter }),
 });
 
 // … the plugin is registered once the renderer exists
@@ -88,6 +88,19 @@ This is the answer for deforming animated characters — glTF import does not re
 vertex skinning. It also registers a Tiled object class, so Spine skeletons can
 be placed from a map.
 
+```js
+import Spine, { SpinePlugin } from "@melonjs/spine-plugin";
+
+await app.init();
+plugin.register(SpinePlugin);   // after init: it reads app.renderer
+// preloaded as { name: "hero.atlas", type: "spine", src: … }, and the same for
+// "hero.json" (a binary "hero.skel" also goes in jsonFile)
+const hero = new Spine(100, 100, { atlasFile: "hero.atlas", jsonFile: "hero.json" });
+```
+
+Register it after `await app.init()` like any plugin: its constructor builds
+an asset manager on the application's renderer, which does not exist before.
+
 ### `@melonjs/gamepad-plugin`
 
 On-screen touch controls, reported as a gamepad: one or two sticks and any
@@ -105,7 +118,14 @@ plugin.register(GamepadPlugin, "gamepad", {
 
 Shown on touch screens by default (`enabled`), hidden while a real pad is in
 use. The left stick also presses the D-pad; a button can press a key instead
-of a pad button. See `melonjs-input` for the bindings.
+of a pad button. Since 1.1 a stick or button can be `floating` (shows up
+under the finger anywhere in its `area`), `hideAtRest` (drawn only while
+held), and a stick can take a `tap` (a quick touch that does not steer presses
+a key or button) — so the mobile layouts, two thumbs or one thumb with
+tap-to-act, need no code of their own. Since 1.2 a `skin` texture atlas draws
+them from the game's own art (`base` / `thumb` regions on a stick, `region` /
+`pressed` on a button). It needs melonJS 20.12 or later. See `melonjs-input`
+for the bindings, the layouts and the overlap rules.
 
 ### `@melonjs/capacitor-plugin`
 
@@ -121,16 +141,29 @@ It also exports helpers usable on their own: `onBackButton`, `bindStageBack`,
 `lockOrientation` / `unlockOrientation`, `hideSplash`. See `melonjs-deployment`
 for the wider packaging picture.
 
+With `pauseOnBackground` (the default), going to the background pauses the
+game and coming back resumes it, but only if this pause was the plugin's: a
+game the player had paused stays paused.
+
 ## Physics adapters
 
-`@melonjs/planck-adapter` and `@melonjs/matter-adapter` swap the physics world
-wholesale. Pick **one** per game. The portable surface — the declarative
-`renderable.bodyDef`, `world.adapter.queryAABB(rect)` and
+`@melonjs/planck-adapter`, `@melonjs/matter-adapter` and
+`@melonjs/rapier2d-adapter` swap the physics world wholesale. Pick **one** per
+game (`app.world.setAdapter()` can switch it later). The portable surface — the
+declarative `renderable.bodyDef`, `world.adapter.queryAABB(rect)` and
 `world.adapter.raycast(from, to)` — works unchanged across the built-in world and
-both adapters, so entity code does not have to branch.
+every adapter, so entity code does not have to branch. The exceptions are in
+`melonjs-physics`: `Box3d`, `Sphere` and `Point` shapes are built-in only,
+`type: "kinematic"` is planck and Rapier only, and the adapters' `queryAABB`
+returns only renderables with a body. The Rapier adapter's WebAssembly loads
+asynchronously, so it must be made with `await RapierAdapter.create()`.
+`create()` is on every adapter from planck-adapter 1.7, matter-adapter 1.6 and
+rapier2d-adapter 1.0 (an older planck or matter adapter is made with
+`new X(options)`), and `world.setAdapter()` from melonJS 20.14.
 
 Two queries are **not** portable: `querySphere` and `raycast3d` exist only on the
-built-in adapter (planck and matter are 2D-only and deliberately omit them).
+built-in adapter (planck, matter and Rapier are 2D-only and deliberately omit
+them).
 `queryAABB` is the one region query every adapter must implement, so call the
 others optionally — `app.world.adapter.querySphere?.(center, radius)`. For rays
 there is a real flag: `app.world.adapter.capabilities.raycasts3d`.
@@ -195,11 +228,17 @@ or a `Stage` is simpler and easier to test.
 | `Plugin version mismatch` | the plugin's `version` floor is above the running engine |
 | `Plugin should extend the BasePlugin Class !` | the class does not extend `plugin.BasePlugin` |
 | the panel reports another app's numbers | `app` defaulted to `game`, the last Application to finish `init()` |
-| `world.adapter.querySphere is not a function` | built-in adapter only; planck and matter are 2D-only |
+| `world.adapter.querySphere is not a function` | built-in adapter only; planck, matter and Rapier are 2D-only |
 | a Tiled map opens in Tiled but not melonJS | compressed layers, tiled-inflate plugin missing |
 | plugin setup never runs | setup written in an `init()` method — there is no such hook |
-| `plugin.register` for an adapter does nothing | adapters are a construction setting, not a plugin |
+| `Plugin should extend the BasePlugin Class !` when registering an adapter | adapters are a construction setting (or `world.setAdapter()`), not a plugin |
+| `PlanckAdapter.create is not a function` (or `MatterAdapter`) | planck-adapter < 1.7 or matter-adapter < 1.6; upgrade, or `new PlanckAdapter(options)` |
+| `TypeError` reading `renderer` from `plugin.register(SpinePlugin)` | registered before `await app.init()`; the plugin's `app` is still unset |
 | physics behaves differently after adding an adapter | expected — units and force scales differ; re-tune |
+| a Spine object slides off screen when the camera moves, or ignores its container (WebGL / WebGPU) | spine-plugin < 4.0.1 drew without the camera's and the parents' transform; upgrade |
+| a Spine object ignores `setOpacity()` / `alpha` | spine-plugin < 4.0.1; upgrade |
+| a game paused from its menu is running again after the app comes back from the background | capacitor-plugin < 1.0.1 resumed on every return; upgrade |
+| touch controls miss the finger after browser zoom or a move to another screen | gamepad-plugin < 1.2.1; upgrade |
 
 ## Related skills
 

package/skills/melonjs-renderables/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-renderables
-description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, and z-ordering. Triggers on: Tween, easing, animate, Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating."
+description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, z-ordering, y-sorting with sortOn and sortOffset, and Container clipping. Triggers on: Tween, easing, animate, Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, sortOn, sortOffset, autoSort, clipping, clipContains, anchorPoint, floating."
 license: MIT
 ---
 
@@ -67,14 +67,19 @@ class Button extends Renderable {
 The symptom is a handler that is registered, looks correct, and never fires.
 
 Note that `Container`, `Camera2d`, `Draggable`, `DropTarget` and the `UI*`
-elements set it to `false` for you, and so does the `Body` constructor on its
-owner (which covers `Entity` and anything you give a body to) — so a plain
-`Renderable` or `Sprite` subclass with no body is the case that catches people.
+elements set it to `false` for you, and so does giving a renderable a body (a
+`bodyDef`, on every physics adapter, or a `Body`, which covers `Entity`) — so a
+plain `Renderable` or `Sprite` subclass with no body is the case that catches
+people. Before melonJS 20.14, matter-adapter 1.6.0 and planck-adapter 1.7.0,
+only the built-in adapter cleared it: under matter or planck a renderable with
+a `bodyDef` stayed kinematic and missed pointer events.
 
 The same flag has a second, less obvious effect: it is also the opt-in to the
 world **broadphase**. The quadtree/octree insert skips any child with
 `isKinematic === true`, so body-less objects you want `adapter.queryAABB` /
-`querySphere` to find need `isKinematic = false` as well. The builtin
+`querySphere` to find need `isKinematic = false` as well. That is the built-in
+adapter; the `queryAABB` of matter, planck and Rapier only ever returns
+renderables with a body. The builtin
 narrowphase likewise requires *both* partners to be non-kinematic.
 
 ## 3. Draw order: only `addChild(child, z)` works
@@ -291,6 +296,19 @@ other correct ending.
 `obj.alwaysUpdate === true`. An off-screen object with the default
 `alwaysUpdate = false` does not tick at all.
 
+A `Container` is culled by its own bounds, which do not follow its children
+unless it has a size of its own (`resize`) or `enableChildBoundsUpdate` is on.
+With the flag, the bounds are the children's union, re-measured on every update
+and, while the group is off screen, before each culling check — so a squad that
+walks back into view is drawn again.
+
+`clipping = true` crops a container's children to its own rectangle, so it
+needs a size of its own: a sizeless container (the default) does not clip.
+Since 20.13 the pointer skips a child where it is cropped away, and
+`container.clipContains(x, y)` tells whether the container shows its children
+at a point (screen pixels for a floating one). A clip inside a clip shows
+their overlap, on WebGL and WebGPU as on Canvas.
+
 ## Anchors and floating
 
 - `anchorPoint` defaults to centre `(0.5, 0.5)` on `Renderable`, but `Container`
@@ -306,8 +324,10 @@ other correct ending.
 ## Prefer built-in features
 
 Before writing custom `draw()` code, check whether the engine already covers it —
-`ParticleEmitter`, `Tween`, the `ShaderEffect` presets, `UISpriteElement` and
-`UITextButton`, the physics adapters, and the Tiled tilemap renderers all exist.
+`ParticleEmitter`, `Tween`, the `ShaderEffect` presets, the UI widgets
+(`UITextButton`, `UISpriteElement`, `UIPanel`, `ProgressBar` and the rest, see
+`melonjs-ui-and-text`), `NineSliceSprite`, the physics adapters, and the Tiled
+tilemap renderers all exist.
 Hand-rolled equivalents miss the batching and the multi-backend support.
 
 ## Symptom → cause
@@ -322,14 +342,18 @@ Hand-rolled equivalents miss the batching and the multi-backend support.
 | effect silently does nothing | running on the Canvas renderer |
 | object appears frozen while its state changes | `update()` not returning `true` |
 | off-screen object never ticks | `update()` is gated on `inViewport` — set `alwaysUpdate = true` |
+| a group of moving children vanishes once they leave where they started | a sizeless container's bounds did not follow its children: give it a size, or `enableChildBoundsUpdate` (which only followed them from 20.13.0) |
 | 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 — `setPosition(x, y)` on the renderable leaves the depth alone |
 | 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` |
+| `clipping = true` crops nothing | the container has no size of its own: give it one (`resize`) |
+| a child cropped out of a clipping container still takes clicks where it is hidden | before 20.13 the pointer ignored the clip: update |
 
 ## Related skills
 - `melonjs-scenes-and-state` — `Tween` and the easing families, for animating any of this
 
 - `melonjs-getting-started` — Application lifecycle and the scene graph
+- `melonjs-ui-and-text` — the UI widgets, before drawing your own
 - `melonjs-20-migration` — the deprecated `shader` property and other pre-20 APIs

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-renderer-backends
-description: "Use this skill when a feature works on one machine and not another, when choosing or pinning a renderer, or when writing code that must degrade gracefully. Covers the WebGPU to WebGL 2 to Canvas fallback ladder, what each backend supports, capability detection, and the subsystems that warn once and then stop working on Canvas. Triggers on: video.AUTO, video.WEBGPU, video.WEBGL, video.CANVAS, renderer.type, supportsDepthBuffer, shaderLanguage, WebGPU, WebGL2, Canvas fallback, context loss, backend, works on my machine."
+description: "Use this skill when a feature works on one machine and not another, when choosing or pinning a renderer, or when writing code that must degrade gracefully. Covers the WebGPU to WebGL 2 to Canvas fallback ladder, what each backend supports, capability detection, and the subsystems that warn once and then stop working on Canvas. Triggers on: video.AUTO, video.WEBGPU, video.WEBGL, video.CANVAS, renderer.type, supportsDepthBuffer, shaderLanguage, WebGPU, WebGL2, Canvas fallback, failIfMajorPerformanceCaveat, software rendering, supportsHDR, hdrOutput, context loss, backend, works on my machine."
 license: MIT
 ---
 
@@ -27,6 +27,14 @@ await app.init();
 WebGL 1 is not in the ladder — 20.x made WebGL 2 the baseline, and pinning
 `video.WEBGL` **rejects** on a WebGL-1-only device rather than degrading.
 
+A GPU backend also counts as unavailable when the browser says it would run
+far slower than native — a software rasterizer, a blocklisted driver. The
+`failIfMajorPerformanceCaveat` setting (`true` by default, stricter than
+WebGL's own default) refuses such a context, and the WebGPU backend refuses a
+software adapter the same way: under `AUTO` that machine gets Canvas, and
+under `video.WEBGL` or `video.WEBGPU` `init()` rejects. Set it `false` to accept
+the slow context instead.
+
 ## What each backend can do
 
 | | WebGPU | WebGL 2 | Canvas |
@@ -36,21 +44,28 @@ WebGL 1 is not in the ladder — 20.x made WebGL 2 the baseline, and pinning
 | shaders and post effects | ✅ | ✅ | ❌ inert |
 | `Light2d` glow (`drawLight`) | ✅ | ✅ | ✅ cached radial gradient |
 | normal-map lighting, `Light3d` | ✅ | ✅ | ❌ inert |
-| `Mesh` | ✅ | ✅ | ⚠️ CPU-projected, no depth |
+| `Mesh` | ✅ | ✅ | ⚠️ last resort: 2D camera only, CPU-projected, no depth, unlit |
 | `Camera3d` / depth sorting | ✅ | ✅ | ❌ warns, renders wrong |
 | `InstancedMesh` | ✅ | ✅ | ⚠️ one draw per instance |
 | GPU tilemap rendering | ✅ | ✅ | ❌ per-tile CPU path |
+| `textureFilter: "linear-mipmap"` | ✅ | ✅ | ❌ no mipmaps |
+| `hdr` (headroom through the effects) | ✅ | ✅ where the driver can render and filter half-float | ❌ |
+| `hdrOutput` (HDR presentation) | ✅ with `hdr` on too | ❌ | ❌ |
+| `state.transition("pixelate", …)` | ✅ | ✅ | ❌ the state changes with no transition |
 
-The Canvas column is the problem: none of it throws. Each of those paths warns
-once and then degrades or no-ops, so the game runs and looks wrong.
+The Canvas column is the problem: none of it throws. Most of those paths warn
+once and then degrade or no-op, and some (the pixelate transition, `hdr`) do
+so without a word, so the game runs and looks wrong.
 
 Two Canvas rows are worth spelling out because they are easy to misread as total
 failures. A `Light2d` still *draws* — the Canvas renderer bakes a radial gradient
 per light and blits it — what disappears is per-pixel normal-map shading, which
 warns once (`Light2d normal-map lighting requires a GPU backend`), the first time
-a normal-mapped sprite is drawn under a light, and then renders sprites unlit. A `Mesh` still draws too, sorted with the painter's
-algorithm and no depth buffer, so convex models look right and anything
-self-overlapping does not. `"none"` (replace, alpha included) is the one blend
+a normal-mapped sprite is drawn under a light, and then renders sprites unlit. A `Mesh` under a 2D camera still draws too, textured,
+sorted with the painter's algorithm and no depth buffer, so convex models look
+right and a self-overlapping one can draw a few triangles over the wrong ones.
+That is a last resort so a game does not go blank, not a target: anything
+built on meshes should run on WebGPU or WebGL 2. `"none"` (replace, alpha included) is the one blend
 mode Canvas cannot express — there is no `globalCompositeOperation` that
 disables blending for the drawn area alone — so it resolves to `"normal"`, and
 `setBlendMode` reports that back.
@@ -65,7 +80,9 @@ app.renderer.shaderLanguage;          // "wgsl" | "glsl" | null (null on Canvas)
 
 There are narrower flags for the features that do not travel together:
 `supportsShaderTileLayers`, `supportsRetainedMesh` and `supportsInstancing` —
-all three `false` on Canvas, `true` on both GPU backends. Prefer a capability
+all three `false` on Canvas, `true` on both GPU backends. `supportsHDR` and
+`supportsHDROutput` say what the `hdr` and `hdrOutput` settings were actually
+granted, which can be less than was asked. Prefer a capability
 flag over comparing `type` against a string; `type` is an identity check for
 code coupled to one backend's machinery.
 
@@ -160,12 +177,12 @@ or the `#webgpu` / `#webgl` URI fragment on a page you can open by hand.
   `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
+  cannot appear on one backend and stops the game dead on the other. Check
+  any canvas the game sizes from content that can be empty before it is drawn.
+  An empty or whitespace-only `Text` did this before 20.11; its glyph canvas
+  is now at least 32 pixels on each side.
+- **3D meshes do not honour the advanced blend modes.** The mesh pass draws
+  with its own depth/blend state; asking for one of them logs a one-time
   `blend mode "…" is not supported for 3D meshes` warning and falls back to
   `"normal"`. Gradient fills warn the same way.
 
@@ -175,14 +192,18 @@ or the `#webgpu` / `#webgl` URI fragment on a page you can open by hand.
 |---|---|
 | effect works locally, not for a user | they got the Canvas fallback, or a different GPU backend |
 | sprites render unlit though lights are in the scene | Canvas fallback — normal-map shading is inert (check the console) |
-| mesh looks inside-out where it overlaps itself | Canvas fallback — painter's algorithm, no depth buffer |
+| a few triangles of a mesh drawn over the wrong ones where it overlaps itself | Canvas fallback — painter's algorithm sorts whole triangles, no depth buffer |
+| a mesh shows its far side through its near one (looks inside-out) on Canvas | melonJS older than 20.14 sorted the triangles the wrong way round; update |
+| a textured OBJ + MTL mesh is a white silhouette on Canvas | melonJS older than 20.14 filled it with its material color and skipped the texture; update |
+| a low-poly (palette) model looks faceted on Canvas, with faint lines between its triangles | melonJS older than 20.14 filled each of its triangles with one texel; update |
 | shader works on one machine only | GLSL-only effect, AUTO chose WebGPU elsewhere — the console carries the warning |
 | 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 |
+| `copyExternalImageToTexture: External image state is not valid` | a zero-sized upload source: a canvas sized from empty content (an empty `Text` before 20.11) |
+| Canvas renderer on a machine that has a GPU, or `init()` rejects with a pinned backend | software rendering or a blocklisted driver, refused by `failIfMajorPerformanceCaveat` (default `true`) |
 | 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 |
+| an advanced blend mode is ignored on a mesh | meshes fall back to `"normal"` for those; look for the one-time warning |
 | textures vanish after the tab is restored | cached raw GPU handles not re-acquired on context restore |
 
 ## Related skills

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-scenes-and-state
-description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
+description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, pixelate, Trigger transition, retry level, state.pause, pauseOnBlur, resumeOnFocus, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
 license: MIT
 ---
 
@@ -59,6 +59,12 @@ was drawn unstepped, and showed the stage's background alone for one frame.
 registered for that id, and `state.set` throws if the second argument is not a
 `Stage` instance. Neither fails quietly.
 
+A change to the state that is **already current does nothing**: no
+`onDestroyEvent`, no `onResetEvent`, no transition. So a "Retry" that calls
+`state.change(state.PLAY)` from `PLAY` is ignored; reload the level with
+`level.reload()`, or go through another state (a game-over or `READY` screen)
+and back.
+
 ### Always leave `state.LOADING` — it is transitional
 
 `loader.preload()` switches to `state.LOADING` for you. Building your scene in
@@ -107,6 +113,9 @@ this.HUD.floating = true;               // screen coordinates, not world
 app.world.addChild(this.HUD, 100);      // explicit z — see melonjs-renderables
 ```
 
+Everything inside a persistent container is kept with it, physics bodies
+included (before 20.13 the children's bodies were dropped by the reset).
+
 ## Transitions and pausing
 
 ```js
@@ -119,11 +128,21 @@ app.freeze(150);                             // brief hit-stop (proxies state.fr
 ```
 
 `state.transition` is global and sticky — once set it applies to every later
-`state.change`. The `"mask"` form needs its fourth argument, an `Ellipse` or
+`state.change`; `state.setTransition(id, false)` turns it off for changes
+into one state.
+The duration (1000 ms when omitted) is for each half: the cover, then the
+reveal. The `"mask"` form needs its fourth argument, an `Ellipse` or
 `Polygon`; without one it warns and falls back to a direct switch. The
 `"pixelate"` form breaks the screen up into blocks (its fourth argument is the
-largest block size in pixels). It is a shader effect, so on Canvas it does
-nothing and the state changes directly.
+largest block size in pixels; the color is not used). It is a shader effect,
+so on Canvas it does nothing and the state changes directly.
+
+A level change is not a state change, so `state.transition` does not apply to
+it. A Tiled `Trigger` that loads a level has a transition of its own, set on
+the trigger: `color` and `duration` (both needed, or the level loads with
+none), and `transition: "fade"` (the default) or `"mask"` with a `shape`.
+A `"mask"` without a `shape` fades instead, without a warning, and there is
+no pixelate form for a trigger. See `melonjs-tilemaps`.
 
 A `state.change` asked for while a transition covers the screen (Enter pressed
 twice on a menu, a timer firing as the player skips a screen) needs no guard:
@@ -146,7 +165,8 @@ 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**.
+own `update()` keeps running**. (`event.GAME_UPDATE` is not emitted while
+paused, so logic hung off it stops with the world.)
 
 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
@@ -172,6 +192,10 @@ 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.
 
+On focus, `resumeOnFocus` (default `true`) undoes only the pause the
+application applied on blur. A game the player paused from its own menu stays
+paused when the window comes back; before 20.9 it resumed underneath the menu.
+
 ## The update loop
 
 There is no loop you own. Logic goes in `update(dt)` overrides, or a
@@ -314,6 +338,14 @@ Four traps:
 - **Stop a tween before destroying its target**, or `onUpdate` fires against a
   dead renderable.
 
+**A target can be an array: a path.** `to({ x: [200, 120, 300] })` runs from
+the current value through each entry in turn, and
+`interpolation: Tween.Interpolation.CatmullRom` smooths the corners. Each
+`start()` builds the path afresh from the current value, so a replay or a chain
+that comes back round runs the same path, and with `yoyo` the return leg plays
+it back the way it came. Before 20.13 a restart ran a longer path each time and
+a `yoyo` path turned the property into `NaN`.
+
 **To animate something that is not a property, tween a holder and push the
 value in `onUpdate`.** A shader uniform and a light's intensity are both set
 through a method, so there is nothing for `to()` to interpolate directly. The
@@ -387,6 +419,7 @@ import { save } from "melonjs";
 
 save.add({ hiscore: 0 });      // once; idempotent, loads any stored value
 save.hiscore = 1200;           // plain assignment writes to localStorage
+save.remove("hiscore");        // gone from localStorage; set it again to save it again
 ```
 
 **In TypeScript, keep what `add()` returns.** The namespace carries a
@@ -410,15 +443,22 @@ both.
 |---|---|
 | scene builds once and is empty on return | content created in the constructor, not `onResetEvent` |
 | `Undefined Stage for state 'N'` thrown | no `state.set` for that id first |
+| `state.change(state.PLAY)` from `PLAY` does nothing ("Retry" ignored) | a change to the current state is a no-op — `level.reload()`, or go through another state |
+| a level change through a `Trigger` ignores `state.transition` | it is a level change, not a state change: set `color` and `duration` (and `transition`) on the trigger |
+| the game stops updating for good after one very slow update, such as a heavy first frame (20.12 and 20.13) | the loop could no longer save enough time to step the world: update |
+| the game resumes under its own pause menu after a tab switch (before 20.9) | focus undid any pause; update, only the blur pause is undone |
 | 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 |
+| an array (path) tween wanders further on each replay, or goes `NaN` with `yoyo` | before 20.13 `start()` re-prepended the start value to the path and `yoyo` swapped the array into the start value; upgrade |
+| a repeating or `yoyo` tween runs a single cycle when started again (a pulse pulses once, a yoyo stays at the far end) | before 20.13 `start()` did not restore the `repeat` count the first run had used up; upgrade |
 | effect stops during a hit-stop | tween needs `updateWhenPaused = true` |
 | crash after a stage switch | callback ran during teardown — guard with `state.isCurrent` |
 | HUD scrolls away with the camera | missing `floating = true` |
+| a `save` key set again after `save.remove()` reads back fine, then is gone (or back at its default) after a reload (before 20.13) | the write skipped the list of keys restored at boot; update |
 
 ## Related skills
 

package/skills/melonjs-sprites-and-animation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-sprites-and-animation
-description: "Use this skill when creating sprites, playing frame animations, or working with texture atlases in melonJS. Covers Sprite construction from a plain image or an atlas region, addAnimation/setCurrentAnimation, TextureAtlas for TexturePacker/ShoeBox/Aseprite, tint, flip, NineSliceSprite, and the centred anchorPoint that offsets naive positioning. Triggers on: Sprite, new Sprite, addAnimation, setCurrentAnimation, isCurrentAnimation, TextureAtlas, TexturePacker, Aseprite, ShoeBox, atlas, region, framewidth, frameheight, tint, flipX, flipY, NineSliceSprite, animation."
+description: "Use this skill when creating sprites, playing frame animations, or working with texture atlases in melonJS. Covers Sprite construction from a plain image or an atlas region, addAnimation/setCurrentAnimation, TextureAtlas for TexturePacker/ShoeBox/Aseprite, tint, flip, NineSliceSprite, and the centred anchorPoint that offsets naive positioning. Triggers on: Sprite, new Sprite, addAnimation, setCurrentAnimation, isCurrentAnimation, onFrame, onComplete, play, pause, flicker, anchorPoint, TextureAtlas, TexturePacker, Aseprite, ShoeBox, atlas, region, framewidth, frameheight, tint, flipX, flipY, NineSliceSprite, animation."
 license: MIT
 ---
 
@@ -20,6 +20,10 @@ sprites appear to disagree.
 const s = new Sprite(100, 100, { image: "hero", framewidth: 64, frameheight: 64 });
 
 s.anchorPoint.set(0, 0);   // switch to top-left positioning if you prefer
+
+// or in the settings, by name: "top-left", "bottom" (the feet), "center",
+// "top", "left", "right", "top-right", "bottom-left", "bottom-right"
+const hero = new Sprite(x, y, { image: "hero", anchorPoint: "bottom" });
 ```
 
 Writing top-left maths against the centred default puts everything half a sprite
@@ -93,7 +97,30 @@ attack) needs no manual switch back to idle.
 
 Re-selecting the animation that is already current is a no-op, so calling
 `setCurrentAnimation` every frame is safe, and an `isCurrentAnimation` check
-around it adds nothing. An unknown id throws.
+around it adds nothing. **The exception is a `loop: false` run that has
+finished**: selecting it again plays it again, so a death animation selected
+every frame replays forever. Select a play-once animation once, on the event
+that starts it. An unknown id throws.
+
+A frame can carry its own delay, as `{ name, delay }` in place of the index or
+region name: `[{ name: 3, delay: 200 }, { name: 4, delay: 100 }]`.
+`play(name?, options?)` switches and plays (or, with no name, resumes),
+`pause()` freezes the current frame and `stop()` rewinds to the first one and
+pauses there; the options are `setCurrentAnimation`'s.
+
+`addAnimation` with an id that exists replaces it, which is how you change an
+animation's frames or speed (`hero.addAnimation("walk", [4, 5, 6, 7], 200)`).
+Redefining the one that is playing takes effect at once: the playing frame is
+kept if the new strip still has it, playback restarts on frame 0 if not, a
+finished `loop: false` run holds the new last frame, and the
+`setCurrentAnimation` options stay. Before 20.13 it kept the old frame count, so
+a shorter strip threw on the next `update()` and a longer one never reached its
+new frames.
+
+Since 20.14, a frame the texture does not have (a number past the end of the
+sheet, a name the atlas does not hold) is left out with a console warning
+naming it, and the frames that exist play in order; `addAnimation` returns how
+many it kept.
 
 ## Texture atlases
 
@@ -125,6 +152,9 @@ sprite.flipX(true);                   // mirror horizontally
 sprite.flipY(true);
 sprite.blendMode = "additive";        // see the effects skill for the full list
 sprite.scale(2, 2);                   // ← multiplicative, see below
+sprite.flicker(1000, function () {    // blink for a second, then…
+    this.ancestor.removeChild(this);  // …`this` is the sprite; the flicker has ended
+});
 ```
 
 **`scale()` is multiplicative, not absolute.** Calling it every frame compounds.
@@ -185,6 +215,11 @@ Two consequences:
 | event handlers leak on pooled objects | bound in the constructor rather than `onActivateEvent` |
 | animation never advances | no `framewidth`/`frameheight`, so the sheet is one frame |
 | animation plays once and stops | `{ loop: false }`, or a callback that returned `false` |
+| a `loop: false` animation keeps replaying | `setCurrentAnimation` called every frame: a finished play-once run is restarted by selecting it again |
+| a one-frame animation never calls its `onComplete` | a looping one-frame animation does not step; play it with `loop: false` or `next` (before 20.12 even those never completed) |
+| `TypeError` reading `offset` or `delay` in `update()` after re-adding the playing animation with fewer frames, or a longer one never shows its new frames | before 20.13 redefining the current animation kept its old frame count; upgrade |
+| a console warning `addAnimation("walk"): no frame … in the texture`, or a `TypeError` reading `delay` / `offset` on an older melonJS | a frame number or name the sheet or atlas does not have (often an atlas re-exported without one of its images): fix the frame list or re-export the atlas |
+| `this` is wrong in a `flicker(ms, callback)` callback, or a flicker started from it stops at once | before 20.13.0 the callback ran on an internal object and the flicker was stopped after it; now `this` is the sprite and the flicker has already ended |
 | sprites do not batch | more distinct textures in one frame than `renderer.maxTextures` |
 | nine-slice corners stretch anyway | `insetX`/`insetY` instead of `insetx`/`insety` |