melonjs 20.12.0 → 20.14.0

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-loading-assets
-description: "Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload, setParser, custom asset type, generated texture, procedural texture."
+description: "Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, organising a multi-level game's assets as bundles (an assets file exporting common plus one bundle per level, passed to loader.preload), loading and freeing a level's bundle, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, resources.js, assets file, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload, unloadAll, bundle, asset bundle, setBundle, getBundle, isLoaded, several levels, per-level assets, free memory between levels, setParser, custom asset type, generated texture, procedural texture."
 license: MIT
 ---
 
@@ -8,28 +8,13 @@ license: MIT
 
 ## The resource descriptor
 
-Every asset is `{ name, type, src }` plus type-specific extras:
+Every asset is `{ name, type, src }` plus type-specific extras. The name is
+what the asset is read back by; the type picks the parser. Type and name
+together identify an asset, so an atlas's image and its JSON share a name:
 
 ```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" },
-    { name: "tileset", type: "tsx",      src: "data/map/tileset.tsx" },
-    { name: "sfx",     type: "audio",    src: "data/sfx/" },
-    { name: "font",    type: "fontface", src: "data/font/PressStart2P.ttf" },
-    { name: "atlas",   type: "json",     src: "data/img/atlas.json" },
-]);
-```
-
-`preload()` has been awaitable since 19.8. The callback form still works and
-takes a third argument to suppress the built-in loading screen:
-
-```js
-loader.preload(resources, onLoaded, /* switchToLoadState */ false);
+{ name: "texture", type: "image", src: "data/img/texture.png" }
+{ name: "texture", type: "json",  src: "data/img/texture.json" }
 ```
 
 ## The type list
@@ -38,7 +23,7 @@ The type strings are melonJS-specific — this is not a generic loader:
 
 | type | for |
 |---|---|
-| `"image"` | textures, sprite sheets, normal maps |
+| `"image"` | textures, sprite sheets, normal maps; `src` may be an array tried in order, such as compressed formats (`.ktx`, `.ktx2`, `.dds`, `.pvr`, `.pkm`) by priority with a PNG last |
 | `"json"` | data, texture-atlas descriptors, collision shapes from a shape editor |
 | `"tmx"` / `"tsx"` | Tiled maps and external tilesets |
 | `"audio"` | sound — **`src` is a directory**, see below |
