melonjs 20.2.0 → 20.4.0

package/skills/melonjs-deployment/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: melonjs-deployment
+description: "Use this skill when packaging, shipping or scaffolding a melonJS game — starting a project with create-melonjs, building for the web, wrapping as a native app with Capacitor or Cordova, publishing to WeChat Mini Games or Facebook Instant Games, browser support and transpiling. Triggers on: create-melonjs, scaffold, new project, build, deploy, publish, Capacitor, Cordova, native app, iOS, Android, WeChat, Instant Games, browser support, transpile, ES2022, bundle size, tree-shaking."
+license: MIT
+---
+
+# Starting and shipping a project
+
+## Scaffolding
+
+Start from the template rather than assembling a build by hand:
+
+```bash
+npm create melonjs@latest my-game
+```
+
+The project name is required — without it the command prints its usage and
+exits. It downloads the melonJS TypeScript boilerplate (Vite, TypeScript and the
+debug plugin already wired in), which saves you the top-level-await and
+asset-path issues that a hand-rolled config usually hits first.
+
+## Adding melonJS to an existing project
+
+```bash
+npm install melonjs
+```
+
+```js
+import { Application, Sprite, loader } from "melonjs";
+```
+
+The package is a tree-shakeable ES module with TypeScript declarations included
+and **no runtime dependencies**.
+
+A CDN build exists for quick experiments, but not for production:
+
+```html
+<script type="module">
+    import { Application } from "https://cdn.jsdelivr.net/npm/melonjs@20/+esm";
+</script>
+```
+
+## Browser support and transpiling
+
+The published bundle targets **ES2022** and uses private class members. A browser
+that predates that **cannot parse the file at all** — it fails at load, not when
+a feature is used, so the symptom is a blank page with a syntax error.
+
+To support older browsers, transpile melonJS **together with your own code**.
+The usual trap is that build setups skip `node_modules` by default, leaving
+melonJS untouched however low you set your target:
+
+```js
+// vite.config.js — esbuild downlevels dependencies too
+export default { build: { target: "es2020" } };
+```
+
+```js
+// webpack: the default `exclude: /node_modules/` would skip melonjs
+{ test: /\.js$/, exclude: /node_modules\/(?!melonjs)/, use: "babel-loader" }
+```
+
+Two caveats worth knowing:
+
+- **Transpiling handles syntax only.** Built-in methods need separate polyfills;
+  a bundler's `target` setting will never add them.
+- Downlevelled private class members become `WeakMap` lookups, and melonJS uses
+  them in the renderer's hot paths. This is a real trade, not a free switch.
+
+## Native apps
+
+**Capacitor** is the current recommendation for iOS and Android — see
+`@melonjs/capacitor-plugin`. **Cordova** also works and is documented, but is the
+older route.
+
+The thing that breaks first in both is asset loading: the app is served from
+`file://`, where `fetch()` cannot read local files. melonJS's loader falls back
+to XHR for that scheme, so engine-loaded assets work — but any `fetch()` in
+*your* game code will fail there.
+
+## Mini-game platforms
+
+**WeChat Mini Games** and **Facebook Instant Games** are both documented in the
+wiki. Note that `device.platform.isWeixin` detects WeChat's **in-app browser**,
+which is a normal WebView. WeChat *Mini Games* are a different runtime with no
+DOM, and need platform-specific adaptation rather than just detection — the one
+hook the engine offers is that the renderer adopts a `globalThis.canvas` when
+the runtime's adapter provides one, instead of creating its own.
+
+## Size
+
+The whole engine is roughly **250 KB minzipped**. Tree-shaking helps less than
+you might expect — the engine's subsystems reach each other, so a game importing
+a handful of symbols still pulls most of it. Budget for the full figure.
+
+Practical wins are in assets, not the engine: pack sprites into atlases, prefer
+one tileset over several, and use `stream: true` for long music tracks so they
+are not decoded into memory.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| blank page, syntax error in the console | browser older than the ES2022 target |
+| transpiling changes nothing | build config excludes `node_modules` |
+| assets 404 in a packaged native app | `fetch()` in game code — `file://` needs XHR |
+| a built-in method is missing after transpiling | transpiling is syntax-only; polyfills are separate |
+| bundle much larger than expected | tree-shaking recovers little — subsystems are interconnected |
+
+## Related skills
+
+- `melonjs` — the companion packages, including the Capacitor plugin
+- `melonjs-getting-started` — the Application bootstrap the template produces

