melonjs 20.11.0 → 20.13.0

package/skills/melonjs-particles-and-trails/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-particles-and-trails
-description: "Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter, tintOverLife, colour over life, color over life, flame, fire."
+description: "Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, particle editor, tune particles, spawn depth, volume, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter, tintOverLife, colour over life, color over life, flame, fire."
 license: MIT
 ---
 
@@ -28,6 +28,50 @@ emitter.burstParticles();      // one shot
 `duration` setting, which defaults to `Infinity` — a stream runs until
 `stopStream()`. `burstParticles(n)` launches `n`, or `totalParticles`.
 
+Without an `image`, particles are white squares of `textureSize` pixels (8 by
+default), coloured by `tint`. Every such emitter draws the renderer's one
+shared white pixel, stretched, so an emitter per explosion or a `reset()` on
+every tweak costs no texture.
+
+## Tuning an effect: the Particle Editor
+
+Settings are easier to find by eye than by reasoning. The
+[Particle Editor](https://melonjs.github.io/melonJS/examples/#/particle-editor)
+runs one emitter live, with every setting on a slider, from a preset (fire,
+smoke, rain, explosions, 3D bursts and rings…), a built-in texture or a sprite
+(sheet) of your own, under a 2D camera or an orbiting 3D one. It writes out the
+matching `new ParticleEmitter(...)` call, listing only what differs from the
+defaults, and the same settings as JSON, in the emitter's own units, to load at
+run time:
+
+```js
+// preloaded with { name: "smoke-fx", type: "json", src: "data/fx/smoke.json" }
+const effect = loader.getJSON("smoke-fx");
+const emitter = new ParticleEmitter(x, y, {
+    ...effect.settings,
+    // no `image` for the plain square: `getImage` would give null
+    ...(effect.image ? { image: loader.getImage(effect.image) } : {}),
+});
+```
+
+Point a user there when they are tuning numbers by trial and error.
+
+It covers every setting that changes how one emitter looks, but not:
+
+- **Layered effects.** It shows one emitter at a time. A campfire (flames,
+  sparks, smoke) or an explosion (flash, debris, smoke) is several emitters
+  at the same spot: tune each in the editor, then add them side by side,
+  the one drawn on top last (or with a higher `z`).
+- **Trails.** `Trail` and `Trail3d` are separate renderables; see below.
+- **Code-only settings.** `onComplete`, `autoDestroyOnComplete`,
+  `accurateBounds`, and a `Container` as `referenceSpace` (it offers
+  `"local"` and `"world"`). `textureAdditive` is left out: `blendMode`
+  replaces it.
+- **Changes at run time.** Calling `burstParticles()` when something
+  happens, or assigning `emitter.blendMode` while particles are alive, is
+  game code. Its "moving emitter" option previews the common case: an
+  emitter attached to something that moves.
+
 ## Sprite-sheet particles
 
 Use `framewidth` and `frameheight` (the same names as on `Sprite`) to divide
@@ -107,15 +151,33 @@ fountain and wrong for an explosion: additive sprites piled on one point clip
 all three channels there however well they are tinted, so a burst reads as one
 bright flash rather than as debris.
 
-Give it the size of whatever broke. The area is measured from the emitter's own
-position, NOT centred on it, so offset by half or the whole burst sits down and
-to the right of its source:
+Give it the size of whatever broke. The constructor centres the area on the
+point it is given, so pass the centre of the source:
 
 ```js
 const area = radius * 2;
-const emitter = new ParticleEmitter(x - area / 2, y - area / 2, {
-    width: area, height: area,
-});
+const emitter = new ParticleEmitter(x, y, { width: area, height: area });
+```
+
+After that, `pos` is the area's top-left corner, as on any renderable. To move
+the emitter to a new source later, offset by half, or the burst sits down and
+to the right of it:
+
+```js
+emitter.pos.set(x - area / 2, y - area / 2);   // re-aimed at (x, y)
+emitter.burstParticles();
+```
+
+Under a `Camera3d`, `depth` (20.13) gives the area its third side: each
+particle is born at a random depth within it, centered on the emitter's own
+depth, unlike `width` and `height`. Without it every particle starts on one
+plane facing the camera, so rain or dust seen from the side is a flat sheet. A
+2D camera does not show depth, though with an order-dependent blend the
+particles are still sorted by it. It is the spawn box's size, not the
+emitter's `depth` property, which is where the emitter sits along Z.
+
+```js
+new ParticleEmitter(x, y, { width: 600, height: 20, depth: 400 });   // a volume of rain
 ```
 
 ## Particles in 3D
@@ -321,6 +383,7 @@ answer when you want discrete puffs rather than a continuous ribbon.
 |---|---|
 | trail looks flat under a `Camera3d` | `Trail` is 2D; use `Trail3d` |
 | particles clutter a minimap or a second camera | every camera draws them: set the emitter's `visibilityLayer` to a layer that camera's `cullMask` leaves out (see `melonjs-camera-and-drawing`) |
+| a camera that draws only the emitter's layer shows no particles | before 20.13 particles stayed on layer 1 whatever their emitter was on; update |
 | `Trail3d` draws nothing, with a console warning | it needs a `Camera3d`; the app's `cameraClass` is still the 2D default |
 | `trail.tint` does nothing | `Trail` cannot be tinted at all; `Trail3d` can |
 | assigning `maxPoints` throws | `Trail3d` sizes its geometry once; pass `length` to the constructor |
@@ -335,7 +398,8 @@ answer when you want discrete puffs rather than a continuous ribbon.
 | frame rate drops with many effects | an emitter per event instead of one re-aimed emitter |
 | a 3D burst is invisible under a `Camera3d` | before 20.8 a particle was culled at twice its depth; update |
 | the whole burst launches from one pixel | `width`/`height` are the spawn area and default to `1` |
-| the burst sits down-right of its source | the spawn area starts at the emitter's position; offset by half |
+| the burst sits down-right of its source | the emitter was moved by setting `pos` to the source: `pos` is the area's top-left corner, so offset by half (only the constructor centres it) |
+| the burst sits up-left of its source | the constructor was given the top-left corner: it centres the area on (x, y), so pass the centre |
 | the middle of a burst goes white | additive sprites overlapping — `textureAdditive: false`, or spread them |
 | debris chunks look like squares | the default sprite is a filled square; pass your own `image` |
 | a ring tilts with the camera instead of staying on a surface | the launch axis is in WORLD axes, not the camera basis |

package/skills/melonjs-performance/SKILL.md

@@ -222,6 +222,9 @@ queries one at a time, usually not. See `melonjs-3d` for the decision table.
 
 - `stream: true` on long music tracks plays through a streaming element instead
   of decoding the whole file into memory.
+- `preload: false` on music a player may never reach (a boss theme, the
+  ending) keeps it out of the initial download: it is fetched and streamed
+  when first played.
 - `pool` on an audio clip sizes the reuse pool for finished instances — it is
   **not** a concurrency cap.
 - `loader.unloadAll()` between large levels drops every loaded asset and

package/skills/melonjs-physics/SKILL.md

@@ -152,6 +152,11 @@ class Player extends Sprite {
 The engine forwards it to the active adapter when the renderable is added with
 `Container.addChild`, and only if that container is already attached to the root
 world; the broadphase picks the renderable up on the next `world.update()`.
+Nesting is fine: adding a container registers the body of every renderable
+below it, at any depth, and removing it — destroyed, pooled or kept alive —
+takes them all out again, so moving a whole group with `other.addChild(group)`
+keeps each body simulated, once. A persistent container's children keep their
+bodies through `world.reset()` (a state change or `level.load`).
 Calling `adapter.addBody()` yourself registers the body but leaves the
 renderable out of the scene graph, so it integrates but never collides.
 
@@ -270,6 +275,13 @@ samples it down and keeps the extent. Anything the 2D backends cannot express
 is refused loudly on both, rather than leaving a body with no collision
 geometry that silently never collides.
 
+A polygon may be wound either way: its edge normals are oriented outward from
+its signed area. Before 20.13 they pointed inward on a counter-clockwise
+polygon — a Tiled polygon drawn that way, anything mirrored with
+`scale(-1, 1)` or a `Rect` of negative width — and the built-in circle test
+then collided a circle with it from tens of pixels away, as soon as their
+bounding boxes met. Polygon against polygon was never affected.
+
 Whatever a backend really simulates is what `getBodyShapes()` reports, so the
 debug panel is the fastest way to see an approximation for what it is.
 
@@ -533,6 +545,15 @@ and only active under a 3D broadphase — i.e. `world.sortOn === "depth"`, which
 `world.adapter.capabilities.raycasts3d` before calling either. `raycast` itself
 is capability-gated by `capabilities.raycasts`.
 
+On the built-in adapter a 2D ray measures each shape the way the narrowphase
+measures it against a planar shape: polygons, `Rect`, `RoundRect` and `Line`
+by their edges, an `Ellipse` with its rotation, a `Box3d` by its XY footprint
+and a `Sphere` as a circle of its radius (a 2D ray is unbounded along Z). A
+`Point` has no area to cross and is skipped, as is an unknown shape type,
+with a one-time console warning. Before 20.13 a body carrying a `Point`,
+`Sphere` or `Box3d` made every ray that reached it throw, and a rotated
+ellipse was hit where it would have been unrotated.
+
 The legacy `collision.rayCast(line, result)` is a different API: it takes a
 `Line`, returns an **array** of every intersecting renderable, and only exists
 on the built-in path.
@@ -629,8 +650,9 @@ 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
+list on every update (after the children have moved, and before each culling
+check while it is off screen) — 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
@@ -656,13 +678,25 @@ real rigid-body engine:
 - **`applyForce(x, y)` is linear only** unless you pass the optional
   `(pointX, pointY)` application point, which generates a torque
   `τ = r × F` into `body.angularVelocity` via `body.pseudoInertia`.
-  `applyTorque(τ)` is the direct form.
+  `applyTorque(τ)` is the direct form. The point is in **world** coordinates,
+  as on matter and planck, and the lever arm is measured from the centre of
+  the shapes where they collide: the renderable's drawn frame (so the anchor
+  counts) plus any parent container's position. `renderable.getBounds()` is
+  in that space, so `b.centerX, b.top` is the top centre.
 - **Force accumulators reset at end-of-step** — for every body, including
   static, paused and off-screen ones — so forces must be applied every frame to
   persist.
 - **`isGrounded` is flag-based, not contact-based** — the adapter returns
   `!body.falling && !body.jumping`, flags updated by the last resolved
-  collision, not a live contact test.
+  collision, not a live contact test. The DIRECTION of the push-out decides
+  them: pushed up out of a floor while not rising is a landing, pushed down
+  by a ceiling while rising (or `jumping`) ends the jump and falls, and a
+  side contact, a body touched from above while standing, or a body with
+  `gravityScale` 0 leaves them alone. Before 20.13 a magnitude test decided
+  instead, so anything that sank a pixel or more per step — gravity above
+  about `1.02`, mass above about `1.03`, `timer.tick > 1` at a low frame
+  rate, a floor moving up under it — stayed `falling` while sitting flush on
+  the floor, and could never jump.
 - **`def.density` maps 1:1 to `body.mass`** (default `1`), and `def.friction` is
   **ignored** entirely. `body.friction` is a per-axis `Vector2d` of per-step
   velocity damping fed from `def.frictionAir`, not a surface coefficient.
@@ -694,6 +728,12 @@ shape that is close enough at every angle (a circle, or a square for
 90° steps), or rotate the shapes yourself with `body.rotate(angle)` — which
 does rotate them, unlike `setAngle()`.
 
+The visual turn pivots on the centre of the body's shapes, where they are
+drawn and collide, whatever the renderable's `anchorPoint`. Before 20.13 it
+ignored the anchor, so a centre-anchored renderable turned about its
+bottom-right corner and swung away from where it stood; only a `(0, 0)`
+anchor turned in place.
+
 `body.rotate()` applies a **delta** and does not update `body.angle`; the two
 are unlinked, so a body driven by `rotate()` still reports an angle of `0`.
 Track it yourself if you need to read it back. Before 20.7 it also threw on a
@@ -775,12 +815,21 @@ use them. `adapter.capabilities` (`constraints`,
 | a small shape sits at the sprite's corner | a shape's offset is measured from the drawn frame's TOP-LEFT; `new Sphere(0, 0, 0, r)` is the corner, `(width / 2, height / 2)` is the centre |
 | a rotated renderable reports an unrotated bounding box | `autoTransform: false` opts `updateBounds()` out of the transform |
 | a body in a pile sinks into the floor (built-in) | fixed in 20.7 for anything with an immovable side; bodies pinned only by other DYNAMIC bodies still overlap by a pixel or two, which is what planck/matter are for |
+| `applyForce` with a point spins a body pushed through its centre, or tips it the wrong way (built-in) | before 20.13 the point was measured against the body's LOCAL bounds, so only a body at the world origin got the right torque; upgrade, and drop any `pos` you subtracted to compensate |
 | forces do nothing after switching adapter | magnitude units differ — re-tune, don't reuse numbers |
 | `body.position` disagrees with `renderable.pos` on matter | matter stores the centroid, melonJS the top-left — the adapter offsets between them |
+| a `bodyDef` two containers down never falls nor collides (`body` stays `undefined`) | before 20.13 only the added container's own children were registered; upgrade |
+| `other.addChild(group)` throws "renderable is already adapter-managed" | before 20.13 a group detached with keepalive (which moving it does) left its children's bodies registered, still simulated off-stage; upgrade |
+| the children of a persistent container stop falling and colliding after a state change or `level.load` | before 20.13 `world.reset()` kept only the bodies whose own renderable was persistent; upgrade, or flag each child `isPersistent` |
 | `bodyDef.shapes: "…"` throws "is not loaded" | the name must match the `name` the JSON was preloaded under, not its filename |
 | everything falls far too fast or too slow after swapping backends | gravity is a different unit per backend; see the table above |
 | debris lands holding its spawn angle and never tumbles | `fixedRotation: true`, or matter-adapter < 1.4.0 / planck-adapter < 1.5.0 |
 | a rotated sprite collides as if upright | the built-in solver rotates visually only — `body.angle` never rotates the shapes. Use planck/matter, or `body.rotate(angle)` |
+| `setAngle` swings a sprite away from where it stood (built-in) | before 20.13 the pivot ignored `anchorPoint`, so a centre-anchored renderable turned about its bottom-right corner; upgrade |
+| `isGrounded()` stays `false` on the floor, so the player cannot jump (built-in) | before 20.13 a body sinking 1px or more per step (gravity or mass above ~1.02, `timer.tick > 1`, a rising floor) never landed; upgrade |
+| a circle body is shoved by a polygon it is nowhere near (built-in) | before 20.13 a counter-clockwise polygon (Tiled, mirrored with `scale(-1, 1)`) had inward edge normals; upgrade |
+| `raycast` throws "reading 'x'" / "reading 'length'" (built-in) | before 20.13 a body carrying a `Point`, `Sphere` or `Box3d` broke the ray walk; upgrade |
+| a ray passes through a rotated ellipse, or stops short of it (built-in) | before 20.13 the raycast ignored `Ellipse#angle`; upgrade |
 | the debug hitbox does not follow a spinning body | pre-1.2.1 matter-adapter / pre-1.3.1 planck-adapter returned the authored shapes rather than the rotated ones |
 | a Tiled polyline becomes a solid box on matter | matter cannot build a zero-area polygon; the adapter falls back to its AABB |
 

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, 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, 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
 ---
 
@@ -88,6 +88,30 @@ 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.
 
+### `@melonjs/gamepad-plugin`
+
+On-screen touch controls, reported as a gamepad: one or two sticks and any
+number of buttons, drawn over the game and read by the engine as a pad in a
+gamepad slot. The game's `bindGamepad` bindings drive it unchanged, so one set
+of bindings covers a real pad and a touch screen.
+
+```js
+import { GamepadPlugin } from "@melonjs/gamepad-plugin";
+plugin.register(GamepadPlugin, "gamepad", {
+    buttons: [{ label: "A" }, { label: "B" }],
+});
+// plugin.cache.gamepad.visible — showing, to word prompts ("tap" or a key)
+```
+
+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. 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.
+
 ### `@melonjs/capacitor-plugin`
 
 Bridges Capacitor's native lifecycle and hardware-back events into the engine:

package/skills/melonjs-renderables/SKILL.md

@@ -174,9 +174,10 @@ Use `addPostEffect()` / `getPostEffect()` / `removePostEffect()`. Assigning
 `renderable.shader = …` is deprecated since 19.2.0.
 
 Post effects need a programmable pipeline. A `ShaderEffect` constructed against
-the Canvas renderer (`renderer.shaderLanguage === null`) logs a warning, stays
-at `enabled === false` and no-ops every method rather than throwing — and
-`beginPostEffect` filters disabled effects out. Since `video.AUTO` picks the
+the Canvas renderer (`renderer.shaderLanguage === null`) stays at
+`enabled === false` and no-ops every method rather than throwing — and
+`beginPostEffect` filters disabled effects out. The first one logs a warning,
+the rest stay quiet, so a decorative effect needs no renderer check. Since `video.AUTO` picks the
 backend at runtime, an effect that works on your machine may do nothing on
 another.
 
@@ -290,6 +291,12 @@ 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.
+
 ## Anchors and floating
 
 - `anchorPoint` defaults to centre `(0.5, 0.5)` on `Renderable`, but `Container`
@@ -321,6 +328,7 @@ 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 |

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

@@ -47,8 +47,8 @@ once and then degrades or no-ops, 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 the WebGL renderer`) and then
-renders sprites unlit. A `Mesh` still draws too, sorted with the painter's
+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
 mode Canvas cannot express — there is no `globalCompositeOperation` that

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

@@ -50,7 +50,10 @@ a transition's reveal follow once the shaders the stage queued are ready, which
 is a few milliseconds once the browser has compiled them before, and at most
 1.5s on a first visit. So build the stage in `onResetEvent`: an object a
 `STATE_CHANGE` listener adds is not waited for, and its first draw may still
-compile what it needs.
+compile what it needs. That first frame steps the world once before drawing it,
+however short it is, so everything `onResetEvent` added is in it (the same goes
+for the frame after a `level.load` made while the game runs). Before 20.12 it
+was drawn unstepped, and showed the stage's background alone for one frame.
 
 `state.change` **throws** `Undefined Stage for state '<id>'` if nothing was
 registered for that id, and `state.set` throws if the second argument is not a
@@ -104,11 +107,15 @@ 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
 state.transition("fade", "#FFFFFF", 250);
 state.transition("mask", "#000", 500, new Ellipse(0, 0, 1, 1));  // shape required
+state.transition("pixelate", "#000", 300);  // blocks up to 32px; a 4th argument sets the size
 state.pause();                               // freeze update, keep drawing
 state.resume();
 app.freeze(150);                             // brief hit-stop (proxies state.freeze)
@@ -116,7 +123,18 @@ 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
-`Polygon`; without one it warns and falls back to a direct switch.
+`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.
+
+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:
+the transition already under way makes it, switching to the last state asked
+for with the last arguments, and a second cover never goes up. A change to a
+state with no transition of its own (`state.setTransition(id, false)`) is made
+at once, and the cover comes down with it. Before 20.12 the second change left
+the first cover on the camera for good, the screen black over a running game.
 
 ### A Stage's own `update()` is NOT paused
 
@@ -299,6 +317,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
@@ -372,6 +398,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
@@ -401,9 +428,12 @@ both.
 | 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

@@ -95,6 +95,15 @@ 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.
 
+`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.
+
 ## Texture atlases
 
 `TextureAtlas` reads several formats:
@@ -125,6 +134,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 +197,8 @@ 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` |
+| `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 |
+| `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. 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, 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, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax, registerTiledObjectClass, registerTiledObjectFactory, TMXObject, resolvedProperty, resolvedProperties, tile class, tile properties."
 license: MIT
 ---
 
@@ -185,6 +185,90 @@ 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.
 
+## Reading and changing tiles at run time
+
+A tile layer is a live grid, not just a picture: read it as the game board,
+and change cells while the game runs — a door opening, a floor panel lighting
+up, a wall blown away. A loaded tile layer is a `TMXLayer` in the world, under
+the name it has in Tiled:
+
+```js
+await level.load("map1", { container: this.app.world, async: true });
+const board = this.app.world.getChildByName("ground")[0];   // a TMXLayer
+board.cols; board.rows;              // the grid, in cells
+board.tilewidth; board.tileheight;   // a cell, in pixels
+```
+
+Two coordinate systems, and the methods do not share one:
+
+| method | takes | returns |
+|---|---|---|
+| `cellAt(col, row)` | column and row | the `Tile` there, or `null` for an empty cell or outside the grid |
+| `getTile(x, y)` | **world pixels** | the same `Tile` object `cellAt` gives, or `null` |
+| `setTile(tile, col, row)` | column and row | puts `tile` there, and returns it |
+| `clearTile(col, row)` | column and row | empties the cell: `cellAt` then returns `null` |
+| `getTileById(gid, col, row)` | a global tile id, column and row | a new `Tile`, to pass to `setTile` |
+
+Columns and rows are the map's tile coordinates, the ones Tiled shows. On an
+**infinite** map a layer can hold tiles left of or above the map's origin:
+there `board.startx` / `board.starty` are negative, its cells run from
+`startx` to `startx + cols - 1` (and `starty` to `starty + rows - 1`), and
+`cellAt(-3, -2)` is the tile Tiled shows at (-3, -2), drawn where Tiled draws
+it. On a finite map both are 0:
+
+```js
+for (let row = board.starty; row < board.starty + board.rows; row++) {
+    for (let col = board.startx; col < board.startx + board.cols; col++) {
+        const tile = board.cellAt(col, row);   // every cell, infinite maps included
+    }
+}
+```
+
+The viewport bounds still cover only the map's `width` x `height`: set them
+yourself to scroll to tiles painted outside it.
+
+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
+`tileset.firstgid + localId`, and only the global one works with `setTile`.
+The tile's custom properties and class, set in Tiled's tileset editor, come
+from its tileset by global id:
+
+```js
+const tile = board.cellAt(col, row);
+const props = tile && tile.tileset.getTileProperties(tile.tileId);  // { kind: "floor" } or undefined
+const cls = tile && tile.tileset.getTileClass(tile.tileId);
+```
+
+To swap a cell for another tile of the tileset, build the tile and set it. Look
+global ids up by property once, rather than hard-coding them, so a designer
+can rearrange the tileset:
+
+```js
+const tileset = board.tilesets.getTilesetByIndex(0);   // the layer's first tileset
+const gidByKind = new Map();
+for (let gid = tileset.firstgid; gid <= tileset.lastgid; gid++) {
+    const kind = tileset.getTileProperties(gid)?.kind;
+    if (kind !== undefined) gidByKind.set(kind, gid);
+}
+
+// light a floor panel up
+board.setTile(board.getTileById(gidByKind.get("floor-lit"), col, row), col, row);
+// knock a wall down
+board.clearTile(col, row);
+```
+
+The layer redraws the changed cell by itself. What it does **not** change is
+collision: solid ground comes from collision object layers (below), so a tile
+set or cleared changes what is drawn and what `cellAt` returns, not what a body
+runs into. Keep a layer you edit often off `preRender` (see the symptom table).
+
+The map's own custom properties (Map → Map Properties in Tiled) are set on the
+map object, which `level.getCurrentLevel()` returns once it is loaded: a
+`theme` string property is `level.getCurrentLevel().theme`. They are set
+**over** the map's own fields, so a property named like one replaces it: a
+custom `name` property becomes the level's `name`. Give level settings names of
+their own (`title`, not `name`).
+
 ## Camera bounds
 
 `level.load` sets the viewport bounds to the map size for you —
@@ -344,6 +428,7 @@ unanimated layer into the offscreen-bake path instead.
 
 | symptom | cause |
 |---|---|
+| objects a screen added just before `level.load` draw in the order they were added (a background over everything) | before 20.13 the reset inside `level.load` dropped the sort still pending for the persistent children it kept; update, or call `sort()` on their container once the level is loaded |
 | 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 |
@@ -361,7 +446,16 @@ 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 tileset's transparent color (`trans`) still shows (the console says it could not be applied) | the image cannot be read back: one from another origin needs CORS headers on the server and `loader.setOptions({ crossOrigin: "anonymous" })` (without them WebGL and WebGPU cannot draw it at all), and a compressed texture cannot be changed: export it with an alpha channel instead |
+| 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` |
+| 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 |
+| 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 |
+| the level's `name` is not its id after loading | a map custom property named `name` replaced it: map properties are set over the map's own fields |
 | changing tiles at runtime is slow on a pre-rendered layer | outside an orthogonal map whose tiles fit their cells, a changed tile re-bakes the whole layer before it next draws: keep layers you edit often off `preRender` |
 | thin lines between tiles on the Canvas renderer, with smoothing on | filtering blends in the next tile of the tileset or its spacing, which a canvas cannot prevent: set `antiAlias: false`, or `preRender` the layer. WebGL and WebGPU keep each tile to itself |
 | tilemap slow on some machines | layer fell back off the shader path — check the console warning for the reason |