melonjs 20.13.0 → 20.14.0

package/skills/melonjs-plugins/SKILL.md

@@ -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
@@ -109,8 +122,10 @@ 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. See `melonjs-input` for the bindings,
-the layouts and the overlap rules.
+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`
 
@@ -126,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`.
@@ -200,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
@@ -297,6 +302,13 @@ 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`
@@ -312,8 +324,10 @@ walks back into view is drawn again.
 ## 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
@@ -334,9 +348,12 @@ Hand-rolled equivalents miss the batching and the multi-backend support.
 | `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
@@ -122,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:
@@ -149,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
@@ -175,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
@@ -422,6 +443,10 @@ 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` |

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,16 @@ 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)`).
@@ -104,6 +117,11 @@ finished `loop: false` run holds the new last frame, and the
 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
 
 `TextureAtlas` reads several formats:
@@ -197,7 +215,10 @@ 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` |

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, and reading or changing tiles while the game runs. Covers registerTiledObjectClass and the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, setTile, clearTile, cellAt, getTile, getTileById, change a tile, tile at run time, game board, grid, tile properties at run time, getTileProperties, map properties, level.load, level.load async, await level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax, registerTiledObjectClass, registerTiledObjectFactory, TMXObject, resolvedProperty, resolvedProperties, tile class, tile properties."
+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, and reading or changing tiles while the game runs. Covers registerTiledObjectClass and the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, setTile, clearTile, cellAt, getTile, getTileById, change a tile, tile at run time, game board, grid, tile properties at run time, getTileProperties, map properties, level.load, level.load async, await level.load, tileset, ImageLayer, infinite map, render order, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax, registerTiledObjectClass, registerTiledObjectFactory, TMXObject, resolvedProperty, resolvedProperties, tile class, tile properties."
 license: MIT
 ---
 
@@ -25,12 +25,29 @@ await loader.preload([
 level.load("map1");           // inside Stage.onResetEvent
 ```
 
+**A game with several maps** keeps each map and the images only it uses in a
+bundle of its own, beside a `common` bundle for the shared tileset, the player
+and the sounds: an assets file exporting `{ common: [...], map1: [...],
+map2: [...] }`, passed as it is to `loader.preload()`. A map's level can then be
+freed with `loader.unload("map1")` and brought back with
+`await loader.load("map1")` before `level.load("map1")`; a game whose maps
+loop back simply keeps them all loaded. `melonjs-loading-assets` covers the
+pattern.
+
 Asset `type` is `"tmx"` for maps and `"tsx"` for external tilesets — those are
 the only two type strings the loader knows. The *file* can be `.tmx` / `.tsx`
 (XML), or `.json` / `.tmj` / `.tsj`; the parser branches on the extension, not
 on the type. `type: "tmj"` throws `unknown or invalid resource type`. You can
-also skip `src` and pass the map inline via `data` (with `format: "json"` or
-`"xml"`).
+also skip `src` and pass the map inline via `data`, as the parsed JSON object
+of a Tiled JSON export (not an XML string).
+
+**Prefer JSON where there is no DOM.** XML maps and tilesets are parsed with
+`DOMParser`, which only a page has: in a Web Worker, or on nx.js (the Nintendo
+Switch, see `melonjs-deployment`), loading one fails, and `preload()` rejects
+with "Failed loading resource …" whose `cause` (also logged to the console)
+says to export it as JSON. Export the map *and* its external tilesets as
+`.tmj` / `.tsj` (Tiled: File → Export As, or set JSON as the format in the
+project).
 
 `level.load(levelId, options)` accepts `container` (default `game.world`),
 `onLoaded` (default `game.onLevelLoaded`), `flatten` (default `game.mergeGroup`),
@@ -178,9 +195,12 @@ authored against melonJS 1.x finds them where it looks.
 
 A `Trigger` forwards a **fixed list** of settings to `level.load()` — not
 whatever you pass it. Today that list is `container`, `onLoaded`, `flatten`,
-`setViewportBounds` and the glTF scene options (`scale`, `rightHanded`,
-`lights`, `lightIntensityScale`, `castGroundShadow`, `shadowGroundY`); see the
-3D assets skill. Anything outside it is **dropped silently**, which is worth
+`setViewportBounds` and the glTF scene options: `scale`, `rightHanded`,
+`lights`, `lightIntensityScale` and the ground-shadow settings
+(`castGroundShadow`, `shadowGroundY`, `shadowOpacity`, `shadowScale`,
+`shadowOffset`, `shadowStretch`, `shadowDirectionX`, `shadowDirectionZ`,
+`shadowGroundNormal`, `shadowLight`, but not `shadowGroundPoint`); see the 3D
+assets skill. Anything outside it is **dropped silently**, which is worth
 knowing before you spend an afternoon on a map that loads at the wrong scale.
 `async` is excluded deliberately — the trigger needs to sequence its own
 transition.
