melonjs 20.1.1 → 20.3.0

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

@@ -0,0 +1,239 @@
+---
+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, 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 |
+| `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: with the game loop running, `level.load` stops the loop and
+defers the actual load to the next tick, so it returns *before* anything is in
+the world. 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.
+
+## 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 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
+- `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,215 @@
+---
+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.
+
+## 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.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,171 @@
+---
+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());
+```
+
+## 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