melonjs 20.2.0 → 20.4.0

package/skills/melonjs-3d-assets/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: melonjs-3d-assets
+description: "Use this skill when loading 3D models into melonJS — glTF and GLB scenes, OBJ/MTL models, materials, imported lights, node animation, ground shadows and GPU instancing. Covers level.load options including the async flag, the rightHanded conversion, and exactly what the loader does and does not support. Triggers on: glTF, gltf, glb, OBJ, MTL, 3D model, getGLTF, getOBJ, getMTL, GLTFModel, GLTFScene, level.load glb, rightHanded, lightIntensityScale, castGroundShadow, shadowGroundY, EXT_mesh_gpu_instancing, KHR_lights_punctual, skinning, Blender export, 3D asset."
+license: MIT
+---
+
+# Loading 3D assets
+
+> glTF/GLB is the primary path for 3D content, and it goes through the **level
+> director** rather than the world directly: `level.load("scene")`, the same call
+> a Tiled map uses. OBJ/MTL is the simpler path for a single static model.
+
+## Loading a glTF/GLB scene
+
+```js
+await loader.preload([
+    { name: "diorama", type: "glb", src: "data/scenes/diorama.glb" },
+]);
+
+level.load("diorama", { scale: 50 });
+```
+
+`type: "gltf"` (JSON plus external buffers) and `type: "glb"` (single binary)
+are both loader types. A self-contained GLB is the better shipping format — one
+request, nothing to resolve relatively.
+
+The scene loads under whatever camera the stage has; view it under a `Camera3d`
+or it renders flat. See `melonjs-3d` for the camera.
+
+### `level.load` options for glTF/GLB
+
+| option | default | what it does |
+|---|---|---|
+| `scale` | `1` | pixels per glTF unit, applied to the whole scene. Blender's metre-scale export usually needs 20–100. |
+| `container` | `game.world` | where the nodes are added |
+| `onLoaded` | `app.onLevelLoaded` | called with the **level id**, not the scene |
+| `async` | `false` | return a promise that settles once the scene is in the world, instead of a boolean |
+| `rightHanded` | `true` | see below |
+| `lights` | `true` | instantiate authored `KHR_lights_punctual` lights as `Light3d` world children |
+| `lightIntensityScale` | — | keep authored intensity ratios instead of normalising every light to 1 |
+| `castGroundShadow` | inherits the app setting (**on**) | blob shadows for this scene's meshes |
+| `shadowGroundY` | each object's own base | world Y of the floor the blobs land on |
+
+`onLoaded` receives the level id — it is a "done" signal, not a handle on the
+scene. You need it, or `async`: with the game loop running, `level.load` stops
+the loop and defers the actual load to a timer, so by default it returns
+*before* anything is in the world.
+
+```js
+await level.load("diorama", { scale: 50, async: true });
+// the scene is in the world here
+```
+
+Note `await level.load("diorama")` without the flag does not await the load — the
+call returns a boolean, and `await true` resolves immediately. To get at what was
+loaded, load into a container you own, or look the nodes up by their authored
+names:
+
+```js
+level.load("diorama", { scale: 50, onLoaded: () => {
+    const sun = app.world.getChildByName("Sun")[0];   // note: returns an array
+    sun.intensity = 2;
+}});
+```
+
+## `rightHanded` — and the default that differs between the two APIs
+
+glTF is authored **Y-up, right-handed**; melonJS is **Y-down, +Z forward**.
+There are two ways to bridge that, and they are not equivalent:
+
+- a **rotation** — preserves chirality, matches the authoring tool
+- a **mirror** (negate Y only) — flips the scene left/right
+
+`level.load` defaults `rightHanded: true`, so a scene loaded through the level
+director comes in correctly. **The `Mesh` constructor defaults it to `false`**,
+so glTF or OBJ geometry you feed to a `Mesh` yourself comes in mirrored unless
+you pass `rightHanded: true`. A model that is subtly wrong — text backwards, a
+character's gear on the wrong side — is this and nothing else.
+
+Do not add a flip of your own on top; two corrections cancel back to wrong.
+
+## Materials — what actually arrives
+
+The importer covers a deliberate subset:
+
+- `pbrMetallicRoughness` **base colour texture and factor**
+- metallic/roughness **factors** converted to the engine's specular model
+- `emissiveFactor`, including `KHR_materials_emissive_strength`
+- `KHR_materials_unlit` — honoured, for baked/stylised workflows
+- `alphaMode: "MASK"` — the cutout threshold is applied
+- `doubleSided`
+
+Not imported: **normal maps**, metallic/roughness *textures*, occlusion maps,
+morph targets, `KHR_texture_transform`. Nothing errors — the material simply
+arrives without them, which reads as "flatter than the preview in my authoring
+tool". Bake what you need into the base colour.
+
+**Draco compression is the exception that does error.** Its geometry sits in
+accessors with no buffer view, which the parser rejects outright, so the whole
+asset fails to load. Export uncompressed.
+
+`textureFilter` on the Application settings (`"nearest"` / `"linear"` /
+`"auto"`) drives sampling; glTF materials that declare their own sampler carry
+it through. Pixel-art models want `"nearest"`.
+
+## Lights
+
+Authored `KHR_lights_punctual` lights — sun, point, spot — become `Light3d`
+world children, plus a soft ambient fill, and each keeps its authored name.
+A scene carrying any of them renders through the **lit** path automatically.
+
+glTF stores physical units — lux for suns, candela for lamps — and a Blender
+daylight sun is 1000+, which blows out the engine's stylised shading. So every
+light is normalised to intensity 1 by default. To keep the *ratios* the artist
+set, scale instead of normalising:
+
+```js
+// a 1000-lux sun lands at 1, a 500-lux fill lands at 0.5
+level.load("diorama", { scale: 50, lightIntensityScale: 0.001 });
+```
+
+Pass `lights: false` to manage lighting yourself.
+
+## Animation
+
+Node-TRS animation **is** supported: translation, rotation and scale channels,
+the rigid hierarchical animation used by blocky/low-poly character packs. An
+animated asset instantiates as a single `GLTFModel` keeping the node hierarchy
+intact, with an API deliberately mirroring `Sprite`. The model carries the asset
+name, which is how you get hold of it after loading:
+
+```js
+const model = app.world.getChildByName("hero")[0];   // the GLTFModel
+
+model.getAnimationNames();                           // ["idle", "walk", ...]
+model.setCurrentAnimation("walk", { loop: true, speed: 1, onComplete });
+model.setCurrentAnimation("jump", { next: "idle" }); // chain
+model.isCurrentAnimation("walk");
+model.play();
+model.pause();
+```
+
+`speed` is a playback multiplier (1 = authored speed), not a frame delay. Only
+an explicit `loop: false` stops looping. `setCurrentAnimation` **throws** on a
+clip name the asset does not define — check `getAnimationNames()` first.
+
+**Vertex skinning is out of scope** — `JOINTS_0` / `WEIGHTS_0` are not read, and
+neither are morph targets. A smoothly-deforming character will not deform. The
+options are: rig it hierarchically instead (separate meshes parented into a
+node tree), use `Sprite3d` billboards, or use the Spine plugin for 2D skeletal
+work.
+
+## Instancing
+
+A node using `EXT_mesh_gpu_instancing` loads as an `InstancedMesh` — one draw
+call for every copy, which is the difference between a hundred trees and a
+hundred thousand. Export with instancing enabled where your tool supports it.
+Sparse accessors on the instancing attributes are rejected with a clear error
+rather than silently misplacing every instance.
+
+## Ground shadows
+
+```js
+level.load("diorama", { scale: 50, castGroundShadow: true, shadowGroundY: 0 });
+```
+
+`castGroundShadow` is tri-state: set it and it overrides the application setting
+for this scene in both directions; omit it and the scene inherits — and that
+setting is `true` by default, so shadows are already on. As a scene-wide opt-in
+it skips nodes with no vertical extent — a ground plane is exactly that, and
+shadowing it with itself smears a blob across the whole floor. Blob shadows need
+a GPU backend and a `Camera3d`; nothing is drawn on the 2D-camera or Canvas
+paths.
+
+Omit `shadowGroundY` and each blob sits at its own object's base at full
+strength, which is right for props already resting on the ground. Set it when
+things jump or fly, so the shadow stays on the floor and shrinks with height.
+
+A blob is centred on its caster's x/z and is never offset by light direction, so
+a wide flat-bottomed prop hides its own shadow under itself. Raising
+`shadowGroundY` to force one into view floats the blob up over the object as a
+dark ring rather than sliding it clear — the setting is for things that leave
+the ground, not a visibility knob.
+
+## OBJ/MTL
+
+A different shape entirely: OBJ produces raw geometry you hand to a `Mesh`,
+not a scene. Preload the two files and name them in the `Mesh` settings — the
+`model` and `material` names are independent, the same name for both is just a
+convention:
+
+```js
+await loader.preload([
+    { name: "fox", type: "obj", src: "models/fox.obj" },
+    { name: "fox", type: "mtl", src: "models/fox.mtl" },
+]);
+
+const mesh = new Mesh(400, 300, {
+    model: "fox",
+    material: "fox",        // texture resolved from the material's map_Kd
+    width: 200,
+    height: 200,
+    rightHanded: true,      // the Mesh default is false — see above
+});
+world.addChild(mesh);
+```
+
+**The MTL loader fetches the textures it references itself** — `map_Kd` and
+`map_d` are resolved relative to the `.mtl` and preloaded for you, so there is
+no image entry in the manifest above. Passing `texture:` explicitly overrides
+that and pins *one* binding over the whole model, which on a multi-material
+model suppresses the per-material texture split; leave it out unless you mean
+that.
+
+MTL contributes `Kd` (diffuse tint), `d` / `Tr` (opacity), `Ke` (emissive),
+`Ks` + `Ns` (specular highlight), `map_Kd` (diffuse texture) and `map_d`
+(per-texel opacity). Normal and specular *maps* are not supported.
+`loader.getOBJ(name)` and `loader.getMTL(name)` return the parsed data if you
+want it directly. OBJ has no scene graph, no lights, no animation — use glTF for
+anything beyond a single static model.
+
+## Packaging
+
+A self-contained GLB is one file with nothing to resolve — the safest thing to
+ship. External references still work in both formats: `.bin` buffers and image
+`uri`s are resolved **relative to the asset's own URL** (a GLB with an external
+texture loads as-shipped). But an external file that 404s rejects the parse, so
+the whole asset fails to load rather than arriving partially — no untextured
+fallback. Note that `loader.setBaseURL("*", …)` deliberately skips `gltf`,
+`glb`, `obj` and `mtl` for this reason; set those types individually if you
+need a prefix.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| model mirrored — text backwards, gear on the wrong side | `Mesh` defaults `rightHanded` to `false`; pass `true` |
+| model upside down | a manual axis flip on top of the loader's conversion |
+| scene is enormous or invisibly small | `scale` left at 1 against a metre-scale export |
+| the asset fails to load entirely | an external buffer/image `uri` that 404s, or Draco-compressed geometry |
+| everything is blown out white | authored lux/candela intensities; use `lightIntensityScale` |
+| materials flatter than the authoring-tool preview | no normal or metallic/roughness *textures* are imported |
+| a character does not deform | vertex skinning is out of scope; rig hierarchically or billboard |
+| animation names come back empty | the asset has no node-TRS channels (skin-only rig) |
+| a hundred copies tank the frame rate | exported without `EXT_mesh_gpu_instancing` |
+| a prop casts no visible shadow | wide and flat-bottomed — the blob is under it; `shadowGroundY` haloes it rather than revealing it |
+| a shadow smeared across the whole floor | a ground plane cast its own blob — use the scene-wide opt-in |
+| `onLoaded` gets a string, not the scene | it is called with the level id; load into your own container instead |
+| scene renders flat and unlit | no `Camera3d` — the 2D-camera path is CPU-projected and unlit (with a `Camera3d` on Canvas you get a black canvas instead) |
+
+## Related skills
+
+- `melonjs-3d` — conventions, `Camera3d`, meshes, `Light3d`, instancing, and
+  `camera.setFog` (an outdoor scene almost always wants it; it is set on the
+  camera, so a loaded scene needs no per-node work)
+- `melonjs-lighting` — how `Light3d` behaves once imported
+- `melonjs-loading-assets` — the loader, asset types and base URLs
+- `melonjs-plugins` — the Spine plugin, for skeletal characters