@@ -52,6 +37,128 @@ The type strings are melonJS-specific — this is not a generic loader:
 | `"js"` | scripts |
 | any type you register | your own formats, and things you generate rather than download — see [Custom asset types](#custom-asset-types) |
 
+## Organise the assets: `common` plus one bundle per level
+
+For any game with **more than one level or screen**, the assets file exports a
+**record of bundles**: what every level uses under `common`, and each level's
+own assets in a bundle of its own. The boot call takes the record as it is:
+
+```js
+// resources.js
+export const resources = {
+    common: [                          // everything every level uses
+        { name: "player",  type: "image", src: "data/img/player.png" },
+        { name: "tileset", type: "image", src: "data/img/tileset.png" },
+        { name: "tileset", type: "tsx",   src: "data/map/tileset.tsx" },
+        { name: "music",   type: "audio", src: "data/bgm/" },
+        { name: "jump",    type: "audio", src: "data/sfx/" },
+    ],
+    level1: [
+        { name: "level1", type: "tmx",   src: "data/map/level1.tmx" },
+        { name: "hills",  type: "image", src: "data/img/hills.png" },
+    ],
+    level2: [
+        { name: "level2", type: "tmx",   src: "data/map/level2.tmx" },
+        { name: "hills",  type: "image", src: "data/img/hills.png" },   // shared: listed again
+        { name: "lava",   type: "image", src: "data/img/lava.png" },
+    ],
+};
+```
+
+```js
+// game.js
+import { audio, loader, state } from "melonjs";
+import { resources } from "./resources.js";
+
+audio.init("mp3,ogg");                 // before any audio is loaded
+await loader.preload(resources);       // every bundle, behind the loading screen
+state.change(state.PLAY);
+```
+
+`preload(record)` declares each key as a bundle and loads them all, with one
+progress bar; an asset several bundles list is fetched once. Nothing else
+changes: a bundle is a lifetime, not a namespace, so assets keep their own
+names, and `getImage("hills")`, `new Sprite(x, y, { image: "player" })` and
+`level.load("level1")` work as with a flat list. What bundles add is that a
+level can later be freed and loaded again **by its id** (next section). Starting
+with bundles costs nothing even if the game never unloads anything.
+
+- **Name a level's bundle after its map.** Bundle ids and asset names are
+  separate, so `"level1"` can be both, and `level.load(id)` and
+  `loader.load(id)` then take the same string.
+- **List a shared asset in every bundle that uses it.** It is still fetched
+  once, and it is what keeps the asset alive when one of those bundles is
+  unloaded.
+- **A map's dependencies go with it**: its `.tsx` and tileset images in the
+  same bundle, or in `common`.
+- **Effects that outlive a level go in `common`** (a HUD's or a camera's
+  shader): unloading the level's bundle would destroy them under whatever
+  still draws with them.
+
+**A flat array is the simplest form**, and is fine for a single-screen game, a
+prototype or a jam game. It works as it always has, and everything in it stays
+in memory for the whole game:
+
+```js
+await loader.preload([
+    { name: "tiles", type: "image", src: "data/img/tiles.png" },
+    { name: "map1",  type: "tmx",   src: "data/map/map1.tmx" },
+    { name: "sfx",   type: "audio", src: "data/sfx/" },
+]);
+```
+
+Moving to bundles later is a change to the assets file alone: wrap the list in
+`{ common: [ … ] }` and split the levels out.
+
+Either way, `preload()` can be awaited (since 19.8) or given a callback, and a
+third argument suppresses the built-in loading screen:
+
+```js
+loader.preload(resources, onLoaded, /* switchToLoadState */ false);
+```
+
+## Level by level: load before, unload after
+
+With every bundle preloaded at boot, nothing more is needed to play. To keep
+memory bounded in a game whose levels are many or large:
+
+```js
+import { level, loader } from "melonjs";
+
+// leaving level1 for good: load the next, switch, then free the previous
+await loader.load("level2");                  // fetches nothing if still in memory
+await level.load("level2", { async: true });
+loader.unload("level1");                      // "hills" stays: level2 lists it too
+
+// going back to a level that was unloaded
+await loader.load("level1");                  // fetches what unloading freed
+await level.load("level1", { async: true });
+```
+
+- **`await loader.load(id)` before entering a level that may not be in
+  memory.** When the bundle is still loaded it resolves at once with no
+  request, so it is cheap to call every time. It does not show the loading
+  screen (the game keeps running); use `loader.preload([id])` for that, or
+  `loader.isLoaded(id)` to decide.
+- **`loader.unload(id)` for a level the player will not come back to soon,
+  after the next level is in.** It frees what no other loaded bundle lists.
+  Unloading the level being played leaves its world as it is, but with no
+  current level, so `level.reload()` has nothing to reload.
+
+**When not to unload:**
+
+- **Levels that loop back** — a hub, a retry after game over, a last level
+  whose exit leads to the first. Unloading one means fetching it again, and a
+  hitch, every time the player returns.
+- **A small game.** If every level fits comfortably in memory, keep
+  everything loaded. The platformer example does exactly this: `resources.ts`
+  exports `{ common, map1, map2 }`, `preload(resources)` loads it all at boot,
+  and since map2's exit leads back to map1, nothing is ever unloaded.
+
+Unload when the levels are large (big tilesets and backgrounds, per-level
+music, 3D scenes), numerous, or linear (a level behind the player for good),
+and on memory-constrained targets such as phones and mini-game platforms.
+
 ## What belongs in the manifest — and what cannot
 
 Preloading is not only for things with a URL. Three tiers, and the middle one
@@ -119,8 +226,8 @@ const app = new Application(1280, 720, {
 
 **You do not call this yourself.** `preload()` calls `renderer.prewarm()` once
 the assets are in and **before** `LOADER_COMPLETE` fires, so it happens while
-the progress bar is still up. Every `preload()` warms, not just the first, so a
-per-level preload warms whatever that level brought with it.
+the progress bar is still up. Every `preload()` warms, not just the first, and
+so does `load(id)`, so loading a level's bundle warms whatever it brought.
 
 The one precondition for this part: **a game that never calls
 `loader.preload()` does not get it**. If you load assets another way, call
@@ -349,15 +456,85 @@ event.on(event.LOADER_COMPLETE, () => { /* … */ });
 event.on(event.LOADER_ERROR, (res) => { /* … */ });
 ```
 
-## Unloading
+**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.
+
+## Bundle and unloading reference
+
+Bundles can also be declared one by one, which is what `preload(record)` does
+for each key:
 
 ```js
-loader.unload({ name: "map1", type: "tmx" });
-loader.unloadAll();
+loader.setBundle("level3", [
+    { name: "level3", type: "tmx",   src: "data/map/level3.tmx" },
+    { name: "hills",  type: "image", src: "data/img/hills.png" },
+]);
+await loader.preload(["common", "level3"]);   // ids and descriptors mix freely
 ```
 
-`unloadAll()` also releases audio and GPU resources such as shader programs, so
-it is the right teardown for switching between large levels.
+- **Strings are bundles, objects are assets.** `loader.unload("map1")`
+  releases the bundle `"map1"`; `loader.unload({ name: "map1", type: "tmx" })`
+  frees that one asset at once, whoever holds it (the bundles listing it then
+  report `isLoaded(id) === false`, and loading one again fetches it again).
+- **`load(id)`** goes through the same path as `preload()`: `LOADER_PROGRESS`
+  for the bundle's own assets, the shader warm-up, then `LOADER_COMPLETE`. It
+  does not switch to the loading screen, and always returns a promise
+  (`onload` / `onerror` callbacks are optional extras).
+- **`load(id, assets)` declares and loads in one call** — `setBundle(id, assets)`
+  then `load(id)`. Called again with the same assets (type, name, src) it just
+  loads; with different ones it redefines the bundle, which throws while that
+  bundle is loaded. Handy where a level's assets are declared next to the code
+  that enters it.
+- **`preload(record)` again** fetches nothing already in memory. A bundle
+  already declared with the same assets is left as it is. A single descriptor
+  passed by mistake throws: wrap it in an array.
+- **Progress:** each asset of the bundle is one step; one already in memory
+  counts as a step done at once. An asset listed twice is one asset, and an
+  empty bundle is allowed (it is always loaded).
+- **Nothing is fetched twice.** An asset already in memory is not requested
+  again, however it got there, and two bundles loading the same asset at once
+  share one request.
+- **Ownership.** Each loaded bundle listing an asset holds it; `unload(id)`
+  frees the assets no other loaded bundle lists. An asset loaded the old way —
+  a flat `preload` list, or `load(asset)` — is **pinned**: no bundle unload
+  frees it, only `unload(asset)` or `unloadAll()`.
+- **`isLoaded(id)`** is true when every asset of the bundle is in memory,
+  however it got there. `getBundle(id)` returns a copy of the list, or
+  `undefined` for an id never declared.
+- **Freeing a map unregisters its level.** After `unload(id)`, `level.load` of
+  a map (or glTF scene) that bundle freed throws "level … not found" until the
+  bundle is loaded again, which registers it again.
+- **Freeing releases the GPU side too:** an image's texture (since 20.14), a
+  shader's program, a font's place in `document.fonts`. `getShader()` hands out
+  the loader's shared instance and does not track who took it, hence
+  "effects that outlive a level go in `common`".
+- **A failing asset rejects `load(id)`**, like `preload`; the assets that did
+  load stay, held by the bundle, and `loader.reload(src)` completes it.
+- **Errors are synchronous.** An unknown id throws in `load`, `unload`,
+  `preload` and `isLoaded`. Redefining a bundle with `setBundle` throws while
+  it is loading or loaded: unload it first. A bundle lists descriptors only,
+  not other bundle ids.
+- **`unloadAll()`** frees every asset, audio included, whoever holds it. The
+  bundles stay declared, all back to not loaded, ready to be loaded again.
+  Levels stay registered (unlike a bundle unload), so load a level's bundle
+  again before `level.load` of it.
+- **`load(asset)`, with a descriptor**, loads one asset while the game runs:
+  no loading screen, progress or loader event, only its promise (or the
+  `onload` / `onerror` callbacks). It is pinned. One already in memory
+  resolves at once with no request (the callback form returns `0` and never
+  calls `onload`), except a `"binary"`, `"fontface"`, `"aseprite"` or `"js"`
+  asset, which is fetched again.
 
 ## Loading between scenes
 
@@ -377,20 +554,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,16 +610,30 @@ 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 |
+| `level X not found` after switching levels with bundles | that map's bundle was unloaded (it unregisters the level), or never loaded: `await loader.load(id)` before `level.load` |
+| `loader: unknown bundle "…"` | a typo, or `setBundle` not called yet; ids and asset names are separate, a bundle is not found by an asset's name |
+| `setBundle(…): the bundle is loaded` | redefining a loaded bundle, by `setBundle` or by `load(id, assets)` with a different list: `loader.unload(id)` first |
+| a shared image disappears (blank layer) after unloading the previous level's bundle | the next level's bundle does not list it: list a shared asset in every bundle that uses it |
+| an asset survives `unload(id)` and memory stays up | it was also loaded the old way (a flat `preload` list, or `load(asset)`), which pins it; load it only through bundles, or `unload(asset)` |
+| a HUD or camera effect goes blank, or throws, after a level's bundle is unloaded | its shader came from that bundle; effects that outlive a level belong in a bundle that outlives it (`"common"`) |
+| `level.reload()` throws `level undefined not found` | the current level's own bundle was unloaded; unload the previous level's bundle after the next level is in |
+| a pause and new network requests every time the player goes back to an earlier level | that level's bundle is unloaded on leaving it although the game loops back to it; keep it loaded (see [When not to unload](#level-by-level-load-before-unload-after)) |
+| memory grows level after level although assets are unloaded (before 20.14) | unloading an image left its GPU texture in the renderer; update |
+| an asset given as a `data:` URI fails, or the default loading screen shows no logo, in a sandboxed embed or under a strict Content-Security-Policy (before 20.11) | the `data:` URI was fetched, which a `connect-src` without `data:` refuses; update, it is decoded in place |
 
 ## Related skills
 

package/skills/melonjs-math/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-math
-description: "Use this skill for vector and matrix maths in melonJS — Vector2d, Vector3d, their observable variants, Matrix2d, Matrix3d, and the math utility functions. Covers which methods mutate and which allocate, the vector pool and when clone() is the wrong tool, interpolation with lerp, slerp, damp and moveTowards, and the argument defaults that silently drop a component. Triggers on: Vector2d, Vector3d, ObservableVector2d, ObservableVector3d, Matrix2d, Matrix3d, vector, vector maths, dot, cross, normalize, length, distance, angle, lerp, slerp, damp, moveTowards, project, clamp, degToRad, radToDeg, clone, vector pool, vector3dPool, setMuted, setCallback, my vector is wrong, z is zero, scale ignores z., moveTowards ignores z, projectN, currentTransform, setTransform, matrix, transform matrix, column-major, val, Float32Array, basis matrix, orientation matrix, Noise, getNoise1d, flicker, wobble."
+description: "Use this skill for vector and matrix maths in melonJS — Vector2d, Vector3d, their observable variants, Matrix2d, Matrix3d, and the math utility functions. Covers which methods mutate and which allocate, the vector pool and when clone() is the wrong tool, interpolation with lerp, slerp, damp and moveTowards, and the argument defaults that silently drop a component. Triggers on: Vector2d, Vector3d, ObservableVector2d, ObservableVector3d, Matrix2d, Matrix3d, vector, vector maths, dot, cross, normalize, length, distance, angle, lerp, slerp, damp, moveTowards, project, clamp, degToRad, radToDeg, clone, vector pool, vector3dPool, setMuted, setCallback, my vector is wrong, z is zero, scale ignores z, moveTowards ignores z, setPosition, projectN, currentTransform, setTransform, matrix, transform matrix, column-major, val, Float32Array, basis matrix, orientation matrix, Noise, getNoise1d, flicker, wobble."
 license: MIT
 ---
 
@@ -97,6 +97,9 @@ v.scale(2, 2, 2);    // (1,2,3) -> (2,4,6)   what you meant
 v.set(10, 20);       // z is now 0, whatever it was
 ```
 
+To move a renderable, `setPosition(x, y)` (20.8) is the call that keeps its
+depth: leave out `z` and it stays as it was, where `pos.set(x, y)` zeroes it.
+
 **`Vector3d.pos` on a renderable is typed `Vector2d`.** `Renderable.pos` is an
 `ObservableVector3d` at run time but is declared through `Polygon` as a
 `Vector2d`, so `.z`, `.setMuted` and `.setCallback` need a cast from
@@ -117,7 +120,7 @@ The 2D one is the z component of the 3D cross, which is the useful scalar for
 ```js
 a.lerp(b, t);            // straight line, t in 0..1
 a.slerp(b, t);           // along the ARC, constant angular rate
-a.damp(b, lambda, dt);   // frame-rate independent ease toward b
+a.damp(b, lambda, dt);   // frame-rate independent ease toward b (dt in seconds)
 a.moveTowards(b, step);  // fixed distance per call, never overshoots
 ```
 
@@ -187,13 +190,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.
@@ -283,11 +295,13 @@ math.clamp(v, lo, hi);
 math.lerp(a, b, t);              // scalars
 math.damp(a, b, lambda, dt);     // frame-rate independent
 math.degToRad(deg);  math.radToDeg(rad);
-math.random(lo, hi);             // integer
+math.random(lo, hi);             // integer, hi EXCLUDED: random(1, 6) never gives 6
 math.randomFloat(lo, hi);
-math.weightedRandom(lo, hi);     // integer, biased toward LO
-math.round(n, decimals);
+math.weightedRandom(lo, hi);     // integer, biased toward LO, hi excluded
+math.round(n, decimals);        // nearest; a tie goes up, as Math.round: -2.5 → -2
 math.pow(n);                     // n squared
+math.lerpArray([1, 0.5, 0], t);  // a value along evenly spaced samples, t in 0..1
+math.isPowerOfTwo(n);  math.nextPowerOfTwo(n);
 math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
 ```
 
@@ -315,9 +329,13 @@ and `Math.random()` every frame jitters instead of drifting.
 | symptom | cause |
 |---|---|
 | 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 |
+| z became 0 for no reason | `set(x, y)` defaults z to 0; move a renderable with `setPosition(x, y)` |
 | 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 |
+| `math.isPowerOfTwo(0)` is true, or a fraction passes | before 20.13 it accepted zero, negative and fractional values; upgrade |
 | memory climbs in a loop | `clone()` or `negate()`/`floor()`/`ceil()` per frame |
+| memory taken by dropped `clone()`s never comes back | before 20.9 the pool kept every instance it handed out; upgrade, and release what you clone |
 | two helper results are the same object | a shared scratch vector was returned |
 | `.z` is a type error | `Renderable.pos` is declared `Vector2d` (#1510) |
 | rotation eases oddly between directions | `lerp` on directions; use `slerp` |

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, stopStream, autoDestroyOnComplete, onComplete, sprite sheet particles, framewidth, randomFrame, cone, sphere, 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,51 @@ 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` (deprecated since 20.2, and does nothing), 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 +152,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
@@ -196,7 +259,9 @@ debris.
 
 For one-shot effects, `autoDestroyOnComplete: true` removes the emitter once its
 particles have finished. The `onComplete` callback fires at that same moment
-either way.
+either way. A stream finishes only once it stops emitting: one left on the
+default `duration` (`Infinity`) never completes until you call `stopStream()`,
+so give a stream that should clean up after itself a `duration`.
 
 For repeated effects (muzzle flashes, impacts) keep **one** long-lived emitter
 and re-aim it per shot, rather than allocating an emitter per event.
@@ -321,6 +386,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 |
@@ -329,13 +395,15 @@ answer when you want discrete puffs rather than a continuous ribbon.
 | the cloud follows a moving emitter | default `referenceSpace: "local"` — use `"world"` for trails |
 | particles do not travel far enough | settings tuned pre-20.2, when drawn travel was doubled |
 | one-shot emitters accumulate | missing `autoDestroyOnComplete: true` |
+| a streaming emitter with `autoDestroyOnComplete` never goes away | the stream runs on the default `duration` of `Infinity`: give it a `duration`, or call `stopStream()` |
 | every particle of an emitter is the same colour all its life | `tint` is one value for the emitter: use `tintOverLife` for a colour that changes as it ages |
 | a `tintOverLife` colour's transparency has no effect | the list sets the colour only; opacity is the particle's fade |
 | `tintOverLife` colours look muddy | the texture is coloured; author it white so the tints come through as given |
 | 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 |