package/skills/melonjs-effects-and-shaders/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: melonjs-effects-and-shaders
+description: "Use this skill for post-processing effects, custom shaders, blend modes and colour grading in melonJS. Covers the built-in ShaderEffect presets, addPostEffect on renderables and cameras, writing a custom dual-language GLSL/WGSL effect, the screen_texture builtins, and why effects silently do nothing on the Canvas fallback. Triggers on: ShaderEffect, addPostEffect, removePostEffect, getPostEffect, VignetteEffect, GlowEffect, BlurEffect, PixelateEffect, ScanlineEffect, shader, GLSL, WGSL, uniform, setUniform, setTexture, setTime, blendMode, colorMatrix, screen_texture, toFrameTexture, post effect, filter."
+license: MIT
+---
+
+# Post effects and custom shaders
+
+> melonJS ships a catalogue of post effects and a dual-language shader system.
+> The recurring trap is that every shader path needs a GPU backend and
+> **degrades to nothing** on Canvas rather than erroring. Blend modes are the
+> exception — those work on all three renderers.
+
+## Applying an effect
+
+Effects attach to a renderable **or** to a camera (for full-screen grading):
+
+```js
+import { VignetteEffect, GlowEffect } from "melonjs";
+
+sprite.addPostEffect(new GlowEffect(app.renderer));
+app.viewport.addPostEffect(new VignetteEffect(app.renderer));
+```
+
+`renderable.shader = …` is **deprecated since 19.2.0**, and its setter destroys
+whatever it replaces. Use `addPostEffect` / `getPostEffect` / `removePostEffect`.
+
+## Toggle with `enabled`, do not remove
+
+**`removePostEffect()` destroys the effect** — it calls `effect.destroy()` and
+frees GPU resources, so the instance cannot be re-added. Same for
+`clearPostEffects()` and for reassigning the deprecated `.shader`.
+
+```js
+// ✗ destroys it; re-adding later fails or forces a recompile
+sprite.removePostEffect(effect);
+
+// ✓
+effect.enabled = false;
+```
+
+An effect with `effect.shared === true` opts out of auto-destroy because it is
+reused across renderables.
+
+## Built-in effects
+
+Eighteen presets, every one constructed as `new XEffect(renderer, options)` and
+every one shipping both a GLSL and a WGSL body, so they all run on either GPU
+backend: `VignetteEffect`, `ScanlineEffect` (optional CRT curvature),
+`GlowEffect`, `BlurEffect`, `PixelateEffect`, `ChromaticAberrationEffect`,
+`DropShadowEffect`, `FlashEffect`, `OutlineEffect`, `ColorMatrixEffect`,
+`DesaturateEffect`, `DissolveEffect`, `TintPulseEffect`, `WaveEffect`,
+`InvertEffect`, `SepiaEffect`, `HologramEffect`, `ShineEffect`.
+
+For grading without writing a shader yourself, the camera has a colour matrix:
+
+```js
+app.viewport.colorMatrix.contrast(1.1).saturate(1.1);
+```
+
+It is still *implemented* as one: a non-identity matrix makes the camera append
+an internal `ColorMatrixEffect` to its post-effect chain for that frame, so it
+needs a GPU backend like everything else here.
+
+## Custom effects are dual-language
+
+A custom `ShaderEffect` supplies a fragment **body**, not a whole program. To run
+on both GPU backends it needs GLSL *and* WGSL — a GLSL-only effect silently does
+nothing when `video.AUTO` lands on WebGPU.
+
+```js
+const effect = new ShaderEffect(app.renderer, { glsl, wgsl });
+effect.setUniform("uStrength", 0.5);
+effect.setTexture("uScene", tex);
+effect.setTime(timer.getTime() / 1000);   // setTime takes SECONDS; getTime is ms
+```
+
+Uniform names are shared across the two bodies — in WGSL they are the members of
+one `@group(3) @binding(0) var<uniform>` struct — so a single `setUniform` call
+feeds whichever backend is live. `setTime` is a convenience for a `uTime`
+uniform and silently does nothing if the shader does not declare one.
+
+Shaders can also be preloaded as assets with loader type `"shader"`.
+
+### Screen-reading builtins
+
+For refraction, distortion and anything that samples what is already drawn:
+
+- **`screen_texture`** — a sampler kept filled with everything drawn so far
+  (GLSL: annotate the sampler `uniform sampler2D tex : screen_texture;`)
+- **`screen_uv`** — this fragment's 0..1 position in that capture
+- **`noise_uv`** — 0..1 across the sprite regardless of its atlas frame
+
+In WGSL the capture is sampled through `screen_sampler` (clamped) or
+`screen_sampler_repeat` (wrapping) instead of GLSL's `: screen_texture`
+annotation. `screen_uv` is y-**up** in GLSL and y-**down** in WGSL, which exactly
+matches each backend's own capture orientation — so a body that samples
+`screen_texture` at `screen_uv` needs no flip in *either* language.
+
+Two places where a straight port really does differ:
+
+- **A capture you bind yourself.** `renderer.toFrameTexture()` grabs the frame
+  into a `Texture2d` you hand to `setTexture` — the supported replacement for
+  `readPixels` tricks. The GL capture is bottom-up (GLSL bodies sample it with
+  `1.0 - uv.y`) and opaque RGB; the WebGPU capture is top-down (the WGSL twin
+  must *not* flip) and preserves alpha.
+- **Vertical UV offsets** — a drop shadow, a directional smear. The WebGL pooled
+  multi-effect path composites through bottom-up FBOs, so declare a `uUVYDir`
+  uniform (initialise it to `1.0`) and multiply vertical offsets by it; the
+  renderer feeds `-1` on that path and `+1` everywhere else.
+
+## Blend modes
+
+Fourteen modes; thirteen of them are honoured by all three renderers:
+
+```js
+sprite.blendMode = "additive";   // or "multiply", "screen", "overlay", …
+```
+
+Six ride fixed-function blend state and cost nothing extra: `normal`,
+`additive` (spelled `add` or `lighter` too), `multiply`, `screen`, `exclusion`,
+and `none` (blending off — the source replaces the destination, alpha included).
+`none` is the one mode the Canvas backend does not implement; it reports
+`"normal"` instead.
+
+The other eight cannot be expressed as a multiply-add on the destination, so the
+GPU backends capture the destination and composite through `BlendEffect` — one
+capture plus one composite **per draw**: `difference`, `overlay`, `hard-light`,
+`color-dodge`, `color-burn`, `soft-light`, `darken`, `lighten`. Right for
+accents; expensive for hundreds of objects. The Canvas renderer reaches all
+eight through `globalCompositeOperation` instead, at no extra cost.
+
+Anything else collapses to `"normal"`, and so do 3D meshes and `Gradient` fills
+whatever you ask for — the latter with a one-time console warning.
+`renderer.setBlendMode(mode)` returns the mode it actually applied, so comparing
+that against your request detects the fallback.
+
+## The Canvas fallback
+
+`ShaderEffect` on a Canvas renderer logs a warning, leaves `enabled = false`, and
+turns every method into a no-op. Nothing throws. The same happens on a GPU
+backend when no body matches its language — a GLSL-only effect under WebGPU.
+
+That is fine for decoration. It is **not** fine when the shader draws your
+content — the carrier renderable then shows through raw. A 1×1 white texture
+stretched to 280×156 renders as a white box where the effect should be.
+
+Guard when the effect is load-bearing:
+
+```js
+if (app.renderer.shaderLanguage === null) {
+    // no programmable pipeline — skip the carrier draw entirely
+}
+```
+
+`shaderLanguage` (`"glsl"`, `"wgsl"`, or `null`) is the flag to test here rather
+than a backend name or `supportsDepthBuffer`: it answers "can this renderer
+compile what I am about to hand it". Per-effect, `effect.enabled` answers the
+same question after construction.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| effect does nothing, warning in console | Canvas fallback — no programmable pipeline |
+| effect does nothing on some machines only | GLSL-only shader, `video.AUTO` chose WebGPU |
+| a white or solid box where the effect should be | carrier renderable drawn while the effect is disabled |
+| effect cannot be re-enabled | `removePostEffect()` destroyed it — use `enabled` |
+| ported shader renders upside down | a hand-bound `toFrameTexture()` capture — GL is bottom-up, WebGPU top-down |
+| shadow/smear offset flips on some draws | vertical UV offset not multiplied by `uUVYDir` |
+| frame rate collapses with many blended sprites | an *advanced* mode (overlay, darken, …) — each draw is a capture plus a composite |
+| animated shader never moves | `setTime` fed milliseconds, or the shader declares no `uTime` |
+
+## Related skills
+
+- `melonjs-renderables` — where post effects attach, and the destroy trap
+- `melonjs-3d` — the GPU-backend requirement, and why a custom mesh shader is
+  not affected by the camera's distance fog

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