melonjs 20.13.0 → 20.14.0

package/skills/melonjs-getting-started/SKILL.md

@@ -144,6 +144,11 @@ await loader.preload([
 ]);
 ```
 
+A flat list suits a single-screen game. A game with several levels exports a
+record of bundles instead — `{ common: [...], level1: [...], level2: [...] }`,
+passed to the same `loader.preload()` — so each level's assets can later be
+freed and loaded again by id; see `melonjs-loading-assets`.
+
 Two ordering rules that produce confusing failures when missed:
 
 - **`audio.init()` must run before any audio asset is preloaded**, and names the

package/skills/melonjs-input/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-input
-description: "Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, which of several overlapping objects receives an event and how to consume it, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, pointermove, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, virtual gamepad, touch controls, joystick, gamepad-plugin, floating stick, floating button, floating joystick, two thumbs, tap to fire, hideAtRest, mobile controls, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click."
+description: "Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, which of several overlapping objects receives an event and how to consume it, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, bindPointer, mouse button, vibrateGamepad, rumble, activeGamepad, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, pointermove, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, virtual gamepad, touch controls, joystick, gamepad-plugin, floating stick, floating button, floating joystick, two thumbs, tap to fire, hideAtRest, mobile controls, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click."
 license: MIT
 ---
 
@@ -54,12 +54,37 @@ narrows it; it also repeats while the key is held, so guard anything that must
 happen once. Keep polling for movement and for a menu cursor, where one step
 per press and a key held across a state change are the things that matter.
 
+When the window loses the focus or the page is hidden, every key and
+`bindPointer` button still held is released, since its real release goes to
+another window: polling sees it up when the player comes back, and a key still
+held then is pressed again by its next `keydown`. No `KEYUP` is sent for it,
+so code moved by `KEYDOWN` / `KEYUP` rather than by polling should also listen
+to `event.BLUR`. A gamepad's presses are left to the gamepad, which is read
+every frame.
+
 The full signature is `bindKey(keyCode, action, lock?, preventDefault?)`;
 `preventDefault` defaults to `input.preventDefault` (itself `true`). Pass the
 fourth argument per binding, or change the global default with
 `input.setPreventDefault(false)` — **assigning `input.preventDefault = false`
 does not work**, it is a read-only module binding.
 
+### A mouse button as a key
+
+`bindPointer` makes a mouse button press a bound key, so a click fires the same
+action and `isKeyPressed` sees it:
+
+```js
+input.bindKey(input.KEY.X, "fire");
+input.bindPointer(input.KEY.X);                       // the left button
+input.bindPointer(input.pointer.RIGHT, input.KEY.X);  // or another button
+input.unbindPointer(input.pointer.RIGHT);             // LEFT when omitted
+```
+
+As with `bindGamepad`, the key needs its `bindKey` first, or `bindPointer`
+throws `no action defined for keycode N`. Turning the wheel neither presses
+nor releases a bound button's key (before 20.14 it released the left
+button's).
+
 ## Pointer events need `isKinematic = false`
 
 **This is the trap.** `Renderable.isKinematic` defaults to `true`, and both the
@@ -82,9 +107,11 @@ class Button extends Renderable {
 ```
 
 `Container`, `Camera2d`, `Draggable`, `DropTarget` and the `UI*` elements set it
-to `false` for you, and so does attaching a physics body (`Body`'s constructor
-sets `ancestor.isKinematic = false`) — so plain `Renderable` and `Sprite`
-subclasses with no body are the ones that catch people.
+to `false` for you, and so does giving it a physics body (a `bodyDef` on any
+adapter, or a `Body`) — so plain `Renderable` and `Sprite` subclasses with no
+body are the ones that catch people. Before melonJS 20.14, matter-adapter
+1.6.0 and planck-adapter 1.7.0, a `bodyDef` under matter or planck left
+`isKinematic` at `true`, so set it yourself there.
 
 Register in `onActivateEvent` and release in `onDeactivateEvent`, not in the
 constructor — pooled objects are reused and would otherwise accumulate handlers.
@@ -103,6 +130,11 @@ throw `invalid event type`. melonJS maps the canonical name onto whichever
 mouse/touch events the device actually supports, so you always register the
 pointer name.
 
+A region can listen to `"pointerup"` alone, to act on release: it gets the
+release of a press made on it. With several fingers on one region, each finger
+that pressed it gets its own `pointerup` / `pointercancel`; `pointerenter` and
+`pointerleave` still follow one pointer per region.
+
 ## Which object gets the event
 
 The dispatcher collects the regions near the pointer from the broadphase,
