melonjs 20.12.0 → 20.13.0

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

@@ -13,8 +13,6 @@ Every asset is `{ name, type, src }` plus type-specific extras:
 ```js
 import { loader } from "melonjs";
 
-loader.setOptions({ crossOrigin: "anonymous" });   // needed for remote assets
-
 await loader.preload([
     { name: "tiles",   type: "image",    src: "data/img/tiles.png" },
     { name: "map1",    type: "tmx",      src: "data/map/map1.tmx" },
@@ -349,6 +347,20 @@ event.on(event.LOADER_COMPLETE, () => { /* … */ });
 event.on(event.LOADER_ERROR, (res) => { /* … */ });
 ```
 
+**Each `preload()` has only its own callback.** One given none calls nothing
+on completion, so a later `await loader.preload(levelAssets)` does not re-run
+the boot callback. Before 20.13 the loader kept the last callback it was given
+and called it again for a preload that had none — usually a `state.change`
+straight back to the first screen. `loader.reload(src)` after a failure
+completes the preload that asset failed in, with that preload's callback, once
+all of its assets are in.
+
+**Progress is per preload:** `LOADER_PROGRESS` goes from that call's first
+asset to `1` with its last, every time. A preload started while another is
+still loading joins it, and the value covers both until everything in flight
+has settled; the next preload starts from zero again. A failed asset keeps
+its preload short of `1`, and only that preload.
+
 ## Unloading
 
 ```js
@@ -377,20 +389,45 @@ state.change(state.PLAY, true);
 
 ## Cross-origin and authenticated assets
 
-Two settings, both global and both applying to **every** asset type — there is
-no per-asset or per-type spelling to remember:
+**Nothing to set for the usual cases.** Every fetched asset (image, json,
+binary, tmx, tsx, shader, gltf/glb, obj, mtl, aseprite, buffered audio) is
+requested the same way:
+
+- **On the game's own origin**, it carries the browser's cookies and HTTP
+  auth, as the page and its scripts do. A game behind a login or a session
+  cookie loads its own assets with no option.
+- **On another origin** (a CDN), it is a CORS request: it loads when that
+  server sends `Access-Control-Allow-Origin`, and fails at load when not, with
+  an error naming the asset and the header it needs. No `crossOrigin` needed.
+
+| asset on… | default | `withCredentials: true` |
+|---|---|---|
+| the game's own origin | loads, with its cookies | loads, with its cookies |
+| another origin sending `Access-Control-Allow-Origin` | loads, no cookies | **blocked** if it answers `*`; needs the page's exact origin plus `Access-Control-Allow-Credentials: true` |
+| another origin allowing credentials for the page | loads, no cookies | loads, with that origin's cookies |
+| another origin with no CORS headers | fails at load, naming the asset | fails at load, naming the asset |
+
+Two global settings cover the rest, for every asset type — there is no
+per-asset or per-type spelling to remember:
 
 ```js
 loader.setOptions({
-    crossOrigin: "anonymous",   // CORS mode for remote assets
-    withCredentials: true,      // send cookies / auth with the request
+    withCredentials: true,      // send cookies / auth to OTHER origins too
+    crossOrigin: "anonymous",   // attribute of the <video>, <script> and glTF
+                                // image elements the loader creates
 });
 ```
 
-`withCredentials` is what an asset behind a session cookie or an
-`Authorization`-style login needs. Every fetched asset — image, json, binary,
-tmx, tsx, shader, gltf/glb, obj, mtl, aseprite, video — carries it, and so does
-buffered audio.
+`withCredentials` is for assets on **another** origin behind a session cookie
+or a login; that server must then allow credentials for the page's origin, or
+the browser blocks the request. `crossOrigin: "use-credentials"` does the same
+for fetched assets, and sets the attribute on the elements.
+
+Before 20.13 both were needed far more often: assets on the game's own origin
+went out with no cookies unless `withCredentials` was set (a 401 or 403 behind
+a login), and an asset on another origin without `crossOrigin: "anonymous"`
+was read as an empty response, failing later with "Unexpected end of input" or
+"The source image could not be decoded" even when its server allowed it.
 
 **Set them through `setOptions`.** `loader.crossOrigin` and
 `loader.withCredentials` are read-only module bindings; assigning to them
@@ -408,13 +445,17 @@ throws, the same trap as the removed `loader.onload` / `onProgress`.
 | audio 404s | `src` given as a file instead of a directory |
 | audio fails, `preload()` rejects with "Failed loading resource" | `audio.init()` not called before preloading — the real message is replaced by the loader's |
 | blank level, missing tiles | `.tsx` or tileset image not listed in the resources |
-| cross-origin textures fail | missing `loader.setOptions({ crossOrigin: "anonymous" })` |
-| assets behind a login 401 / audio preload hangs | missing `loader.setOptions({ withCredentials: true })` — one switch, all asset types |
+| `Failed to load "…" (Failed to fetch). An asset on another origin loads only if its server allows it…` | that origin sends no `Access-Control-Allow-Origin` header — or, with `withCredentials`, sends `*` or no `Access-Control-Allow-Credentials: true`. Fix the server's headers, or serve the asset from the game's own origin |
+| an asset on another origin behind a login 401s / audio preload hangs | missing `loader.setOptions({ withCredentials: true })` — one switch, all asset types. Assets on the game's own origin need nothing (before 20.13 they needed it too) |
+| a remote JSON fails with "Unexpected end of input", or an image with "The source image could not be decoded" | melonJS before 20.13, which read assets on another origin without CORS unless `crossOrigin: "anonymous"` was set |
 | `TypeError` assigning `loader.withCredentials` / `crossOrigin` | read-only module bindings; use `loader.setOptions({ … })` |
 | preload never finishes, blank screen, no error | a failing sound with `audio.setStopOnAudioError(false)` before 20.4 — it disabled audio *and* failed the preload |
 | text renders in a fallback font | web font not preloaded as `"fontface"` |
 | `BitmapText` renders nothing | the `.fnt` (as `"binary"`) or its image is missing |
 | `TypeError` assigning `loader.onProgress` / `onload` | removed in 20.3; they were never writable — use the `LOADER_*` events |
+| `await loader.preload(level)` sends the game back to its title screen, or runs the boot setup twice (before 20.13) | a preload with no callback re-ran the previous preload's callback; update, each preload now calls only its own |
+| the loading bar starts part-full on a second preload, or never reaches the end after one asset failed (before 20.13) | the progress counters ran for the whole session; update, progress is per preload |
+| `loader.reload(src)` of a custom asset type throws `unload : unknown or invalid resource type` (before 20.13) | update: a type registered with `setParser` can now be retried |
 | `load : unknown or invalid resource type` | a custom type in the manifest before its `loader.setParser` call |
 | black or frozen screen when a stage is first entered, the profile shows your own code (noise, a canvas bake) | a costly derived asset built on stage entry — bake it inside the preload as a [custom asset type](#custom-asset-types) |
 | a custom asset preloads but the result is nowhere to be found | `onload` takes no value and the loader stores nothing for custom types — keep the result in your own module |

package/skills/melonjs-math/SKILL.md

@@ -187,13 +187,22 @@ which is how a renderable knows its bounds went stale.
 
 ```js
 v.setCallback(() => { ... });
