melonjs 20.2.0 → 20.4.0

package/skills/melonjs-input/SKILL.md

@@ -0,0 +1,166 @@
+---
+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, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, click, touch, drag."
+license: MIT
+---
+
+# Input: keyboard, pointer and gamepad
+
+## Keyboard goes through named actions
+
+Do not poll key codes. Bind a key to an **action string**, then poll the action —
+this is what lets gamepad and virtual controls map onto the same handling.
+
+```js
+import { input } from "melonjs";
+
+input.bindKey(input.KEY.LEFT,  "left");
+input.bindKey(input.KEY.RIGHT, "right");
+input.bindKey(input.KEY.X,     "jump", true);   // true = locked: one press per keydown
+
+// in update()
+if (input.isKeyPressed("left"))  { /* … */ }
+if (input.isKeyPressed("jump"))  { /* fires once per press, not per frame */ }
+```
+
+The third argument to `bindKey` is `lock` (default `false`). Without it,
+`isKeyPressed` stays true for as long as the key is held — correct for movement,
+wrong for jump or fire. A locked action stays consumed until the key is released
+or you call `input.unlockKey("jump")`. Use `input.keyStatus(action)` when you
+want the raw held/not-held state regardless of locking.
+
+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.
+
+## Pointer events need `isKinematic = false`
+
+**This is the trap.** `Renderable.isKinematic` defaults to `true`, and both the
+broadphase and the pointer dispatcher skip any candidate whose `isKinematic` is
+still `true`. The handler registers successfully and simply never fires.
+
+```js
+class Button extends Renderable {
+    constructor(x, y, w, h) {
+        super(x, y, w, h);
+        this.isKinematic = false;               // ← required
+    }
+    onActivateEvent() {
+        input.registerPointerEvent("pointerdown", this, this.onDown.bind(this));
+    }
+    onDeactivateEvent() {
+        input.releasePointerEvent("pointerdown", this);
+    }
+}
+```
+
+`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.
+
+Register in `onActivateEvent` and release in `onDeactivateEvent`, not in the
+constructor — pooled objects are reused and would otherwise accumulate handlers.
+
+`app.viewport` works as a whole-screen region when you want global clicks: the
+dispatcher appends it to the candidate list on every event, so it is reachable
+even when nothing else is under the pointer.
+
+The accepted event names are exactly `"pointerdown"`, `"pointerup"`,
+`"pointermove"`, `"pointercancel"`, `"pointerenter"`, `"pointerover"`,
+`"pointerleave"` and `"wheel"`. Anything else — `"click"`, `"mousedown"`,
+`"touchstart"` — makes both `registerPointerEvent` and `releasePointerEvent`
+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.
+
+## World coordinates versus screen coordinates
+
+The pointer carries several, and picking the wrong one produces a feedback loop:
+
+| property | meaning | use for |
+|---|---|---|
+| `pointer.gameScreenX` / `gameScreenY` | canvas-relative position | anything that **moves the camera** |
+| `pointer.gameWorldX` / `gameWorldY` | projected into world space | picking and spawning objects |
+| `pointer.gameLocalX` / `gameLocalY` | relative to the region's ancestor container | hit-testing inside a container |
+| `pointer.gameX` / `gameY` | **context-dependent** — see below | region handlers on non-floating regions |
+
+`gameX`/`gameY` is not a fixed coordinate space. The dispatcher rewrites it per
+candidate just before calling your handler: world coordinates for a normal
+region, screen coordinates for a `isFloating === true` region. On the global
+`event.POINTERMOVE` broadcast it is set to the **screen** coordinates. When you
+need one specific space, read `gameWorldX`/`gameWorldY` or
+`gameScreenX`/`gameScreenY` by name rather than relying on `gameX`.
+
+Using world coordinates for a camera-orbit drag means the same pixel maps to a
+different world point every frame as the camera moves — the drag jumps wildly.
+
+## Pointer move and release outside a region
+
+Region handlers only fire while the pointer is over the region. For drag
+tracking, listen globally:
+
+```js
+import { event } from "melonjs";
+event.on(event.POINTERMOVE, (pointer) => { /* … */ });
+```
+
+There is **no global pointer-up system event** — `event.ts` publishes only
+`POINTERMOVE`, `POINTERLOCKCHANGE`, `DRAGSTART` and `DRAGEND`. For "released
+anywhere" you need a raw listener:
+
+```js
+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.
+
+## Gamepad
+
+Gamepad input maps onto the same action strings, so game code does not branch:
+
+```js
+input.bindGamepad(0,
+    { type: "buttons", code: input.GAMEPAD.BUTTONS.FACE_1 },
+    input.KEY.X);        // → the "jump" action bound above
+```
+
+**Order matters:** `bindGamepad` throws `no action defined for keycode N` if the
+keycode has not already been passed to `bindKey`. Axes use the same call with a
+threshold: `{ type: "axes", code: input.GAMEPAD.AXES.LX, threshold: -0.5 }`.
+`unbindGamepad(index, button)`, `setGamepadDeadzone(value)` and
+`setGamepadMapping(id, mapping)` complete the surface.
+
+## Virtual controls
+
+On-screen buttons synthesise key events, again reaching the same actions:
+
+```js
+input.triggerKeyEvent(input.KEY.LEFT, true);    // press
+input.triggerKeyEvent(input.KEY.LEFT, false);   // release
+```
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| pointer handler never fires | `isKinematic` left at its `true` default |
+| 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 |
+| `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 |
+
+## Related skills
+
+- `melonjs-renderables` — `isKinematic` also gates the physics broadphase
+- `melonjs-ui-and-text` — `UISpriteElement` and `UITextButton` handle this for you

package/skills/melonjs-lighting/SKILL.md

@@ -0,0 +1,139 @@
+---
+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 the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
+license: MIT
+---
+
+# 2D dynamic lighting
+
+> `Light2d` is a world renderable that cuts through a stage's ambient darkness.
+> The glow and the cutout work on every backend; only per-pixel normal-map
+> shading needs a GPU one. It is 2D-only.
+
+## The model: ambient darkness plus cutouts
+
+The `Stage` holds an ambient colour — a dark sheet painted over the scene after
+the world is drawn — and each active `Light2d` punches a hole in it at its
+visible area. The lights themselves are drawn additively on top.
+
+```js
+class PlayScreen extends Stage {
+    onResetEvent(app) {
+        this.ambientLight.parseCSS("#1a1a2e");     // the darkness
+
+        app.world.addChild(new Light2d(x, y, radiusX, radiusY, "#ffddaa", 0.9));
+    }
+}
+```
+
+The constructor is `Light2d(x, y, radiusX, radiusY = radiusX, color = "#FFF",
+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.
+
+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
+`light.illuminationOnly = true` to suppress the visible glow while still lighting
+normal-mapped sprites.
+
+`Stage.ambientLight` defaults to fully transparent black, and `drawLighting()`
+returns immediately while its alpha is 0 — so with no ambient colour set there
+is nothing to cut through and the lights just look like soft additive blobs.
+
+## Multiple lights
+
+Add as many as you need — the glow quads and the ambient cutouts accumulate with
+no fixed cap.
+
+The **normal-map** pipeline is capped: lights are packed into a std140 uniform
+block sized for `MAX_LIGHTS = 32`, and anything past the 32nd is silently dropped
+from the per-pixel shading (it still draws its glow and punches its cutout). The
+cap is an allocation, not a budget — the fragment loop still runs once per pixel
+per live light.
+
+Lights are positioned like any renderable, so they can follow an entity by
+updating `pos`, or be added as children of one.
+
+## Per-pixel lighting with normal maps
+
+For sprites that respond to light direction rather than just brightness, supply a
+normal map alongside the diffuse texture:
+
+```js
+await loader.preload([
+    { name: "hero",     type: "image", src: "data/img/hero.png" },
+    { name: "hero_n",   type: "image", src: "data/img/hero_n.png" },
+]);
+
+const hero = new Sprite(x, y, {
+    image: "hero",
+    normalMap: "hero_n",       // ← enables per-pixel lighting on this sprite
+    framewidth: 32, frameheight: 32,
+});
+```
+
+`normalMap` takes a loader key, or any image-like source (`HTMLImageElement`,
+canvas, `ImageBitmap`, a `Texture2d`). Assigning anything else — including an
+`HTMLVideoElement`, which would freeze on frame 0 — throws a `TypeError`.
+
+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
+normal texture sharing the colour texture's UVs, and a `Sprite` built from that
+atlas picks it up in preference to its own `settings.normalMap`.
+
+Unlit areas of a normal-mapped sprite render pure black unless you raise
+`Stage.ambientLightingColor` (default black) — that is the base level added to
+every lit pixel, and it is a different knob from `Stage.ambientLight`.
+
+Without a normal map a sprite is still lit, but flatly: brightness varies with
+distance from the light, not with surface direction.
+
+## What needs a GPU backend, and what does not
+
+Less than you would expect. `Light2d` is renderer-agnostic: it just calls
+`renderer.drawLight(this)`, and every backend implements it — the GPU backends
+through a shared procedural radial-falloff shader, the Canvas renderer by
+rasterising a cached `Gradient` into one shared render target and compositing it
+with `drawImage`. The ambient cutout pass is plain `setMask` + `fillRect`. So the
+lit-spot look works everywhere, Canvas included.
+
+What Canvas cannot do is **per-pixel normal-map lighting**:
+`renderer.setLightUniforms()` is a no-op there, and the first frame that passes a
+non-empty light list logs a one-shot warning. Normal-mapped sprites simply render
+unlit — no error.
+
+```js
+if (app.renderer.shaderLanguage === null) {
+    // Canvas fallback: lights and ambient still work, but `normalMap` is ignored
+}
+```
+
+## Do not combine with `Camera3d`
+
+`Camera3d` extends `Camera2d` and therefore still runs the 2D lighting pass, but
+nothing in that pass is projection-aware: the ambient fill is a screen-space
+`fillRect`, the cutout is a 2D `Ellipse` mask, and light positions are packed as
+2D world coordinates minus the camera translate. Under a perspective projection
+none of that lines up with what the camera actually draws.
+
+For 3D scenes use `Light3d` instead — it is the counterpart for the mesh
+lighting path, with `"directional"`, `"ambient"`, `"point"` and `"spot"` types.
+See the `melonjs-3d` skill.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| lights added but the scene never darkens | no ambient colour set — `ambientLight` alpha is 0, so the pass returns early |
+| sprite lit flatly, ignoring light direction | 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 |
+| `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` |
+
+## Related skills
+
+- `melonjs-3d` — `Light3d` for perspective scenes
+- `melonjs-sprites-and-animation` — sprite settings and atlases

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

@@ -0,0 +1,186 @@
+---
+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."
+license: MIT
+---
+
+# Loading assets
+
+## The resource descriptor
+
+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" },
+    { 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);
+```
+
+## The type list
+
+The type strings are melonJS-specific — this is not a generic loader:
+
+| type | for |
+|---|---|
+| `"image"` | textures, sprite sheets, normal maps |
+| `"json"` | data, texture-atlas descriptors |
+| `"tmx"` / `"tsx"` | Tiled maps and external tilesets |
+| `"audio"` | sound — **`src` is a directory**, see below |
+| `"video"` | video textures |
+| `"binary"` | raw data, bitmap font `.fnt` descriptors |
+| `"fontface"` | web fonts (`.ttf`, `.woff`) |
+| `"aseprite"` | Aseprite JSON + image |
+| `"shader"` | GLSL/WGSL shader sources |
+| `"obj"` / `"mtl"` | Wavefront models and materials |
+| `"gltf"` / `"glb"` | glTF scenes |
+| `"js"` | scripts |
+
+## Two conventions that produce 404s
+
+**Audio `src` is a directory.** The loader appends the asset name plus each
+format from `audio.init()`, and picks the first that decodes:
+
+```js
+audio.init("mp3,ogg");                                  // before preloading audio
+{ name: "cling", type: "audio", src: "data/sfx/" }      // → data/sfx/cling.mp3
+```
+
+A full filename here gives you a 404. And `audio.init()` must run **before** any
+audio asset is preloaded.
+
+**A Tiled map needs its dependencies listed too** — the `.tmx`, any external
+`.tsx`, and the tileset images. Listing only the map produces a blank level.
+
+## Retrieving loaded assets
+
+```js
+loader.getImage("tiles");
+loader.getJSON("atlas");
+loader.getTMX("map1");
+loader.getGLTF("diorama");
+loader.getVideo("intro");
+loader.getFont("font");
+loader.getBinary("font-fnt");
+```
+
+Most engine classes take the asset **name** directly, so you often do not need
+these — `new Sprite(x, y, { image: "tiles" })` resolves it for you.
+
+## Base URLs
+
+Set a prefix per asset type rather than repeating it:
+
+```js
+loader.setBaseURL("image", "data/img/");
+loader.setBaseURL("audio", "data/sfx/");
+loader.setBaseURL("*", "https://cdn.example.com/");   // every 2D type at once
+```
+
+The `"*"` wildcard deliberately **skips `obj`, `mtl`, `gltf` and `glb`**: those
+resolve their own internal references (a `map_Kd` texture, a glTF `.bin`)
+relative to their file, so a global prefix would double-prefix them. Set those
+types individually.
+
+## Progress and completion
+
+Use the events. The old callback properties (`loader.onload`, `onProgress`,
+`onError`) were deprecated in 18.2 and **removed in 20.3** — being `let`
+bindings on an ES module namespace they could never be assigned from outside in
+the first place, so `loader.onProgress = fn` always threw a `TypeError`:
+
+```js
+import { event } from "melonjs";
+
+event.on(event.LOADER_PROGRESS, (progress) => { /* 0..1 */ });
+event.on(event.LOADER_COMPLETE, () => { /* … */ });
+event.on(event.LOADER_ERROR, (res) => { /* … */ });
+```
+
+## Unloading
+
+```js
+loader.unload({ name: "map1", type: "tmx" });
+loader.unloadAll();
+```
+
+`unloadAll()` also releases audio and GPU resources such as shader programs, so
+it is the right teardown for switching between large levels.
+
+## Loading between scenes
+
+The default loading screen appears automatically when `preload` switches state.
+For a custom one, register a `Stage` against `state.LOADING`:
+
+```js
+state.set(state.LOADING, new MyLoadingScreen());
+```
+
+If you preload without a loading stage and then change state immediately, pass
+`forceChange`:
+
+```js
+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:
+
+```js
+loader.setOptions({
+    crossOrigin: "anonymous",   // CORS mode for remote assets
+    withCredentials: true,      // send cookies / auth with the request
+});
+```
+
+`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.
+
+**Set them through `setOptions`.** `loader.crossOrigin` and
+`loader.withCredentials` are read-only module bindings; assigning to them
+throws, the same trap as the removed `loader.onload` / `onProgress`.
+
+| | |
+| --- | --- |
+| one streamed clip (`stream: true` / `html5: true`) ignores `withCredentials` | it plays through an `<audio>` element, which needs a `crossorigin` attribute rather than fetch credentials. Preload it buffered if it is behind auth |
+| credentials silently dropped for audio before 20.4 | the loader forwarded them under a pre-20.3 name the backend never read — a hung preload rather than an error |
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| 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 |
+| `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 |
+
+## Related skills
+
+- `melonjs-getting-started` — where preloading sits in the bootstrap
+- `melonjs-tilemaps` — the full Tiled asset set
+- `melonjs-audio` — formats and the directory convention

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

@@ -0,0 +1,136 @@
+---
+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, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, Trail, explosion, smoke, sparks, exhaust, emitter."
+license: MIT
+---
+
+# Particles and trails
+
+## An emitter does nothing until you tell it to emit
+
+Adding a `ParticleEmitter` to the world is not enough. Nothing appears, and
+nothing warns you.
+
+```js
+const emitter = new ParticleEmitter(x, y, {
+    image: loader.getImage("spark"),
+    totalParticles: 60,
+    speed: 4,
+    minLife: 200, maxLife: 800,
+});
+
+world.addChild(emitter);
+emitter.streamParticles();     // continuous — or:
+emitter.burstParticles();      // one shot
+```
+
+`streamParticles(ms)` takes an optional run time; without one it uses the
+`duration` setting, which defaults to `Infinity` — a stream runs until
+`stopStream()`. `burstParticles(n)` launches `n`, or `totalParticles`.
+
+For one-shot effects, `autoDestroyOnComplete: true` removes the emitter once its
+particles have finished. The `onComplete` callback fires at that same moment
+either way.
+
+For repeated effects (muzzle flashes, impacts) keep **one** long-lived emitter
+and re-aim it per shot, rather than allocating an emitter per event.
+
+## `referenceSpace` — which frame particles live in
+
+Added in 20.2. This decides what a particle's position is measured *from*, and
+it is the difference between an effect that trails behind a moving object and
+one that drags along with it.
+
+| value | particles are measured from | use for |
+|---|---|---|
+| `"local"` (default) | the emitter | flames, auras, anything welded to the object |
+| `"world"` | the container the emitter sits in | **trails, smoke, exhaust, dust** |
+| a `Container` | that container | a moving frame — snow inside a moving carriage |
+
+```js
+// exhaust that stays where it was emitted, so the ship flies away from it
+const exhaust = new ParticleEmitter(x, y, { referenceSpace: "world", /* … */ });
+```
+
+With the default `"local"`, a moving emitter carries its whole cloud along —
+which is right for a torch flame and wrong for a smoke trail. Changing it at
+runtime re-bases live particles, so nothing jumps.
+
+## Particle tuning changed in 20.2
+
+The 20.2 particle transform fix corrected a drift where drawn positions ran past
+simulated ones. Particles now travel roughly **half as far** over their life as
+they did before.
+
+Consequence: **speed values tuned on 19.x or earlier look wrong on 20.2+.** If
+you are copying emitter settings from older code or older tutorials, expect to
+raise `speed` or `maxLife`.
+
+## Trails
+
+`Trail` is a ribbon that follows a target — use it rather than hand-rolling a
+position history. **Its constructor takes one argument, the options object** —
+no `x, y` pair like every other renderable:
+
+```js
+const trail = new Trail({
+    target: sprite,             // a renderable or a plain Vector2d
+    length: 24,                 // max points kept (default 20)
+    width: 20,                  // max ribbon width in px (default 10)
+    lifetime: 500,              // per-point lifetime in ms (default 500)
+    widthCurve: [1, 0],         // 0 = head, 1 = tail
+    gradient: ["#fff", "#f80", "#f000"],
+});
+trail.blendMode = "additive";
+world.addChild(trail, 5);
+```
+
+Omit `target` and feed it yourself with `trail.addPoint(x, y)` — the mode for a
+sword slash, where the ribbon follows a weapon tip rather than an object. Points
+closer together than `minDistance` (default 4 px) are dropped.
+
+**`Trail` is 2D.** `addPoint` takes `(x, y)`, points are stored without a `z`,
+and the ribbon is drawn as connected screen-space quads. Under a `Camera3d` it
+draws a flat ribbon that does not recede with perspective — so it is the wrong
+tool for a trail behind an object moving *into* the scene. For that:
+
+- **`ParticleEmitter` with `referenceSpace: "world"`** — particles stay where
+  they were dropped while the emitter moves on, and the emitter propagates its
+  depth to each particle so `Camera3d` projects them correctly. This is the
+  built-in answer for exhaust, ski tracks and speed trails in 3D.
+- **A procedural `Mesh`** built from the object's recent path, with
+  `mesh.vertexColors` for a per-vertex gradient — more work, but a continuous
+  ribbon rather than discrete puffs.
+
+## Performance
+
+- Particles come from a shared pool, so a steady-state emitter allocates
+  nothing. Each emitter is still a `Container` that updates and draws every
+  frame, so one busy emitter beats many idle ones.
+- `totalParticles` (default 50) is a cap on how many are alive at once in stream
+  mode; `burstParticles()` launches that many in one go, or the count you pass.
+- `framesToSkip` (default 0) skips n updates between simulation steps — the
+  cheapest lever on an emitter with many particles.
+- Blending is per particle, set through the `blendMode` setting or by assigning
+  `emitter.blendMode` (which reaches the particles already alive as well as
+  later ones). Additive is cheap everywhere: fixed-function on both GPU
+  backends, native `lighter` on Canvas. The expensive modes are the advanced CSS
+  ones (`overlay`, `soft-light`, `color-dodge`, `darken`, …), which on WebGL 2
+  and WebGPU cost a destination capture plus a shader composite *per blended
+  draw*.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| trail looks flat under a `Camera3d` | `Trail` is 2D — use a world-space emitter or a ribbon mesh |
+| emitter added but nothing appears | `streamParticles()` / `burstParticles()` never called |
+| 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` |
+| frame rate drops with many effects | an emitter per event instead of one re-aimed emitter |
+
+## Related skills
+
+- `melonjs-renderables` — draw order and blend modes
+- `melonjs-effects-and-shaders` — blend mode cost on each backend