melonjs 20.13.0 → 20.14.0

package/skills/melonjs-audio/SKILL.md

@@ -19,10 +19,13 @@ await loader.preload([
 ```
 
 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"`.
+   lists the formats you actually ship. Preloading first fails the preload:
+   `await loader.preload(...)` rejects with the loader's `Failed loading
+   resource <src>`, which hides the real reason, `target audio extension(s)
+   should be set through me.audio.init() before calling the preloader.`
+   (thrown as it is by `audio.load()` called directly). 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
@@ -50,13 +53,19 @@ audio.playTrack("theme");               // background music
 audio.stopTrack();
 ```
 
-Use **`playTrack`** for music, not `play`. `playTrack(name, volume?)` always
+Use **`playTrack`** for music, not `play`. `playTrack(name, volume?)` (or
+`playTrack(name, { volume, sprite })`, to loop one region of the clip) 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 name*.
 
+`playTrack` on a track that is paused restarts it. `pauseTrack` and
+`resumeTrack` act on the track alone, so effects played from the same file (an
+audio sprite holding both) keep going, and `resumeTrack` on a track that is
+playing does nothing.
+
 **`playTrack` stops the track it replaces** (20.9.0 and later; before that it
 only assigned the slot, and the previous bed kept looping underneath where
 `stopTrack()` could no longer reach it). So a scene just states its own music
@@ -155,6 +164,11 @@ audio.unmuteAll();              // (audio.enable() is an alias)
 audio.muted();                  // global mute state
 ```
 
+`setVolume` is a master level over everything; the `volume` given to a `play`
+or `playTrack` is that sound's own level, 1 when left out, and what is heard is
+the product of the two. So a music slider fades the track's own level
+(`audio.fade(name, v, v, 1)`) and a master slider calls `setVolume`.
+
 `audio.unload(name)` / `audio.unloadAll()` free the decoded buffers; `unload`
 also clears the current-track pointer if it named that clip.
 
@@ -163,8 +177,10 @@ also clears the current-track pointer if it named that clip.
 When the window loses focus the engine mutes all audio, and unmutes it on
 focus. That covers sound effects, procedural `tone` / `noise` and the mixer
 effects, not just the music track that `state.pause()` pauses. Set
-`pauseOnBlur: false` in the application settings if a clip has to keep playing
-in the background.
+`app.pauseOnBlur = false` (with `stopOnBlur` left at its `false` default) if a
+clip has to keep playing in the background. It is a property of the
+application, not a constructor setting: `new Application(w, h, { pauseOnBlur:
+false })` does nothing.
 
 ## Spatial audio
 
@@ -197,10 +213,15 @@ audio.play("portal", { at: { x: 1200, y: 480 } });
 
 `follow` and `at` are mutually exclusive: passing both throws, rather than
 quietly picking one. `follow` re-reads the target's **absolute** position each
-frame, so a renderable nested in a moving container is placed correctly. `stopWithTarget` is what you
-want for a sound that belongs to an entity: without it a looping clip on a
-destroyed renderable keeps playing from wherever it last was. `audio.unfollow(id)`
-detaches a sound and leaves it playing where it is.
+frame, so a renderable nested in a moving container is placed correctly. That
+position is where its `anchorPoint` sits: the center of a `Renderable` or a
+`Sprite`, but the **top-left corner** of an `Entity` or an object loaded from
+Tiled, whose anchor is `(0, 0)`, so a large one (a boss) sounds from up and to
+the left of where it looks to be. `stopWithTarget` is what you want for a sound
+that belongs to an entity: without it a looping clip on a destroyed renderable
+keeps playing from wherever it last was. It also counts a pooled renderable
+going back to its pool, which can lend it out again before the next frame.
+`audio.unfollow(id)` detaches a sound and leaves it playing where it is.
 
 ### Move the listener, don't do the subtraction yourself
 
@@ -221,7 +242,12 @@ player's position.
 `setListener` places the ear at the target's absolute position after the world
 updates. A plain renderable contributes position only, so a side-scroller keeps
 the default "facing into the screen" and gets left-right panning plus distance
-falloff from the one call.
+falloff from the one call. A `Camera2d` (`audio.setListener(app.viewport)` in a
+2D game) is heard from the **center of its view**, its `worldView`, zoom and
+offset included, not from its `pos`, the view's top-left corner (before 20.12
+it was the corner, and everything panned right). Following stops on its own
+when the target is destroyed, which a stage that owns its camera does on every
+state change.
 
 A `Camera3d` target also contributes its **orientation**, taken from its own
 basis, so turning the camera swings the stereo image with it. That is the whole
@@ -380,6 +406,14 @@ a gate screen — a splash, a "press any key", or a health/photosensitivity noti
 unconditionally. Note the unlock listens for `keydown` too, so a keyboard-only
 player is covered.
 
+Where there is no DOM (nx.js on the Nintendo Switch, see `melonjs-deployment`)
+there is no page to gesture at and no autoplay policy: audio unlocks as soon as
+the engine has its context, and music can start on load. nx.js's Web Audio has
+buffer sources, gain and stereo panning, but not the `PannerNode`,
+`OscillatorNode` and `BiquadFilterNode` behind 3D `position()` / `panner()` and
+`tone()` / `noise()`, nor the reverb, echo and compressor nodes: those throw
+"Method not implemented" there.
+
 ### The context can stop again, long after it was unlocked
 
 Unlocking is only the first half. A context that has been running can be
@@ -490,8 +524,9 @@ either way — blank screen, empty console.
 | 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 |
+| `preload()` rejects with `Failed loading resource data/sfx/` (or `audio.load()` throws `target audio extension(s) should be set...`) | `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 |
+| "Method not implemented" from `position()`, `panner()`, `tone()`, `noise()` or an effect, on nx.js | nx.js's Web Audio lacks the node it needs (panner, oscillator, filter, convolver...): use `stereo()` and recorded sounds there |
 | 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 |
@@ -507,11 +542,17 @@ either way — blank screen, empty console.
 | a positioned sound is silent, or only audible right next to the player | placed by hand with `audio.position()`, which keeps WebAudio's metre defaults (`refDistance: 1`) — use `follow` / `at`, or set `refDistance` in pixels with `audio.panner()` |
 | a positioned sound does not follow the player | nothing is placing it — `audio.play(name, { follow: entity })`, and `audio.setListener(player)` once |
 | a followed sound pans to the wrong side as the player moves | the listener was moved **and** positions are still relative to the player — with a listener in the world, pass absolute world coordinates |
-| a looping sound outlives the entity that owns it | `follow` without `stopWithTarget: true` |
+| with `audio.setListener(app.viewport)`, a sound in the middle of the screen is heard off to the right (before 20.12) | the ear was at the camera's top-left corner: update, it is at the center of the view |
+| a followed `Entity` (or Tiled object) sounds offset up and to the left | `follow` uses the anchor point, which is the top-left corner under their `(0, 0)` anchor |
+| a looping sound outlives the entity that owns it | `follow` without `stopWithTarget: true`; with it, before 20.14 a pooled entity going back to its pool did not count either |
+| new sounds are quieter than the volume slider says, or the music stays silent after the volume went to 0 and back (before 20.14) | the global volume was applied twice: update |
+| "Retry" from a pause menu restarts the level with no music (before 20.14) | `playTrack` on a paused track stopped it: update |
+| a clip's load-time `on: { end }` stops firing after `audio.stop(name)` (before 20.14) | `stop(name)` removed it: update |
 | a voice panned with `stereo()` loses its 3D placement, or the reverse | one panner node per voice and last writer wins — pick one per voice and stay with it |
 | a reverb / compressor on the master gain does not affect the music | the music is `stream: true`, which bypasses the master gain — preload it buffered |
 | a looping MP3 drops out for a moment at every loop, in Safari only | Safari keeps the encoder's padding at the end of the file: loop a sprite region of the clip's exact length (see "A loop with no gap") |
 | sound effects keep playing after the window loses focus | `pauseOnBlur` and `stopOnBlur` are both off, so the engine is deliberately leaving the game running in the background |
+| the game still pauses and goes quiet on blur although `pauseOnBlur: false` was passed to `new Application()` | it is not a setting: assign `app.pauseOnBlur = false` |
 
 ## Related skills
 

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

@@ -1,6 +1,6 @@
 ---
 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 what each one draws, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, baking with CanvasRenderTarget, and reading pixels back. Triggers on: Camera2d, viewport, follow, offset, look ahead, setBounds, minimap, second camera, split screen, cullMask, visibilityLayer, hide from a camera, shake, fadeIn, fadeOut, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, setGlobalAlpha, fillArc, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels."
+description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras and what each one draws, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, baking with CanvasRenderTarget, and reading pixels back. Triggers on: Camera2d, viewport, follow, offset, look ahead, setBounds, minimap, second camera, split screen, cullMask, visibilityLayer, hide from a camera, zoom, roll, shake, fadeIn, fadeOut, CameraEffect, addCameraEffect, MaskEffect, PixelateTransitionEffect, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, setGlobalAlpha, fillArc, Rect, Ellipse, Polygon, Line, Path2D, SVG path, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels."
 license: MIT
 ---
 
@@ -109,6 +109,13 @@ The fade pair is named from the *colour's* point of view, not the scene's:
 (screen starts at `color` and clears). Both default to a 1000 ms duration and
 take an optional completion callback.
 
+`shake()` while a shake is still running is ignored, unless its fifth
+argument, `force`, is `true`, which replaces the running one:
+
+```js
+app.viewport.shake(8, 300, app.viewport.AXIS.BOTH, undefined, true);
+```
+
 **`fadeIn` does not HOLD the colour.** The effect completes, the camera's own
 update destroys it, and the screen snaps back — which is why the engine's
 idiom does the work in the completion callback and then calls `fadeOut`. To
@@ -136,6 +143,48 @@ 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.
 
+### The camera effects, and your own
+
+Each is a `CameraEffect`, added with `camera.addCameraEffect(effect)` (which
+returns it), found with `getCameraEffect(Class)` and taken off with
+`removeCameraEffect(effect)`, which destroys it:
+
+| effect | options | what it does |
+|---|---|---|
+| `ShakeEffect` | `intensity`, `duration`, `axis`, `onComplete` | jitters `offset`; what `shake()` adds. Several can run at once this way |
+| `FadeEffect` | `color`, `duration` (1000), `direction: "in" \| "out"`, `onComplete` | what `fadeIn()` / `fadeOut()` add |
+| `MaskEffect` | `shape`, `color`, `duration` (500), `direction: "hide" \| "reveal"`, `onComplete` | an iris or a wipe through a unit-sized `Ellipse` or `Polygon` centred on the origin |
+| `PixelateTransitionEffect` | `renderer`, `size` (32), `duration` (500), `direction: "hide" \| "reveal"`, `onComplete` | the view breaks into blocks up to `size` screen pixels, or comes back from them. A shader: on Canvas it keeps its timing and draws nothing |
+
+`state.transition("fade" | "mask" | "pixelate", …)` drives the last three
+for a state change (see `melonjs-scenes-and-state`). A `Trigger` that loads a
+level transitions only with both a `color` and a `duration`, and takes only
+`transition: "fade"` (the default) or `"mask"` with a `shape`: anything else,
+`"pixelate"` included, is a fade.
+
+For an effect of your own, extend `CameraEffect`: `update(dt)` runs every
+frame (`dt` in ms), `draw(renderer, width, height)` draws over the camera's
+view, and `destroy()` frees what it holds. Set `isComplete = true` and the
+camera's update destroys it that frame, unless it is `isPersistent`.
+
+## Zoom and roll
+
+```js
+app.viewport.zoom = 2;              // above 1 zooms in, below 1 out
+app.viewport.roll = Math.PI / 32;   // a slight dutch angle, in radians
+```
+
+A zoomed camera follows, keeps to its bounds and centres on `focusOn` in world
+units, and `localToWorld` / `worldToLocal` count the zoom. A zoom of 0 or less
+is taken as 1.
+
+`roll` is absolute (assigning the same angle twice changes nothing), and the
+pointer conversions undo it, so picking under a rolled camera needs nothing.
+It OWNS the camera's `currentTransform`: each assignment rebuilds it, so a
+`rotate()` or `scale()` called on the camera itself is lost at the next one.
+`reset()` puts it back to 0. On a `Camera3d` the same `roll` banks the view
+(see below).
+
 ## Coordinate conversion
 
 ```js
@@ -291,8 +340,38 @@ backend, though: Canvas closes it with a straight chord, the GPU renderers fill
 a pie slice from the centre.
 
 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.
+(and a `Bounds`), plus the 3D `Box3d` and `Sphere`, drawn as their footprint
+and their circle on the screen plane. `renderer.fill(shape)` and
+`renderer.stroke(shape)` take any of them and throw `Invalid geometry for
+fill/stroke` for anything else.
+
+### Paths and SVG strings
+
+For any other outline, build a path on the renderer's own `renderer.path2D`,
+then call `fill()` / `stroke()` with no argument:
+
+```js
+renderer.path2D.parseSVGPath("M 50 0 L 100 100 L 0 100 Z");
+renderer.setColor("#4CAF50");
+renderer.fill();
+```
+
+`renderer.path2D` also takes the methods of the browser's `Path2D`
+(`beginPath`, `moveTo`, `lineTo`, `arc`, `arcTo`, `ellipse`, `rect`,
+`roundRect`, `quadraticCurveTo`, `bezierCurveTo`, `closePath`).
+
+- **Every `moveTo`, every `M`, starts a sub-path, and filled, each one after
+  the first is a HOLE**: a donut, the counter of an "O". Wind a hole the
+  opposite way to the outline, as Canvas fills by the non-zero rule, where a
+  hole wound the same way fills in. Draw separate shapes with separate fills.
+- **`parseSVGPath` reads absolute commands only** (`M L H V Q C A Z`). A
+  lowercase, relative command is read as its absolute twin, so a path
+  exported with relative commands comes out scrambled, and `H` / `V` take an
+  OFFSET from the pen, not the coordinate SVG means. Export absolute
+  coordinates.
+- **The engine's `Path2D` class is not exported.** `new Path2D()` in a game is
+  the browser's own, which `fill()` / `stroke()` refuse as invalid geometry:
+  use `renderer.path2D`.
 
 `Gradient` gives linear and radial fills, built with
 `renderer.createLinearGradient(x0, y0, x1, y1)` /
@@ -353,10 +432,11 @@ drawable, and the engine's own bakes (the particle emitter's default texture)
 hand `.canvas` on for exactly that reason.
 
 **Create it once and keep it.** On a GPU backend, once drawn, its texture stays
-on the GPU for as long as the renderer lives: a stage change does not release
-it, and no public call does. A target made for every level, every restart or
-every spawned object leaks one texture each time, so make it once (at module
-level, say) and clear it for reuse. If you paint into it again after it has
+on the GPU until `rt.destroy(renderer)` frees it: a stage change does not, and
+`destroy()` without the renderer frees the canvas but not that copy. A target
+made for every level, every restart or every spawned object and never
+destroyed leaks one texture each time, so make it once (at module level, say)
+and clear it for reuse. If you paint into it again after it has
 been drawn, call `rt.invalidate(renderer)` before the next draw so the GPU copy
 is refreshed.
 
@@ -435,7 +515,14 @@ const data = await rt.toImageData(0, 0, w, h);
 | baked target draws nothing / throws | passed the `CanvasRenderTarget`, not its `.canvas` |
 | `getImageData()` throws on one machine but not another | that one is on the WebGPU renderer, which cannot read back synchronously — `await toImageData()` instead |
 | frame rate drops with many static draws | bake into a `CanvasRenderTarget` instead |
-| GPU memory grows with every level or restart | a `CanvasRenderTarget` created each time: make one and reuse it |
+| GPU memory grows with every level or restart | a `CanvasRenderTarget` created each time: make one and reuse it, or `destroy(renderer)` the old one |
+| a second `shake()` does nothing | one is still running: pass `force` (the fifth argument) to replace it |
+| a `Trigger` with `transition: "pixelate"` fades instead | a trigger takes only `"fade"` or `"mask"`; add a `PixelateTransitionEffect` yourself |
+| a `Trigger` loads its level with no transition | it needs both `color` and `duration` |
+| a `rotate()` or `scale()` on the camera is lost | `roll` owns the camera's `currentTransform` and rebuilds it; use `roll` and `zoom` |
+| an SVG path from an editor comes out scrambled | `parseSVGPath` reads absolute commands only, and `H` / `V` as offsets |
+| a hole in a path fills in, on Canvas only | it is wound the same way as the outline; wind it the opposite way |
+| `fill(new Path2D(...))` throws `Invalid geometry for fill/stroke` | that is the browser's `Path2D`; build on `renderer.path2D` and call `fill()` |
 | a repainted `CanvasRenderTarget` still shows the old pixels | call `rt.invalidate(renderer)` after painting |
 | a 3D camera cannot be given an arbitrary up | `Camera3d#lookAt(target, up)` or `setBasis(right, up, forward)`; see `melonjs-3d` |
 | particles or effects clutter a minimap | every camera draws everything: put them on their own `visibilityLayer` and leave it out of the minimap's `cullMask` |

package/skills/melonjs-deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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, running with no DOM (nx.js on the Nintendo Switch, a Web Worker), browser support and transpiling. Triggers on: create-melonjs, scaffold, new project, build, deploy, publish, Capacitor, Cordova, native app, iOS, Android, WeChat, Instant Games, nx.js, Nintendo Switch, homebrew, no DOM, Web Worker, OffscreenCanvas, browser support, transpile, ES2022, bundle size, tree-shaking."
 license: MIT
 ---
 
@@ -15,9 +15,11 @@ 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.
+exits — and it names a new directory: an existing one is refused. 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. Then `npm install` and
+`npm run dev` in that directory.
 
 ## Adding melonJS to an existing project
 
@@ -69,14 +71,22 @@ Two caveats worth knowing:
 
 ## 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.
+**Capacitor** is the current recommendation for iOS and Android. A melonJS game
+runs in its WebView unchanged; `@melonjs/capacitor-plugin` adds the native
+lifecycle: the game pauses when the app goes to the background and resumes when
+it comes back (but stays paused if the player had paused it, from 1.0.1), the
+hardware back button reaches the current stage (`bindStageBack`), and
+orientation lock and the splash screen are one call each. The boilerplate's
+Vite build writes to `dist/`, Capacitor's default `webDir`. See
+`melonjs-plugins` for its options. **Cordova** also works and is documented,
+but is the older route.
+
+The thing that breaks first under Cordova 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. Capacitor serves the app from a local web
+server instead (`https://localhost` on Android, `capacitor://localhost` on
+iOS), so `fetch()` works there.
 
 ## Mini-game platforms
 
@@ -85,7 +95,67 @@ 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.
+the runtime's adapter provides one, instead of creating its own. What the engine
+does without a DOM is described in the next section.
+
+## Runtimes with no DOM: nx.js, Web Workers
+
+melonJS (from 20.14) runs where there is no `document`: in a Web Worker, and in
+runtimes that implement the web APIs a game uses but no page around it, such as
+[nx.js](https://github.com/TooTallNate/nx.js), JavaScript homebrew for the
+Nintendo Switch. There is no `<canvas>` to create there, so hand the
+Application the canvas to draw to. On nx.js that is the global `screen`, the
+1280x720 display:
+
+```js
+import { Application, video } from "melonjs";
+
+const app = new Application(1280, 720, {
+    canvas: screen,          // nx.js's display; an OffscreenCanvas in a worker
+    renderer: video.AUTO,    // WebGL 2 where the runtime has it, else Canvas
+    scale: 1,
+});
+await app.init();
+```
+
+What changes without a DOM:
+
+- **Design at the canvas's size.** There is no page to fit, so
+  `scale: "auto"` measures nothing and the game is drawn at the scale it was
+  given. On the Switch that is 1280x720 (the console scales it when docked).
+- `app.parentElement` is `undefined`: the canvas is the display and is not
+  attached to anything. Fullscreen and pointer lock do nothing.
+- **Assets** load through `fetch` and `createImageBitmap` as in a browser; on
+  nx.js a relative path resolves inside the app's RomFS. Tiled maps must be
+  **JSON** (`.tmj` / `.tsj`): XML needs `DOMParser` (see `melonjs-tilemaps`).
+  The `video` and `script` asset types need a DOM and fail.
+- **Input**: touch arrives as `TouchEvent`s on the canvas, and melonJS reports
+  them as pointer events as usual. There is no mouse. On nx.js the Joy-Con are
+  standard gamepads (`melonjs-input`), and keyboard events only come from a
+  USB keyboard.
+- **Audio** needs no gesture to unlock. nx.js cannot say which formats it
+  decodes (its `Audio` has no `canPlayType`), so melonJS tries the first
+  extension given to `audio.init()`: list one FFmpeg decodes, such as
+  `audio.init("ogg,mp3")`. nx.js's Web Audio has no `PannerNode`,
+  `OscillatorNode`, `BiquadFilterNode` or effect nodes, so plain playback,
+  volume and `stereo()` work, but 3D `position()` / `panner()`, `tone()` /
+  `noise()` and the reverb / echo / compressor effects throw there (see
+  `melonjs-audio`).
+- **Fonts**: nx.js's `FontFace` only takes the font's bytes, so a `fontface`
+  asset (a URL) fails there. Load the bytes yourself and add the face before
+  using it in a `Text`. The face is ready once made, and its `load()` throws
+  on nx.js, so do not call it:
+  `fonts.add(new FontFace("Pixel", await (await fetch("font.ttf")).arrayBuffer()))`.
+- **Save data**: melonJS checks `localStorage` when it loads. On nx.js, if the
+  app declares user save data (`userAccountSaveDataSize` in its NACP), that
+  first read is when the Switch asks the player to pick a user profile. An app
+  that saves nothing should leave that size at 0, so no picker appears.
+- A Web Worker has no `Image`, `Audio` or `AudioContext` of its own: draw
+  there, and play sound from the page.
+
+The engine's own test, `tests/nxjs-compatibility.spec.js`, runs a game in a
+Web Worker made to look like nx.js. It is the reference for what is expected
+to work, not a test on Switch hardware.
 
 ## Size
 
@@ -103,11 +173,19 @@ are not decoded into memory.
 |---|---|
 | 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 |
+| assets 404 in a packaged Cordova 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 |
+| a native app paused from its menu is running again after coming back from the background | capacitor-plugin < 1.0.1 resumed on every return; upgrade |
+| `Cannot read properties of undefined (reading 'body')` from `new Application` in nx.js or a Web Worker | melonJS older than 20.14, which needed a DOM; update |
+| WebGL 2 "could not be created" on nx.js | another context was taken on `screen` first: it holds one context kind, so let the Application be the first to call `getContext` on it |
+| the game is drawn small, or cropped, on nx.js | its resolution is not the screen's 1280x720; with no page, `scale: "auto"` does not fit it |
+| an XML Tiled map fails with "needs DOMParser" | no DOM to parse XML with: export the map and its tilesets as JSON (`.tmj` / `.tsj`) |
+| a `fontface` asset fails on nx.js | nx.js's `FontFace` takes bytes, not a URL: fetch the file and add the face to `fonts` yourself |
+| spatial sound, `tone()` or `noise()` throws "Method not implemented" on nx.js | the node it needs is missing from nx.js's Web Audio; use `stereo()` and recorded sounds |
 
 ## Related skills
 
 - `melonjs` — the companion packages, including the Capacitor plugin
+- `melonjs-plugins` — registering the Capacitor plugin, and its helpers
 - `melonjs-getting-started` — the Application bootstrap the template produces

package/skills/melonjs-display-and-scaling/SKILL.md

@@ -39,8 +39,11 @@ the usual arrangement: author once, scale to whatever you are given.
 
 ## `scale` and `scaleMethod`
 
-`scale: "auto"` turns on automatic scaling; a number is a fixed multiplier and
-`scaleMethod` is then ignored.
+`scale: "auto"` turns on automatic scaling, and so does naming any
+`scaleMethod` other than `"manual"`, even with no `scale` given:
+`{ scaleMethod: "flex" }` alone scales to its container. A number is a fixed
+multiplier, used only while `scaleMethod` is `"manual"` (the default); with
+automatic scaling on, the number is ignored.
 
 `scaleMethod` decides how the available space is used:
 
@@ -54,7 +57,8 @@ the usual arrangement: author once, scale to whatever you are given.
   both axes.
 - **`"stretch"`** scales each axis independently, so the aspect ratio is not
   preserved and circles become ovals.
-- **`"manual"`** does nothing automatic.
+- **`"manual"`**, the default, does nothing automatic with a numeric `scale`.
+  With `scale: "auto"` it scales as `"fit"` does.
 
 The distinction that matters: **`fit` scales a fixed frame; everything else
 changes how much of the world is visible.** A game whose layout assumes a
@@ -381,3 +385,4 @@ const app = new Application(1024, 576, {
 | `scaleRounding: "integer"` changes nothing | it applies to `scaleMethod: "fit"` only; the others resize the renderer |
 | text is soft but sprites are crisp | the glyphs were anti-aliased when `Text` baked them; use `BitmapText` (see below) |
 | the game shows more world on a bigger window | that is `fill-*` or `flex-*` doing their job; use `"fit"` to keep a fixed frame |
+| a numeric `scale` (say `2`) is ignored | a `scaleMethod` other than `"manual"` turns automatic scaling on, which ignores the number |

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

@@ -1,6 +1,6 @@
 ---
 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: Tween, easing, animate an effect, ShaderEffect, addPostEffect, removePostEffect, getPostEffect, postEffectNeedsCapture, VignetteEffect, GlowEffect, BlurEffect, PixelateEffect, ScanlineEffect, shader, GLSL, WGSL, uniform, setUniform, setTexture, setTime, blendMode, colorMatrix, screen_texture, toFrameTexture, post effect, filter."
+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: Tween, easing, animate an effect, ShaderEffect, addPostEffect, removePostEffect, getPostEffect, postEffectNeedsCapture, VignetteEffect, GlowEffect, BlurEffect, PixelateEffect, ScanlineEffect, OutlineEffect, BloomEffect, ToneMappingEffect, SwayEffect, SquishEffect, hdr, tone mapping, shader, GLSL, WGSL, uniform, setUniform, setTexture, setTime, getShader, prewarm, blendMode, colorMatrix, screen_texture, screen_uv, noise_uv, toFrameTexture, pixelate transition, post effect, filter."
 license: MIT
 ---
 
@@ -88,8 +88,9 @@ class Bar extends Renderable {
 }
 ```
 
-`ProgressBar` and `Trail` set it for you, and a sprite needs nothing: the flag
-defaults to `false` and only ever changes the single-effect case.
+`ProgressBar`, `UIPanel` and `Trail` set it for you, and a sprite needs
+nothing: the flag defaults to `false` and only ever changes the single-effect
+case.
 
 ## Toggle with `enabled`, do not remove
 
@@ -229,7 +230,8 @@ squish.setBulge(1 - scaleY);
 ```
 
 Apply that from the sprite's own `update()`, not from a tween's `onUpdate`. A
-physics adapter that mirrors a body's angle (Matter does) rewrites
+physics adapter that mirrors a body's angle (matter, planck and Rapier do, and so does
+the built-in once a body has an angle or angular velocity) rewrites
 `currentTransform` on every step, before the renderables update, so a scale set
 anywhere else is gone by the time the sprite is drawn. Let the tween animate a
 plain `{ scaleY }` object and read it in `update()`.
@@ -457,8 +459,10 @@ renderer.setToneMapping("aces", { exposure: 0.4, white: 6 });
 renderer.setToneMapping("none");                       // and off again
 ```
 
-`"none"` by default. The renderer keeps the curve LAST on the camera, so
-whatever you put in front of it is mapped along with everything else. Changing
+`"none"` by default, and set at boot through the `toneMapping`,
+`toneMappingExposure` and `toneMappingWhite` application settings. The
+renderer keeps the curve LAST on the camera, so whatever you put in front of
+it is mapped along with everything else. Changing
 the mode rebuilds one shader (the curve is baked); `exposure` and `white` are
 uniform writes, so a settings screen can drive them live. `white` is the value
 that comes out as display white — the knob a "brightness" or "peak" slider
@@ -483,6 +487,13 @@ 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.
 
+The `"pixelate"` state transition (`state.transition("pixelate", …)`, or a
+`PixelateTransitionEffect` added with `addCameraEffect`) is another such guest:
+while it runs it puts a `PixelateEffect` FIRST in the camera's chain, so a
+vignette or scanlines you added stay sharp over the blocks, and it takes the
+effect off again when it is done. Being a shader, it does nothing on Canvas,
+where `state.transition` changes the state directly instead.
+
 ## Custom effects are dual-language
 
 A custom `ShaderEffect` supplies a fragment **body**, not a whole program. To run
@@ -582,8 +593,8 @@ string in your own module:
 
 ```js
 // with the level's other assets, not in the stage that uses them.
-// `preload()` rather than `load()` — preload is what warms the shaders it
-// brought in, and it can be called again per level, not just at boot
+// `preload()` or a bundle's `load(id)`, not `load(asset)`: those two warm
+// the shaders they bring in, and run again per level, not just at boot
 await loader.preload([
     { name: "ripples", type: "shader", src: {
         glsl: "assets/level2/ripples.glsl",
@@ -596,6 +607,14 @@ await loader.preload([
 `src` takes the dual-language pair, so one asset carries both realizations and
 the two backends cannot drift apart. `data` takes inline source the same way.
 
+A level's bundle (20.14: `loader.load("level2", [...])` declares and loads
+one, warming like `preload` but with no loading screen) is also the shader's
+lifetime. Unloading the last bundle that lists it, or `loader.unload()` of the
+shader asset itself, destroys the shared instance whatever still draws with
+it, and those renderables then draw without the effect. An effect that
+outlives a level (a HUD's, a camera's) belongs in a bundle that outlives it
+too; see `melonjs-loading-assets`.
+
 With `prewarm` on (the default since 20.6), `loader.preload()` warms on its way
 through — automatically, on every call — and compiles the GPU-side objects for
 every shader it holds — on WebGPU that is the
@@ -632,7 +651,9 @@ variants are covered by the loading-screen warm-up and by the per-renderable one
 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;`)
+  (GLSL: annotate the sampler `uniform sampler2D tex : screen_texture;`, or
+  `: screen_texture(repeat)` to sample it wrapping; `repeat-x` and
+  `repeat-y` work too)
 - **`screen_uv`** — this fragment's 0..1 position in that capture
 - **`noise_uv`** — 0..1 across the sprite regardless of its atlas frame, and
   across the renderable when it has several effects (it does not slide with
@@ -650,7 +671,11 @@ Two places where a straight port really does differ:
   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.
+  must *not* flip) and preserves alpha. It holds what was drawn when it was
+  called, so call it right before the draw that samples it. By default it
+  refills one shared, renderer-owned texture; `toFrameTexture({ target: null })`
+  hands back a capture of your own, for two alive at once, which you
+  `destroy()` when done.
 - **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
@@ -724,10 +749,14 @@ capture plus one composite **per draw**: `difference`, `overlay`, `hard-light`,
 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.
+Anything else collapses to `"normal"`. `renderer.setBlendMode(mode)` returns
+the mode it actually applied, so comparing that against your request detects
+an unknown name, and `none` on Canvas.
+
+Two kinds of draw cannot take the eight composited modes on the GPU backends:
+a 3D mesh and a `Gradient` fill draw them as `"normal"`, with a one-time
+console warning naming which. `setBlendMode` cannot see that one, since it
+happens at the draw, and still reports the mode you asked for.
 
 ## The Canvas fallback
 
@@ -767,9 +796,11 @@ same question after construction.
 | 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 |
+| `overlay` (or another composited mode) does nothing on a mesh or a gradient fill, with a console warning | those two draws take the eight composited modes as `"normal"` on the GPU backends |
+| an effect from `loader.getShader()` stops drawing after a level change | its asset, or the last bundle listing it, was unloaded, which destroys the shared instance |
 | many sprites with the same effect still cost a draw each | an effect instance per sprite, or a uniform set to a different value per sprite — share one instance and group sprites by value |
 | animated shader never moves | `setTime` fed milliseconds, or the shader declares no `uTime` |
-| squash and stretch only bulges, the height never changes, under Matter | the adapter rewrites `currentTransform` every step; set the scale from the sprite's `update()` |
+| squash and stretch only bulges, the height never changes, under matter, planck or Rapier (or a rotating built-in body) | the adapter rewrites `currentTransform` every step; set the scale from the sprite's `update()` |
 | `SquishEffect` squishes the whole screen instead of the sprite | it is chained with another effect, or on the camera; give the sprite it alone |
 | syntax error in a file whose shader you just edited, pointing at a line of GLSL | a backtick in the shader body ended the template literal — most often one wrapped around an identifier in a comment |
 

package/skills/melonjs-events/SKILL.md

@@ -55,7 +55,7 @@ game events in a `.ts` project.
 | 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 |
+| `GAME_BEFORE_DRAW` / `GAME_AFTER_DRAW` | around the draw pass, on frames that redraw: one where no update reported a change is not drawn |
 | `WORLD_STEP` | after the physics step |
 | `TICK` | the raw engine tick |
 
@@ -67,7 +67,7 @@ game events in a `.ts` project.
 | `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 |
+| `LOADER_PROGRESS`, `LOADER_COMPLETE`, `LOADER_ERROR` | asset loading: every `loader.preload()`, and a bundle loaded with `loader.load(id)` (20.14); not one asset loaded with `loader.load(descriptor)` |
 | `BLUR` / `FOCUS` | the page lost or regained focus |
 | `CANVAS_ONRESIZE`, `VIEWPORT_ONRESIZE` | relayout hooks |
 | `POINTERMOVE` | global pointer movement |
@@ -153,6 +153,7 @@ Use `removeChild()`, or flag the work and drain it from `Stage.update`.
 | crash during a stage switch | callback ran mid-teardown — guard with `state.isCurrent` |
 | crash after a collision | `removeChildNow()` inside a contact callback — use `removeChild()` |
 | progress callbacks never fire | assigned `loader.onProgress` (removed in 20.3) instead of subscribing to `LOADER_PROGRESS` |
+| a `LOADER_COMPLETE` handler (a `state.change` to the first screen) runs again mid-game | a later `preload()`, or a level's bundle loaded with `loader.load(id)`, emits it too; subscribe with `event.once`, or use `preload()`'s promise or callback |
 | `onActivateEvent` never runs | the child was added to a container not yet attached to the world |
 | `onDeactivateEvent` runs twice when a group is removed (a count goes negative, a light or listener is released twice) | the group's `onDeactivateEvent` and its `destroy()` both reached the children, before 20.13.0 — now once per `onActivateEvent` |
 | `onDeactivateEvent` never runs on a child of a group built off-world and destroyed | it never had `onActivateEvent` either: the pair is only sent to children that entered the world |