melonjs 20.2.0 → 20.3.0

package/skills/melonjs-events/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: melonjs-events
+description: "Use this skill for the melonJS event bus and lifecycle hooks — subscribing to engine events, the per-frame and per-state event names, renderable lifecycle callbacks, and how to unsubscribe without leaking. Triggers on: event.on, event.off, event.once, event.emit, GAME_UPDATE, GAME_BEFORE_DRAW, LEVEL_LOADED, LOADER_COMPLETE, STATE_CHANGE, CANVAS_ONRESIZE, POINTERMOVE, WORLD_STEP, onActivateEvent, onDeactivateEvent, onDestroyEvent, lifecycle, subscribe, listener."
+license: MIT
+---
+
+# Events and lifecycle
+
+## The bus
+
+```js
+import { event } from "melonjs";
+
+const onUpdate = () => { /* … */ };
+const unsubscribe = event.on(event.GAME_UPDATE, onUpdate);  // on() returns its own off()
+event.once(event.LEVEL_LOADED, () => { /* … */ });
+
+// two ways to undo it — the same reference, or the returned function
+event.off(event.GAME_UPDATE, onUpdate);
+unsubscribe();
+```
+
+`event.on`/`once`/`off`/`has` all take an optional third `context` argument,
+invoked as the handler's `this`. **`off` matches on the pair — handler identity
+AND context identity.** `on(EVT, fn, this)` followed by `off(EVT, fn)` removes
+nothing, silently.
+
+**Store the handler reference, or use the context argument.** An inline arrow or
+a fresh `.bind(this)` in the `on` call can never be removed — that is the
+standard way to leak listeners in melonJS.
+
+```js
+// ✗ unremovable
+event.on(event.GAME_UPDATE, this.tick.bind(this));
+
+// ✓ keep the bound reference
+this._tick = this.tick.bind(this);
+event.on(event.GAME_UPDATE, this._tick);
+// later: event.off(event.GAME_UPDATE, this._tick);
+
+// ✓ or skip the bind entirely — the context is part of the identity
+event.on(event.GAME_UPDATE, this.tick, this);
+// later: event.off(event.GAME_UPDATE, this.tick, this);
+```
+
+Custom event names work at runtime (`event.emit("my.custom.event", payload)`),
+but `on`/`emit` are typed against a closed map of the engine's own events, so in
+TypeScript a name outside that map is a compile error. Use your own emitter for
+game events in a `.ts` project.
+
+## The events worth knowing
+
+**Per frame**
+
+| event | when |
+|---|---|
+| `GAME_BEFORE_UPDATE` / `GAME_UPDATE` / `GAME_AFTER_UPDATE` | around the world update — `GAME_UPDATE` is **not** emitted while paused |
+| `GAME_BEFORE_DRAW` / `GAME_AFTER_DRAW` | around the draw pass |
+| `WORLD_STEP` | after the physics step |
+| `TICK` | the raw engine tick |
+
+**Lifecycle**
+
+| event | when |
+|---|---|
+| `BOOT`, `GAME_INIT`, `VIDEO_INIT` | engine start-up |
+| `STATE_CHANGE`, `STATE_PAUSE`, `STATE_RESUME`, `STATE_STOP` | state machine |
+| `STAGE_RESET` | a stage was reset |
+| `LEVEL_LOADED` | a Tiled level finished loading |
+| `LOADER_PROGRESS`, `LOADER_COMPLETE`, `LOADER_ERROR` | asset loading |
+| `BLUR` / `FOCUS` | the page lost or regained focus |
+| `CANVAS_ONRESIZE`, `VIEWPORT_ONRESIZE` | relayout hooks |
+| `POINTERMOVE` | global pointer movement |
+
+Use `LOADER_PROGRESS` / `LOADER_COMPLETE`. The `loader.onProgress` /
+`loader.onload` / `loader.onError` properties were deprecated in 18.2.0 and
+removed in 20.3: they were module-level `let` bindings on an ES module
+namespace, so `loader.onProgress = fn` threw and the documented migration path
+never worked. For completion, `loader.preload(assets, onloadcb)` also takes the
+callback directly.
+
+## Renderable lifecycle callbacks
+
+Prefer these over bus subscriptions where they fit — the engine calls them at the
+right times and there is nothing to unsubscribe:
+
+| callback | when |
+|---|---|
+| `onActivateEvent()` | `addChild`-ed into a container that is already attached to the world root (a `Container` forwards it to its children) |
+| `onDeactivateEvent()` | removed from its container — including the automatic world clear on a state change |
+| `onDestroyEvent()` | `destroy()` ran; called with no arguments from the container-removal path |
+| `onCollisionStart` / `onCollisionActive` / `onCollisionEnd` | contacts |
+
+Note the activate gate: adding a child to a *detached* container fires nothing.
+The callback arrives later, when that container itself is added to the world.
+And an `isPersistent` renderable survives the world clear between stages, so it
+gets no fresh `onActivateEvent` on the next state.
+
+**Pair subscriptions with activate/deactivate, not the constructor.** This is
+the rule that keeps pooled objects working:
+
+```js
+onActivateEvent() {
+    this._tick = this.update.bind(this);
+    event.on(event.GAME_UPDATE, this._tick);
+    input.registerPointerEvent("pointerdown", this, this._onDown);
+}
+onDeactivateEvent() {
+    event.off(event.GAME_UPDATE, this._tick);
+    input.releasePointerEvent("pointerdown", this);
+}
+```
+
+**Pool-recycled objects never fire `onDestroyEvent` on removal** — `removeChildNow`
+tries `pool.push(child)` first and only calls `destroy()` if that fails, so a
+class registered with `pool.register(name, Class, true)` goes back to the pool
+instead. Anything you clean up there will not run. `destroy()` is also what calls
+`releaseAllPointerEvents(this)`, which is why a pooled object must release its
+own pointer registrations in `onDeactivateEvent`.
+
+## Guard callbacks that can fire during teardown
+
+Events can arrive while a stage is being dismantled, when the current state is
+already something else:
+
+```js
+if (!state.isCurrent(state.PLAY)) return;
+```
+
+Without this, a "children emptied" handler can reset the wrong stage.
+
+## Removing objects from a collision callback
+
+Contact callbacks fire inline inside the physics step, mid-iteration over the
+detector's pair list. `container.removeChild()` is safe there — it defers the
+actual removal to the next tick, which is exactly why it defers. The immediate
+forms are the dangerous ones: `removeChildNow()` and `destroy()` tear the object
+down under the iteration (`destroy()` nulls `pos` and `body`). The builtin
+detector guards the pair it is currently resolving, but nothing guarantees that
+for the rest of the step or for another adapter.
+
+Use `removeChild()`, or flag the work and drain it from `Stage.update`.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| handler still fires after removing the object | `event.off` given a different function reference, or a different `context` than `on` got |
+| handlers accumulate on pooled objects | subscribed in the constructor rather than `onActivateEvent` |
+| cleanup never runs on a pooled object | pooled removal does not fire `onDestroyEvent` |
+| crash during a stage switch | callback ran mid-teardown — guard with `state.isCurrent` |
+| crash after a collision | `removeChildNow()` / `destroy()` inside a contact callback — use `removeChild()` |
+| progress callbacks never fire | assigned `loader.onProgress` (removed in 20.3) instead of subscribing to `LOADER_PROGRESS` |
+| `onActivateEvent` never runs | the child was added to a container not yet attached to the world |
+
+## Related skills
+
+- `melonjs-scenes-and-state` — the state machine and stage lifecycle
+- `melonjs-performance` — pooling, and why activate/deactivate pairing matters

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