package/skills/melonjs-audio/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: melonjs-audio
+description: "Use this skill for sound and music in melonJS — loading audio, playing effects, background tracks, audio sprites, volume and muting, spatial audio, and procedural tone/noise generation. Covers the mandatory audio.init format list, the directory-not-file src convention, playTrack versus play, and browser autoplay unlocking. Triggers on: audio, sound, audio.init, audio.play, playTrack, stopTrack, audio.load, sfx, music, volume, mute, sprite audio, stereo, panner, audio.tone, audio.noise, getAudioContext, autoplay."
+license: MIT
+---
+
+# Audio
+
+## Two setup rules
+
+```js
+import { audio, loader } from "melonjs";
+
+audio.init("mp3,ogg");                      // 1. BEFORE preloading any audio
+
+await loader.preload([
+    { name: "cling", type: "audio", src: "data/sfx/" },   // 2. a PREFIX, not a file
+]);
+```
+
+1. **`audio.init(format)` must run before any audio asset is preloaded**, and
+   lists the formats you actually ship. Preloading first throws
+   `target audio extension(s) should be set through me.audio.init() before
+   calling the preloader.` It returns `false` when no audio backend is
+   available, so it is worth checking. The format list defaults to `"mp3"`.
+2. **`src` is a prefix, not a file.** The loader appends the asset `name` plus
+   each configured extension and uses the first that loads — so
+   `data/sfx/` + `cling` + `mp3` → `data/sfx/cling.mp3`. Passing a full filename
+   gives you a 404. A `data:audio/...` URL is the one exception: it is used
+   verbatim, prefix and extension skipped.
+
+Order matters — melonJS tries the listed formats left to right, so put the
+preferred one first. Two formats (`"webm,mp3"` or `"mp3,ogg"`) is the usual
+belt-and-braces for codec coverage. Accepted tokens: `mp3`, `mpeg`, `opus`,
+`ogg`, `oga`, `wav`, `aac`, `caf`, `m4a`, `m4b`, `mp4`, `weba`, `webm`, `dolby`,
+`flac`.
+
+## Effects versus music
+
+```js
+audio.play("cling");                    // fire and forget
+audio.play("cling", false, null, 0.5);  // loop, onend, volume
+const id = audio.play("engine", true);  // looping; keep the id to stop it
+
+audio.playTrack("theme");               // background music
+audio.stopTrack();
+```
+
+Use **`playTrack`** for music, not `play`. `playTrack(name, volume?)` always
+loops, and it records the name as the current track — which is what
+`app.pauseOnBlur` / `resumeOnFocus` / `stopOnBlur` act on, via
+`state.pause(true)` → `pauseTrack()`. `stopTrack()`, `pauseTrack()`,
+`resumeTrack()` and `getCurrentTrack()` all read that same single slot, so there
+is only ever one current track. Stop it in `onDestroyEvent`.
+
+Every per-clip function throws `audio clip <name> does not exist` if the clip was
+never loaded, and `play` additionally throws when a named sprite region is
+missing.
+
+## Audio sprites
+
+One file carrying many effects, with named regions in milliseconds:
+
+```js
+await loader.preload([{
+    name: "sfx", type: "audio", src: "data/sfx/",
+    sprite: { jump: [0, 450], hit: [2000, 250], music: [4000, 12000, true] },
+}]);
+
+audio.play("sfx", { sprite: "jump" });
+```
+
+The optional third element marks a region as looping. `play()`'s second argument
+takes either the original `loop` boolean or a `PlayOptions` object
+(`sprite`, `loop`, `onend`, `volume`) — both forms work. Object fields win over
+the positional `onend` / `volume` arguments when both are supplied.
+
+## Clip state
+
+```js
+audio.duration("theme");        // seconds — 0 while still loading
+audio.duration("sfx", id);      // duration of the region THAT instance plays
+audio.playing("theme");         // is anything playing?
+audio.playing("theme", id);     // is that instance playing?
+audio.state("theme");           // "unloaded" | "loading" | "loaded"
+```
+
+`stop()`, `pause()` and `resume()` take an optional instance `id` too; omit it
+and the whole group is affected. `audio.stop()` with no arguments at all stops
+every sound. `audio.seek(name)` reads the position, `audio.seek(name, s, id?)`
+writes it; `audio.rate` and `audio.fade(name, from, to, ms, id?)` round it out.
+
+## Volume and muting
+
+```js
+audio.setVolume(0.5);           // global, 0..1
+audio.getVolume();              // read it back
+audio.mute("cling");            // one clip  — mute(name, id?, shouldMute = true)
+audio.unmute("cling");
+audio.muteAll();                // everything (audio.disable() is an alias)
+audio.unmuteAll();              // (audio.enable() is an alias)
+audio.muted();                  // global mute state
+```
+
+`audio.unload(name)` / `audio.unloadAll()` free the decoded buffers; `unload`
+also clears the current-track pointer if it named that clip.
+
+## Spatial audio
+
+```js
+audio.position("engine", x, y, z);
+audio.orientation("engine", x, y, z);
+audio.stereo("engine", -1);     // -1 left … 1 right
+audio.panner("engine", { coneInnerAngle: 90, /* … */ });
+```
+
+`position(name, x, y = 0, z = -0.5, id?)` and
+`orientation(name, x, y, z, id?)` both default `id` to "the whole group".
+Called with just the clip name, each of the four returns the current value —
+`stereo` gives `0` and `position` gives `[0, 0, 0]` before they have ever been
+set.
+
+**Spatial audio is WebAudio-only.** On a clip loaded with `stream: true` (or
+`html5: true`) `stereo` / `position` / `orientation` return early and do
+nothing — which is exactly the case for the long music tracks people reach for
+first.
+
+## Procedural sound
+
+For beeps, blips and noise without shipping files. Both take **one options
+object**, and `duration` (in seconds) is required:
+
+```js
+audio.tone({ freq: 440, duration: 0.2, gain: 0.3, pan: -0.5 });
+audio.tone({ freq: [440, 660, 880], duration: 0.4 });   // layered partials
+audio.noise({ duration: 0.5, filter: { type: "lowpass", frequency: 800 } });
+```
+
+`tone` also takes `wave` (default `"sine"`), `attack` (`0.005`) and `pitchSlide`
+(`1`). `noise` takes `type` (`"white"` | `"pink"` | `"brown"`, default
+`"white"`), `attack`, `pan`, `filter` and `filterSweep`. `gain` defaults to `0.1`
+on both.
+
+Both are **silent no-ops** when there is no WebAudio context — they bail on
+`getAudioContext() === null` rather than throwing. Neither needs the clip to be
+loaded; neither goes through the file-playback path at all.
+
+`audio.getAudioContext()` and `audio.getMasterGain()` are the escape hatches for
+custom Web Audio work; both return `null` when audio is unavailable, so guard.
+Connect a custom graph to the master gain rather than `ctx.destination` if you
+want it to respect `setVolume` / `muteAll`.
+
+## Autoplay: sound is silent until the first gesture
+
+Browsers create the audio context in the `suspended` state and keep it there
+until a user interaction. Nothing errors — audio simply does not play, which
+reads as a bug. melonJS installs one-shot `touchstart` / `touchend` / `click` /
+`keydown` unlock listeners on `document`, so the first real gesture anywhere
+unlocks it and fires the clip's `on.unlock` callback. Design for it: start music
+on the first click or key press, not on load. `tone` / `noise` additionally call
+`ctx.resume()` themselves, best-effort, on every invocation.
+
+Playback also starts **asynchronously**: `play()` returns an id while the
+instance is still starting, so `playing()` can legitimately be `false` on the
+very next line.
+
+## Load-time options
+
+```js
+{ name: "sfx", type: "audio", src: "data/sfx/",
+  sprite: { jump: [0, 450] },
+  pool: 5,            // finished instances kept for reuse — NOT a concurrency cap
+  rate: 1.0,          // initial playback rate, 0.5..4.0
+  mute: false,
+  loop: false,
+  autoplay: false,
+  preload: true,      // or "metadata"
+  format: "mp3",      // explicit hint when the URL has no usable extension
+  stream: true,       // long music: stream rather than decode into memory
+  on: { play() {}, end() {}, stop() {}, unlock() {} },
+}
+```
+
+`pool` (default `5`) is a **reuse cap on finished voices**, not a limit on
+simultaneous playback: when the number of ended voices exceeds it, the surplus
+are disconnected and dropped. Raise it for a clip triggered in rapid bursts, not
+to allow more overlap.
+
+Use `stream: true` for long music tracks — it plays through an HTML5 `<audio>`
+element instead of decoding the whole file into memory. (`html5: true` is the
+same switch under its backend name.) `on` accepts the full lifecycle set:
+`play`, `pause`, `stop`, `end`, `fade`, `seek`, `rate`, `volume`, `mute`,
+`unlock`.
+
+Re-preloading a manifest that already contains a loaded clip is a no-op —
+`audio.unload(name)` first if you genuinely want to reload it.
+
+**Credentials use the same global switch as every other asset type** —
+`loader.setOptions({ withCredentials: true })`, not an audio-specific option.
+Buffered audio fetches through the shared loader path, so it honours it exactly
+as an image or a JSON file does. A `stream: true` clip does not: it plays
+through an `<audio>` element, which needs a `crossorigin` attribute rather than
+fetch credentials. Preload a clip buffered if it sits behind a login.
+
+**Failing clips and `setStopOnAudioError(false)`.** The default is to fail the
+preload when a clip cannot be loaded after its retries: the error reaches the
+loader, so `await loader.preload(...)` rejects and your `catch` runs, and the
+reason is logged. Turn the flag off and the engine mutes audio, warns
+(`failed loading <name>, disabling audio`) and lets the load *continue* — the
+preload finishes and the game reaches the next scene without sound.
+
+Before 20.4 both halves were broken: with the flag off it disabled audio and
+failed the preload anyway, and a clip whose bytes arrived but would not decode
+(a missing file served as HTML by an SPA rewrite, say) reported nothing at all
+either way — blank screen, empty console.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| audio assets 404 | `src` given as a full filename instead of a directory prefix |
+| `target audio extension(s) should be set...` thrown at preload | `audio.init()` not called before preloading |
+| `audio clip X does not exist` | the clip was never preloaded, or the name is mis-cased — every per-clip call throws this |
+| nothing plays until the user clicks | browser autoplay policy — expected, design around it |
+| `playing()` is false right after `play()` | playback starts asynchronously |
+| music keeps playing after leaving a scene | used `play` instead of `playTrack`, or no `stopTrack` in teardown |
+| `stereo` / `position` do nothing | the clip was loaded with `stream: true` — spatial is WebAudio-only |
+| one format works, another does not | that codec is not in the `audio.init()` list |
+| audio behind a login fails, or the preload hangs | `loader.setOptions({ withCredentials: true })` — the same switch every asset type uses |
+| a streamed clip ignores `withCredentials` | `stream: true` plays through an `<audio>` element; preload it buffered instead |
+| `audio.tone(440, {...})` does nothing / errors | `tone` takes a single options object with a required `duration` |
+| `tone` / `noise` are silent with no error | no WebAudio context — `getAudioContext()` returned `null` |
+
+## Related skills
+
+- `melonjs-getting-started` — preloading and asset ordering

