melonjs 20.2.0 → 20.3.0

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

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,177 @@
+---
+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` — custom mesh shaders and the GPU-backend requirement