@@ -182,9 +214,10 @@ globalThis.addEventListener("pointerup", onRelease);
 
 For plain drag-and-drop, `Draggable` / `DropTarget` already wire all of this up
 (`pointerdown` / `pointerup` / `pointercancel` regions plus a global
-`POINTERMOVE` listener) and emit `event.DRAGSTART` / `event.DRAGEND`. `DRAGEND`
-still originates from a region handler, so it only fires when the release lands
-on the draggable itself.
+`POINTERMOVE` listener) and emit `event.DRAGSTART` / `event.DRAGEND`, and
+follow the pointer under any camera, scrolled or zoomed. `DRAGEND` still
+originates from a region handler, so it only fires when the release lands on
+the draggable itself.
 
 ## Gamepad
 
@@ -252,10 +285,10 @@ input.hasGamepadVibration(index);    // for an options-screen toggle
 
 Safe to call blind: no pad, no motors, or no Gamepad API at all resolves
 `false` and does nothing, so game code never branches on support. Magnitudes
-default to **full** — the underlying web API defaults every parameter to zero,
-which makes a bare `playEffect` a silent no-op. A second call preempts the
-first on the same pad, so a rapid series of hits reads as a rapid series of
-hits rather than as a queue. For a SUSTAINED rumble issue one effect with a
+default to **full** and `duration` to 200 ms — the underlying web API defaults
+every parameter to zero, which makes a bare `playEffect` a silent no-op. A
+second call preempts the first on the same pad, so a rapid series of hits
+reads as a rapid series of hits rather than as a queue. For a SUSTAINED rumble issue one effect with a
 long `duration` instead of calling every frame.
 
 Hot-plugging needs no polling of your own — the engine listens for the browser's