package/skills/melonjs-camera-and-drawing/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: melonjs-camera-and-drawing
+description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, and baking with CanvasRenderTarget. Triggers on: Camera2d, viewport, follow, setBounds, shake, fadeIn, fadeOut, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d."
+license: MIT
+---
+
+# Camera and immediate-mode drawing
+
+## Following a target
+
+```js
+app.viewport.follow(player, app.viewport.AXIS.BOTH, 0.1);
+```
+
+**Pass the renderable, not `renderable.pos`.** `follow()` accepts a `Renderable`,
+a `Vector2d` or a `Vector3d` and **throws** `invalid target for me.Camera2d.follow`
+for anything else. A renderable's `pos` is an `ObservableVector3d`, which is not
+a `Vector3d` subclass, so `follow(player.pos, …)` throws.
+
+The third argument is a damping factor in `[0 .. 1]` — lower is smoother and
+laggier, `1` snaps. Omit it for a hard lock (it defaults to `1`). It is
+frame-rate independent since 19.7. `AXIS.HORIZONTAL` / `AXIS.VERTICAL` /
+`AXIS.BOTH` / `AXIS.NONE`.
+
+Call it from the followed entity's `onActivateEvent`, using `this.parentApp`.
+
+## Bounds are the thing people forget
+
+The camera's bounds default to the **renderer size**, so it cannot scroll until
+you widen them to the world:
+
+```js
+app.viewport.setBounds(0, 0, mapWidth, mapHeight);
+```
+
+Symptom: `follow()` is called, looks right, and the view never moves. Note a
+canvas resize resets the default camera's bounds to `(0, 0, w, h)`, so re-apply
+them from a `CANVAS_ONRESIZE` handler if your game resizes. Loading a Tiled map
+sets them for you from the map size.
+
+## Camera effects
+
+```js
+app.viewport.shake(4, 200);                       // intensity, ms
+app.viewport.fadeIn("#000000", 500);              // fade TO black
+app.viewport.fadeOut("#000000", 500);             // start black, fade back to normal
+app.viewport.colorMatrix.contrast(1.1).saturate(1.1);
+app.viewport.addPostEffect(new VignetteEffect(app.renderer));
+```
+
+The fade pair is named from the *colour's* point of view, not the scene's:
+`fadeIn` fades the colour in (screen goes to `color`), `fadeOut` fades it out
+(screen starts at `color` and clears). Both default to a 1000 ms duration and
+take an optional completion callback.
+
+`colorMatrix` (`brightness` / `contrast` / `saturate` / `hueRotate` / `sepia` /
+`invertColors`, all chainable) is the cheap way to grade a whole camera: the
+camera appends it as a final post-effect pass by itself whenever the matrix is
+non-identity, and drops it again after the frame. It is **not** shader-free —
+it is a `ColorMatrixEffect`, i.e. a `ShaderEffect`, so like every post effect it
+is inert on the Canvas renderer.
+
+## Coordinate conversion
+
+```js
+app.viewport.worldToLocal(x, y);   // world → screen
+app.viewport.localToWorld(x, y);   // screen → world
+```
+
+Both return a `Vector2d`; with no third argument that vector comes from the
+shared pool, so in a per-frame path pass your own `v` as the third argument, or
+release it with `getPool("vector2d").release(v)`.
+
+Pointer events already carry every frame of reference: `gameWorldX`/`gameWorldY`
+(world), `gameScreenX`/`gameScreenY` (screen), `gameLocalX`/`gameLocalY`
+(relative to the registered region's container) and `gameX`/`gameY`, which is
+whichever of world/screen matches the region — screen for a `floating` region,
+world otherwise. Use the screen pair for anything that *moves* the camera, or
+the drag feeds back on itself.
+
+## Secondary cameras
+
+Cameras are first-class — a minimap is a second camera with `autoResize = false`
+and an overridden `postDraw`:
+
+```js
+this.cameras.set("minimap", new MinimapCamera());
+```
+
+View state is per camera, not per scene: a `Camera3d` carries its own distance
+fog (`setFog`), so a minimap or split-screen view fogs independently of the main
+one — and a `Camera2d` never fogs. See `melonjs-3d`.
+
+## Immediate-mode drawing
+
+Inside a custom `draw(renderer)` you can draw shapes directly. Remember the two
+renderable rules: read `this.pos`, and zero the anchor.
+
+```js
+draw(renderer) {
+    renderer.setColor("#ff8800");
+    renderer.fillRect(this.pos.x, this.pos.y, this.width, this.height);
+
+    renderer.setColor("#ffffff");
+    renderer.lineWidth = 2;                 // property, not setLineWidth()
+    renderer.stroke(new Line(0, 0, [/* … */]));
+}
+```
+
+Geometry available: `Rect`, `RoundRect`, `Ellipse`, `Polygon`, `Line`, `Point`
+(and a `Bounds`). `renderer.fill(shape)` and `renderer.stroke(shape)` take any
+of them and throw `Invalid geometry for fill/stroke` for anything else.
+
+`Gradient` gives linear and radial fills, built with
+`renderer.createLinearGradient(x0, y0, x1, y1)` /
+`createRadialGradient(x0, y0, r0, x1, y1, r1)` and then handed to
+`renderer.setColor(gradient)`. `NoiseTexture2d` generates cellular and simplex
+noise — including seamless tiling and `asNormalMap` — so you rarely need to ship
+noise PNGs.
+
+## Clipping and masking
+
+```js
+renderer.clipRect(x, y, w, h);        // rectangular clip
+renderable.mask = new Ellipse(/* … */);  // shape mask on an object
+```
+
+Note that a `Container` with `clipping` enabled clips **after** its own
+`translate(pos)`, in container-local coordinates — `clipRect(0, 0, width,
+height)`. It also silently does nothing unless the container is non-root and has
+a finite `width`/`height`: a `Container` built with no explicit size is
+`Infinity × Infinity`, and `clipping = true` on it is a no-op.
+
+## Bake once, draw many
+
+When you would otherwise issue hundreds of identical draws every frame, render
+them once into a `CanvasRenderTarget` and draw the result:
+
+```js
+const rt = new CanvasRenderTarget(width, height, { context: "2d" });
+const ctx = rt.context;          // a CanvasRenderingContext2D — draw into it once…
+// then draw the backing canvas, not the target object:
+renderer.drawImage(rt.canvas, x, y);
+// or wrap it: new Sprite(0, 0, { image: rt.canvas })
+```
+
+Pass `rt.canvas`, never `rt` — a `CanvasRenderTarget` is a wrapper, not a
+drawable, and the engine's own bakes (the particle emitter's default texture)
+hand `.canvas` on for exactly that reason.
+
+This is the sanctioned performance idiom before reaching for a custom shader.
+
+`renderer.toFrameTexture()` is the related tool for capturing the *current frame*
+into a texture for a shader to sample.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| `follow()` set but the view never moves | viewport bounds still at renderer size |
+| `invalid target for me.Camera2d.follow` | passed `player.pos` — pass the renderable, a `Vector2d` or a `Vector3d` |
+| camera drag jumps around | using world (`gameWorldX`) instead of screen (`gameScreenX`) coordinates |
+| `colorMatrix` does nothing | it is a shader effect — inert on the Canvas renderer |
+| custom drawing appears at the origin | `draw()` not reading `this.pos` |
+| custom drawing offset by half its size | centred `anchorPoint` not zeroed |
+| `setLineWidth` is not a function | it is the `lineWidth` property |
+| clipping in the wrong place inside a container | container clips in local coordinates, after its own translate |
+| `container.clipping = true` does nothing | container has no explicit size, so `width`/`height` are `Infinity` |
+| baked target draws nothing / throws | passed the `CanvasRenderTarget`, not its `.canvas` |
+| frame rate drops with many static draws | bake into a `CanvasRenderTarget` instead |
+
+## Related skills
+
+- `melonjs-renderables` — the `draw()` contract and anchors
+- `melonjs-3d` — `Camera3d`, which extends `Camera2d` and keeps all of the above