@@ -0,0 +1,183 @@
+---
+name: melonjs-getting-started
+description: "Use this skill when starting or bootstrapping a melonJS game, creating the Application, choosing a renderer, or setting up the first scene. Covers the mandatory async init, the world container, adding renderables, and the WebGPU/WebGL 2/Canvas fallback. Triggers on: melonjs, new Application, app.init, app.world, video.AUTO, video.WEBGL, video.CANVAS, Stage, state.change, getting started, bootstrap."
+license: MIT
+---
+
+# Getting started with melonJS
+
+> Bootstrapping a melonJS 20.x game: the `Application` lifecycle, the mandatory
+> `await app.init()`, the world container, and what the renderer fallback means
+> for feature availability.
+
+**Applies to:** melonJS 20.x. Older major versions differ — see the
+`melonjs-20-migration` skill.
+
+## The bootstrap
+
+`Application` construction is synchronous but **initialisation is not**. `init()`
+returns a promise and must be awaited before building any renderable, loading
+assets, or entering a scene.
+
+```js
+import { Application, Text } from "melonjs";
+
+const app = new Application(1218, 562, {
+    parent: "screen",      // id of the DOM element to mount into
+    scale: "auto",
+    backgroundColor: "#202020",
+});
+await app.init();          // ← REQUIRED. Nothing below works without it.
+
+app.world.addChild(
+    new Text(609, 281, {
+        font: "Arial",
+        size: 160,
+        fillStyle: "#FFFFFF",
+        textAlign: "center",
+        textBaseline: "middle",
+        text: "Hello World !",
+    }),
+);
+```
+
+**This is the single most common thing to get wrong.** On 19.x the constructor
+called `init(width, height, options)` for you; on 20.x `init()` takes no
+arguments and calling — and awaiting — it is your job. Nothing that follows
+names the missing call. The constructor does build `app.world`, so adding a
+plain renderable succeeds and simply never draws — no canvas is appended and the
+app never subscribes to the frame tick — while constructing a `Sprite` or a
+`Text` throws `Cannot read properties of undefined (reading 'renderer')`,
+because the global `game` those two fall back on is only set once the first
+`init()` resolves. Either way `app.renderer` and `app.viewport` stay `undefined`
+and the page stays blank.
+
+`init()` is asynchronous because acquiring a WebGPU device is asynchronous. There
+is no synchronous alternative.
+
+## Top-level await
+
+The bootstrap needs `await` at module scope. In an ES module that is fine. If the
+surrounding tooling does not allow it, wrap it:
+
+```js
+async function main() {
+    const app = new Application(800, 600, { parent: "screen" });
+    await app.init();
+    // …
+}
+void main();
+```
+
+## Choosing a renderer
+
+`video.AUTO` (the default) tries **WebGPU → WebGL 2 → Canvas** and uses the first
+that works.
+
+```js
+import { video } from "melonjs";
+
+const app = new Application(800, 600, {
+    parent: "screen",
+    renderer: video.AUTO,      // default; or video.WEBGPU / video.WEBGL / video.CANVAS
+});
+```
+
+Two consequences worth knowing before writing rendering code:
+
+- **Which backend you get is a runtime fact, not a build-time one.** The same
+  code runs on a different renderer depending on the machine. Do not assume
+  WebGL.
+- **Not every feature exists on every backend.** Shader effects and post effects
+  need a programmable pipeline and are inert on Canvas. Where a feature degrades,
+  the engine warns once rather than throwing — so a missing effect is a console
+  warning, not a crash.
+
+Pin the renderer explicitly (`video.WEBGL`) only when you have a reason to. It
+costs you the WebGPU path and the Canvas fallback.
+
+## The scene graph
+
+`app.world` is the root `Container`. Everything drawn is a descendant of it.
+
+```js
+app.world.addChild(sprite, 10);   // 10 is the z / draw order
+```
+
+**Pass the z-order as the second argument to `addChild`** — it is the only form
+that works. `renderable.z` does not exist as a property, setting `depth` before
+`addChild` is overwritten by `autoDepth`, and setting it afterwards does not
+resort. See the `melonjs-renderables` skill for the full explanation.
+
+## Scenes
+
+For anything beyond a single screen, use `Stage` subclasses and the `state`
+manager rather than mutating `app.world` directly:
+
+```js
+import { Stage, state } from "melonjs";
+
+class PlayScreen extends Stage {
+    onResetEvent() { /* build the scene */ }
+    onDestroyEvent() { /* tear it down */ }
+}
+
+state.set(state.PLAY, new PlayScreen());
+state.change(state.PLAY);
+```
+
+`onResetEvent` runs every time the state is entered, not once — build scene
+content there, not in the constructor.
+
+## Loading assets
+
+Assets are declared and preloaded through `loader`; audio needs `audio.init()`
+with the formats you ship before any audio asset is preloaded.
+
+```js
+import { audio, loader } from "melonjs";
+
+loader.setOptions({ crossOrigin: "anonymous" });   // needed for remote assets
+audio.init("mp3,ogg");                             // BEFORE preloading audio
+await loader.preload([
+    { name: "tileset", type: "image", src: "data/img/tileset.png" },
+    { name: "jump",    type: "audio", src: "data/sfx/" },   // directory, not file
+]);
+```
+
+Two ordering rules that produce confusing failures when missed:
+
+- **`audio.init()` must run before any audio asset is preloaded**, and names the
+  formats you actually ship. Preloading first throws *"target audio extension(s)
+  should be set through me.audio.init() before calling the preloader"*.
+- The audio `src` is a **directory**, not a file. The loader appends the asset
+  `name` plus each configured extension, so a full filename gives you a 404.
+
+## `anchorPoint` defaults to the centre
+
+`Renderable.anchorPoint` is `(0.5, 0.5)`, so `pos` is an object's **centre**, not
+its top-left. `Container` forces `(0, 0)` instead.
+
+Writing top-left math against a centred anchor puts everything half a sprite off
+with no error — it is the most common source of "close but subtly wrong"
+placement.
+
+## Common mistakes
+
+| symptom | cause |
+|---|---|
+| blank page, nothing drawn, or a `TypeError` reading `renderer` from `new Sprite` / `new Text` | missing `await app.init()` |
+| objects draw in the wrong order | `.z`/`depth` set instead of `addChild(child, z)` — `.z` is not even a real property |
+| shader/post effect does nothing, warning in console | running on the Canvas renderer |
+| audio 404s | audio asset `src` given as a file rather than a directory |
+| scene content appears once and never resets | scene built in the constructor instead of `onResetEvent` |
+| everything offset by half a sprite | top-left math against the centred `anchorPoint` default |
+| a `Tween` or `ParticleEmitter` does nothing | `.start()` / `streamParticles()` never called |
+| cross-origin textures fail to load | missing `loader.setOptions({ crossOrigin: "anonymous" })` |
+
+## Related skills
+
+- `melonjs-20-migration` — what changed in 20.x that older code and older
+  training data get wrong
+- `melonjs-renderables` — custom `Renderable` subclasses, pointer events, post
+  effects and the traps in each

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