@@ -224,8 +244,17 @@ for (let row = board.starty; row < board.starty + board.rows; row++) {
 }
 ```
 
-The viewport bounds still cover only the map's `width` x `height`: set them
-yourself to scroll to tiles painted outside it.
+An infinite map's `getBounds()` (and its `width` / `height`) covers the map's
+own area and every painted tile, so a level loaded with `setViewportBounds`
+lets the camera reach tiles painted past the map's size, or left of or above
+its origin. Empty chunk cells past the last painted tile are not part of it.
+Size a camera you set up yourself from `map.getBounds()`, not from
+`cols * tilewidth`, which is only right for an orthogonal map:
+
+```js
+const b = level.getCurrentLevel().getBounds();
+app.viewport.setBounds(b.left, b.top, b.width, b.height);
+```
 
 A `Tile` carries `tileId` (its **global** id), `col`, `row` and `tileset`.
 Tiled shows a tile's *local* id in the tileset editor; the global id is
@@ -271,7 +300,8 @@ their own (`title`, not `name`).
 
 ## Camera bounds
 
-`level.load` sets the viewport bounds to the map size for you —
+`level.load` sets the viewport bounds to the map's bounds for you (on an
+infinite map, every painted tile, see above) —
 `setViewportBounds` defaults to `true`, and the handler is re-run on every
 viewport resize, centring the map when it is smaller than the screen. You only
 need to do it by hand when you opted out:
@@ -415,14 +445,17 @@ per-pixel GID lookup in the fragment shader. It requires **all** of:
 - `world.gpuTilemap !== false` (the `gpuTilemap` application setting, default `true`),
 - an **orthogonal** layer — isometric, hexagonal, staggered and oblique always
   fall back,
-- no collection-of-image tileset, no non-zero `tileoffset`, and tile overflow
-  within the shader's 4-cell limit.
-
-When a layer falls back, melonJS `console.warn`s once with the reason. Practical
-consequences: fewer tilesets means fewer batches (one packed tileset beats
-several small ones), and on the Canvas fallback large maps get noticeably
-slower. `world.preRender` (or a `preRender` layer property in Tiled) opts an
-unanimated layer into the offscreen-bake path instead.
+- no collection-of-image tileset, no non-zero `tileoffset`, a tileset tile
+  render size of "Tile size" (`tilerendersize`, not "Map grid size"), and tile
+  overflow within the shader's 4-cell limit.
+
+When a layer falls back, melonJS `console.warn`s the reason each time the
+layer is activated (once per page when the renderer has no GPU tile support at
+all), and says nothing while `gpuTilemap` is off. Practical consequences:
+fewer tilesets means fewer batches (one packed tileset beats several small
+ones), and on the Canvas fallback large maps get noticeably slower.
+`world.preRender` (or a `preRender` layer property in Tiled) opts an unanimated
+layer into the offscreen-bake path instead.
 
 ## Symptom → cause
 
@@ -432,7 +465,7 @@ unanimated layer into the offscreen-bake path instead.
 | 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 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` |
+| `level <id> not found` | the map was never preloaded, its bundle was unloaded (`await loader.load(bundleId)` first), 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`) |
 | `No inflate function set` at parse time | compressed layers without the tiled-inflate plugin |
@@ -446,12 +479,17 @@ unanimated layer into the offscreen-bake path instead.
 | a property set on a tile is undefined on the object's `settings` | tile properties are not copied onto `settings`: read them with `settings.resolvedProperty(name)` |
 | objects placed from a classed tile come out as plain sprites | that class is not registered, it is a built-in name, or the object has a class or a registered name of its own, which come first |
 | missing tiles or a blank map | the `.tsx` or tileset image was not preloaded |
+| a map fails to load with "needs DOMParser" (in the error's `cause` and the console) | an XML `.tmx` / `.tsx` loaded where there is no DOM (a Web Worker, nx.js): export the map and its tilesets as JSON (`.tmj` / `.tsj`) |
 | a tileset's transparent color (`trans`) still shows (the console says it could not be applied) | the image cannot be read back: an image the game made itself from another origin without CORS (an `<img>` with no `crossOrigin`) cannot be, so load it with the loader, which only loads an image another origin's server allows (its CORS headers) and can always read back; and a compressed texture cannot be changed: export it with an alpha channel instead |
 | `cellAt` returns `null` (or the wrong tile) for a cell that has one | it was given pixels: `cellAt`, `setTile` and `clearTile` take column and row, only `getTile` takes world pixels |
 | `setTile` shows the wrong tile, or nothing | it was given Tiled's local tile id: use the global id, `tileset.firstgid + localId`, through `getTileById` |
+| on an infinite map the camera stops before tiles painted past the map's size, or left of or above its origin | an older melonJS held the camera to the map's width and height from (0, 0): update; and size a camera you set up yourself from `map.getBounds()` |
+| oversized tiles overlap in the wrong order (the map's render order is not "right-down") | an older melonJS drew every layer "right-down", whatever the map's render order: update |
 | an infinite map's tiles sit in the wrong row, or tiles left of or above the origin are missing | an older melonJS ignored where the chunks start (update); and loop from `layer.startx` / `layer.starty`, not 0, to reach cells left of or above the origin |
 | on a staggered map `getTile` gives the neighbouring tile on every row but the first, or a scrolled view draws nothing | a bug of older melonJS versions in the staggered renderer: update |
 | on an isometric (or staggered, oblique) map `getTile` gives an edge tile for a point just outside the tiles | an older melonJS rounded a fractional column or row toward 0: update |
+| on an isometric map a tile drawn by hand with the map renderer's `drawTile()` lands away from where the layer draws that cell | before 20.14 the isometric `drawTile()` placed it differently from the layer: update |
+| a repeating `ImageLayer` slides off the screen once the camera has moved far enough | before 20.12 its repeat did not follow the camera: update |
 | tiles of a second tileset draw from the first tileset's image (that first one has a `margin`) | an older melonJS let its gid range overrun into the next tileset (update): the range is the `tilecount` Tiled saved |
 | a layer is `undefined` from `getChildByName(name)[0]` | the level is not in the world yet (await `level.load(id, { async: true })`), or the name differs from the layer's in Tiled |
 | a tile set or cleared at run time does not block or free movement | tile layers carry no collision: collision comes from collision object layers |