-v.setMuted(true);     // write without firing it
+v.setMuted(x, y, z);  // write without firing it
+v.setCallback(undefined); // stop observing
 ```
 
 **`setMuted` is what you want when writing several components**, so a
 half-updated vector does not fire a callback that reads the other half.
 `set()` already does this internally: it disables the callback, writes all
-three, fires once, and re-enables.
+three, fires once, and re-enables. Every mutating method (`add`, `scale`,
+`negateSelf`, `floorSelf`, `clampSelf`, `normalize`, `lerp`, …) goes through
+`set()`, so it fires once and returns the observable vector itself. Before
+20.13 `negateSelf`, `floorSelf`, `ceilSelf` and `clampSelf` (and the 3D
+`normalize` and `perp`) fired once per component and returned the wrapped
+plain vector instead.
+
+`clone()` takes from a pool, and gets the callback you pass it or none: before
+20.13 a recycled clone kept the callback of the vector released before it.
 
 Note the observable `set(x = 0, y = 0, z = 0)` defaults EVERY argument, so
 `set(10, 20)` zeroes z exactly as the plain vector does.
@@ -286,7 +295,7 @@ math.degToRad(deg);  math.radToDeg(rad);
 math.random(lo, hi);             // integer
 math.randomFloat(lo, hi);
 math.weightedRandom(lo, hi);     // integer, biased toward LO
-math.round(n, decimals);
+math.round(n, decimals);        // nearest; a tie goes up, as Math.round: -2.5 → -2
 math.pow(n);                     // n squared
 math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
 ```
@@ -317,6 +326,8 @@ and `Math.random()` every frame jitters instead of drifting.
 | z unchanged after scaling | `scale(s)` leaves z alone; pass `scale(s, s, s)` |
 | z became 0 for no reason | `set(x, y)` defaults z to 0 |
 | the original vector changed | the method mutates; `copy()` into something first |
+| a position callback fires twice and sees a half-updated vector, or `pos.floorSelf()` returns something that is not `pos` | before 20.13 the observable `negateSelf` / `floorSelf` / `ceilSelf` / `clampSelf` wrote component by component; upgrade |
+| `math.round(-2.7)` is -2, or a large value comes back negative | before 20.13 `round` truncated toward zero through 32-bit integers; upgrade |
 | memory climbs in a loop | `clone()` or `negate()`/`floor()`/`ceil()` per frame |
 | two helper results are the same object | a shared scratch vector was returned |
 | `.z` is a type error | `Renderable.pos` is declared `Vector2d` (#1510) |

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-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, 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
 ---
 
@@ -105,7 +105,12 @@ 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. See `melonjs-input` for the bindings,
+the layouts and the overlap rules.
 
 ### `@melonjs/capacitor-plugin`
 

package/skills/melonjs-renderables/SKILL.md

@@ -291,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`
@@ -322,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-scenes-and-state/SKILL.md

@@ -107,6 +107,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
@@ -314,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
@@ -387,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
@@ -416,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` |