@@ -270,12 +303,15 @@ event.on(event.GAMEPAD_DISCONNECTED, (gamepad) => { /* pause, show a prompt */ }
 
 Bindings survive a disconnect: they are attached to the index, not to the
 device, so a pad unplugged and plugged back into the same slot keeps working.
+A pad unplugged with a button or the stick held lets go of the keys bound to
+them, as releasing them would.
 
 ## Virtual controls
 
-For on-screen touch controls, use `@melonjs/gamepad-plugin` rather than
-writing them: sticks and buttons drawn over the game and reported as a pad in
-a gamepad slot, so the `bindGamepad` bindings above answer to them unchanged.
+For on-screen touch controls, use `@melonjs/gamepad-plugin` (it needs melonJS
+20.12 or later) rather than writing them: sticks and buttons drawn over the
+game and reported as a pad in a gamepad slot, so the `bindGamepad` bindings
+above answer to them unchanged.
 
 ```js
 import { GamepadPlugin } from "@melonjs/gamepad-plugin";
@@ -326,6 +362,12 @@ Every press lasts at least one frame, so a 15 ms thumb tap still reaches
 `isKeyPressed`, and Safari's pinch gesture is cancelled while the controls
 show, so a second thumb works on iOS.
 
+To match the game's artwork (1.2), pass an already-loaded `TextureAtlas` as
+`skin` to `GamepadPlugin`, with `base` / `thumb` region names on sticks
+and `region` / optional `pressed` names on buttons. Omitted parts keep
+their shapes. Regions scale to the controls' sizes without changing hit areas;
+labels, floating controls, opacity, hiding and dimming keep working.
+
 A single key can also be pressed directly, reaching the same actions:
 
 ```js
@@ -338,19 +380,27 @@ input.triggerKeyEvent(input.KEY.LEFT, false);   // release
 | symptom | cause |
 |---|---|
 | pointer handler never fires | `isKinematic` left at its `true` default |
+| touches never arrive where there is no DOM (nx.js, a Web Worker) | melonJS older than 20.14 listened for mouse events there; update. Touch is then read from `TouchEvent`s dispatched on the canvas given as `settings.canvas` |
 | handlers fire twice, or on dead objects | registered in the constructor instead of `onActivateEvent` |
 | camera drag jumps around | using world coordinates instead of `gameScreenX`/`gameScreenY` |
 | `gameX` holds screen coords where world coords were expected | read on `event.POINTERMOVE`, or on a floating region — use `gameWorldX`/`gameWorldY` |
 | drag stops when leaving the object | region events end at the region — use `event.POINTERMOVE` |
 | release never detected outside the region | no global pointer-up event — add a raw listener |
 | jump fires every frame while held | `bindKey` without its third `lock` argument |
+| the hero keeps walking after an Alt-Tab, until the key is pressed again (before 20.14) | the key's release went to another window: update, held keys are now released on blur |
+| a region with only a `"pointerup"` callback never gets it, or the first finger's release is lost with two on one region (before 20.14) | the release was only delivered to the last pointer to press the region: update |
+| a key bound with `bindPointer` never fires once the mouse has entered the canvas (before 20.12) | the pointer's button bindings were replaced on each event: update |
+| firing (a key bound with `bindPointer`) stops while the button is held and the wheel turns (before 20.14) | a wheel event released the main button's key: update |
+| clicks land off target after browser zoom or a move to another screen (before 20.14) | the pointer was scaled by the live pixel ratio against a canvas sized with the old one: update |
+| a `Draggable` jumps away when grabbed, and stays stuck dragging, once the camera has moved (before 20.14) | it mixed screen and world coordinates: update |
 | `invalid event type` thrown at registration | non-pointer name (`"click"`, `"mousedown"`, …) passed to `registerPointerEvent` |
-| `no action defined for keycode N` | `bindGamepad` called before `bindKey` for that keycode |
+| `no action defined for keycode N` | `bindGamepad` or `bindPointer` called before `bindKey` for that keycode |
 | floating stick ignores the right half of the screen | its `area` defaults to `"half"`, its own side — use `area: "screen"` |
 | `area: "screen"` stick still ignores part of the screen | a floating button's area comes first there — the overlap order is fixed buttons, fixed sticks, floating buttons, floating sticks |
 | a quick tap on a stick moves instead of acting | it leaned past `dpadThreshold` or outlasted `tap.time` before lifting |
 | stick has to be pushed well past its `threshold` before it registers | `threshold` is ADDED to the deadzone, not used instead of it |
 | one half of a stick does nothing | each half is a separate `bindGamepad`, chosen by the sign of `threshold` |
+| a key stays pressed after its pad is unplugged, or a stick bound on one side holds its key after coming back to the centre (before 20.12) | update: an unplugged pad lets go of what it held, and a stick lets go when it returns to rest, even just past the centre |
 | a widget under an overlapping panel still lights up | the panel consumes no hover: return `false` from its `onOver` (presses already stop at UI elements; `UIPanel` with `blocking` does both) |
 | a widget stays highlighted after the pointer moves onto a panel over it | the panel consumes no `pointermove`, so nothing takes the pointer off the widget |
 | a child's big `z` does not put it in front of another container | `pos.z` is container-local — use `ancestor.moveToTop()` on the container |

package/skills/melonjs-lighting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-lighting
-description: "Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
+description: "Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, softness, soft light, lightHeight, setRadii, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
 license: MIT
 ---
 
@@ -31,6 +31,11 @@ intensity = 0.7)`, and `pos` is the light's **centre** — its `anchorPoint` is
 `(0.5, 0.5)`, and `centerX` / `centerY` are overridden to return `pos` directly.
 Give `radiusY` a different value for a stretched, elliptical light.
 
+Resize a light with `light.setRadii(radiusX, radiusY)`, which resizes its
+bounds too. Writing `radiusX` alone changes nothing you can see: the glow, the
+hole in the darkness and the normal-map shading are all sized from the bounds,
+on every backend.
+
 A `Light2d` added to the world **registers itself with the stage's ambient
 overlay on activate**, so you add it like any other renderable and it takes part
 in the lighting pass. It draws additively (`blendMode = "lighter"`); set
@@ -105,6 +110,11 @@ const hero = new Sprite(x, y, {
 canvas, `ImageBitmap`, a `Texture2d`). Assigning anything else — including an
 `HTMLVideoElement`, which would freeze on frame 0 — throws a `TypeError`.
 
+How grazing the light is comes from `light.lightHeight`, its height above the
+sprite plane in the same units as its radius (default `max(radiusX, radiusY) *
+0.075`). Lower it for light raking across the surface, which shows the relief
+off; raise it for flatter, more even shading.
+
 Normal maps are typically authored in **SpriteIlluminator**. The sidecar pattern
 above — one `_n` image beside each diffuse image — is the simplest setup, but an
 atlas can carry one too: `new TextureAtlas(json, image, { normalMap })` pairs a
@@ -209,6 +219,8 @@ See the `melonjs-3d` skill.
 | sprite not shaded by a light, only glowed over | no `normalMap` on the sprite, or the Canvas backend is active |
 | normal-mapped sprite is pure black where unlit | `Stage.ambientLightingColor` left at black |
 | the 33rd light shades nothing | `MAX_LIGHTS = 32` for the normal-map pipeline |
+| changing `radiusX` / `radiusY` does nothing | everything is sized from the bounds, which `setRadii()` updates and a bare field write does not |
+| normal-mapped relief looks flat under a light | `lightHeight` is high relative to the radius; lower it for a grazing light |
 | `TypeError` assigning `normalMap` | not an image-like value (a video element is rejected outright) |
 | lighting misaligned under a 3D camera | the 2D light pass is not projection-aware — use `Light3d` |
 

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,26 +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";
-
-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
@@ -36,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 |
@@ -50,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
@@ -117,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
@@ -361,15 +470,71 @@ 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
+## 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
 
@@ -459,6 +624,16 @@ throws, the same trap as the removed `loader.onload` / `onProgress`.
 | `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
 ```
 
@@ -292,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.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
 ```
 
@@ -324,11 +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, 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."
+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
 ---
 
@@ -64,7 +64,8 @@ It covers every setting that changes how one emitter looks, but not:
   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
+  `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
@@ -258,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.
@@ -392,6 +395,7 @@ 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 |