melonjs 20.12.0 → 20.14.0

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
 
@@ -758,6 +787,7 @@ same question after construction.
 
 | symptom | cause |
 |---|---|
+| a camera's post effect hides another camera drawn before it | before 20.13 a later camera's pass replaced the whole frame; update. Since then each camera's effects apply to what it draws, over the cameras before it |
 | 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 |
@@ -766,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 |
@@ -87,7 +87,7 @@ 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 |
+| `onDeactivateEvent()` | removed from its container — including the automatic world clear on a state change. Once per `onActivateEvent`: the children of a removed container, at any depth, are told once |
 | `onDestroyEvent()` | `destroy()` ran; called with no arguments from the container-removal path |
 | `onCollisionStart` / `onCollisionActive` / `onCollisionEnd` | contacts |
 
@@ -153,7 +153,10 @@ 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 |
 
 ## Related skills
 

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

@@ -137,7 +137,6 @@ 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" },
@@ -145,6 +144,11 @@ await loader.preload([
 ]);
 ```
 
+A flat list suits a single-screen game. A game with several levels exports a
+record of bundles instead — `{ common: [...], level1: [...], level2: [...] }`,
+passed to the same `loader.preload()` — so each level's assets can later be
+freed and loaded again by id; see `melonjs-loading-assets`.
+
 Two ordering rules that produce confusing failures when missed:
 
 - **`audio.init()` must run before any audio asset is preloaded**, and names the
@@ -173,7 +177,7 @@ placement.
 | 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" })` |
+| an asset on another origin fails to load, the error naming it | that server sends no `Access-Control-Allow-Origin` header (see melonjs-loading-assets) |
 
 ## Related skills
 

package/skills/melonjs-input/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-input
-description: "Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, which of several overlapping objects receives an event and how to consume it, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, pointermove, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, virtual gamepad, touch controls, joystick, gamepad-plugin, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click."
+description: "Use this skill for keyboard, pointer, mouse, touch and gamepad input in melonJS. Covers the bindKey action indirection, registerPointerEvent on regions, the isKinematic requirement that silently blocks pointer events, which of several overlapping objects receives an event and how to consume it, world vs screen pointer coordinates, and gamepad mapping onto the same actions. Triggers on: input, bindKey, isKeyPressed, KEY, bindPointer, mouse button, vibrateGamepad, rumble, activeGamepad, registerPointerEvent, releasePointerEvent, pointerdown, pointerup, pointermove, POINTERMOVE, gamepad, bindGamepad, triggerKeyEvent, virtual gamepad, touch controls, joystick, gamepad-plugin, floating stick, floating button, floating joystick, two thumbs, tap to fire, hideAtRest, mobile controls, KEYDOWN, KEYUP, press any key, splash screen, click, touch, drag, hit test, event propagation, stop propagating, overlapping, which object gets the click."
 license: MIT
 ---
 
@@ -54,12 +54,37 @@ narrows it; it also repeats while the key is held, so guard anything that must
 happen once. Keep polling for movement and for a menu cursor, where one step
 per press and a key held across a state change are the things that matter.
 
+When the window loses the focus or the page is hidden, every key and
+`bindPointer` button still held is released, since its real release goes to
+another window: polling sees it up when the player comes back, and a key still
+held then is pressed again by its next `keydown`. No `KEYUP` is sent for it,
+so code moved by `KEYDOWN` / `KEYUP` rather than by polling should also listen
+to `event.BLUR`. A gamepad's presses are left to the gamepad, which is read
+every frame.
+
 The full signature is `bindKey(keyCode, action, lock?, preventDefault?)`;
 `preventDefault` defaults to `input.preventDefault` (itself `true`). Pass the
 fourth argument per binding, or change the global default with
 `input.setPreventDefault(false)` — **assigning `input.preventDefault = false`
 does not work**, it is a read-only module binding.
 
+### A mouse button as a key
+
+`bindPointer` makes a mouse button press a bound key, so a click fires the same
+action and `isKeyPressed` sees it:
+
+```js
+input.bindKey(input.KEY.X, "fire");
+input.bindPointer(input.KEY.X);                       // the left button
+input.bindPointer(input.pointer.RIGHT, input.KEY.X);  // or another button
+input.unbindPointer(input.pointer.RIGHT);             // LEFT when omitted
+```
+
+As with `bindGamepad`, the key needs its `bindKey` first, or `bindPointer`
+throws `no action defined for keycode N`. Turning the wheel neither presses
+nor releases a bound button's key (before 20.14 it released the left
+button's).
+
 ## Pointer events need `isKinematic = false`
 
 **This is the trap.** `Renderable.isKinematic` defaults to `true`, and both the
@@ -82,9 +107,11 @@ class Button extends Renderable {
 ```
 
 `Container`, `Camera2d`, `Draggable`, `DropTarget` and the `UI*` elements set it
-to `false` for you, and so does attaching a physics body (`Body`'s constructor
-sets `ancestor.isKinematic = false`) — so plain `Renderable` and `Sprite`
-subclasses with no body are the ones that catch people.
+to `false` for you, and so does giving it a physics body (a `bodyDef` on any
+adapter, or a `Body`) — so plain `Renderable` and `Sprite` subclasses with no
+body are the ones that catch people. Before melonJS 20.14, matter-adapter
+1.6.0 and planck-adapter 1.7.0, a `bodyDef` under matter or planck left
+`isKinematic` at `true`, so set it yourself there.
 
 Register in `onActivateEvent` and release in `onDeactivateEvent`, not in the
 constructor — pooled objects are reused and would otherwise accumulate handlers.
@@ -103,6 +130,11 @@ throw `invalid event type`. melonJS maps the canonical name onto whichever
 mouse/touch events the device actually supports, so you always register the
 pointer name.
 
+A region can listen to `"pointerup"` alone, to act on release: it gets the
+release of a press made on it. With several fingers on one region, each finger
+that pressed it gets its own `pointerup` / `pointercancel`; `pointerenter` and
+`pointerleave` still follow one pointer per region.
+
 ## Which object gets the event
 
 The dispatcher collects the regions near the pointer from the broadphase,
@@ -182,9 +214,10 @@ globalThis.addEventListener("pointerup", onRelease);
 
 For plain drag-and-drop, `Draggable` / `DropTarget` already wire all of this up
 (`pointerdown` / `pointerup` / `pointercancel` regions plus a global
-`POINTERMOVE` listener) and emit `event.DRAGSTART` / `event.DRAGEND`. `DRAGEND`
-still originates from a region handler, so it only fires when the release lands
-on the draggable itself.
+`POINTERMOVE` listener) and emit `event.DRAGSTART` / `event.DRAGEND`, and
+follow the pointer under any camera, scrolled or zoomed. `DRAGEND` still
+originates from a region handler, so it only fires when the release lands on
+the draggable itself.
 
 ## Gamepad
 
@@ -252,10 +285,10 @@ input.hasGamepadVibration(index);    // for an options-screen toggle
 
 Safe to call blind: no pad, no motors, or no Gamepad API at all resolves
 `false` and does nothing, so game code never branches on support. Magnitudes
-default to **full** — the underlying web API defaults every parameter to zero,
-which makes a bare `playEffect` a silent no-op. A second call preempts the
-first on the same pad, so a rapid series of hits reads as a rapid series of
-hits rather than as a queue. For a SUSTAINED rumble issue one effect with a
+default to **full** and `duration` to 200 ms — the underlying web API defaults
+every parameter to zero, which makes a bare `playEffect` a silent no-op. A
+second call preempts the first on the same pad, so a rapid series of hits
+reads as a rapid series of hits rather than as a queue. For a SUSTAINED rumble issue one effect with a
 long `duration` instead of calling every frame.
 
 Hot-plugging needs no polling of your own — the engine listens for the browser's
@@ -270,12 +303,15 @@ event.on(event.GAMEPAD_DISCONNECTED, (gamepad) => { /* pause, show a prompt */ }
 
 Bindings survive a disconnect: they are attached to the index, not to the
 device, so a pad unplugged and plugged back into the same slot keeps working.
+A pad unplugged with a button or the stick held lets go of the keys bound to
+them, as releasing them would.
 
 ## Virtual controls
 
-For on-screen touch controls, use `@melonjs/gamepad-plugin` rather than
-writing them: sticks and buttons drawn over the game and reported as a pad in
-a gamepad slot, so the `bindGamepad` bindings above answer to them unchanged.
+For on-screen touch controls, use `@melonjs/gamepad-plugin` (it needs melonJS
+20.12 or later) rather than writing them: sticks and buttons drawn over the
+game and reported as a pad in a gamepad slot, so the `bindGamepad` bindings
+above answer to them unchanged.
 
 ```js
 import { GamepadPlugin } from "@melonjs/gamepad-plugin";
@@ -293,6 +329,45 @@ its own, a touch starting on the controls does not reach the game, and they
 hide while a real pad is in use. `plugin.cache.gamepad.visible` says whether
 they show, to word a prompt ("tap" or a key name).
 
+Sticks and buttons are fixed in a corner by default. **`floating: true`**
+puts one under the finger wherever it lands inside its `area` (`"half"`, its
+own half of the screen, by default; `"screen"`; or `{ x, y, width, height }`),
+and **`hideAtRest: true`** draws it only while held. The usual mobile
+two-thumb layout, nothing on screen until touched (1.1):
+
+```js
+plugin.register(GamepadPlugin, "gamepad", {
+    sticks: [{ floating: true, hideAtRest: true }],                 // left half
+    buttons: [{ floating: true, hideAtRest: true, label: "A" }],    // right half
+});
+```
+
+Or one thumb for both: a stick over the whole screen whose quick tap (lifted
+within `tap.time`, 250 ms, without leaning to `dpadThreshold`) presses a key
+or button for one frame, and no button at all:
+
+```js
+plugin.register(GamepadPlugin, "gamepad", {
+    sticks: [{ floating: true, area: "screen", hideAtRest: true,
+               tap: { key: input.KEY.SPACE } }],
+    buttons: 0,
+});
+```
+
+Where areas overlap, a finger takes the first free control there: fixed
+buttons, fixed sticks, floating buttons, floating sticks. So a floating button
+on its `"half"` carves the right half out of a `"screen"` stick, and several
+floating buttons sharing an area split it by distance to where each rests.
+Every press lasts at least one frame, so a 15 ms thumb tap still reaches
+`isKeyPressed`, and Safari's pinch gesture is cancelled while the controls
+show, so a second thumb works on iOS.
+
+To match the game's artwork (1.2), pass an already-loaded `TextureAtlas` as
+`skin` to `GamepadPlugin`, with `base` / `thumb` region names on sticks
+and `region` / optional `pressed` names on buttons. Omitted parts keep
+their shapes. Regions scale to the controls' sizes without changing hit areas;
+labels, floating controls, opacity, hiding and dimming keep working.
+
 A single key can also be pressed directly, reaching the same actions:
 
 ```js
@@ -305,17 +380,28 @@ input.triggerKeyEvent(input.KEY.LEFT, false);   // release
 | symptom | cause |
 |---|---|
 | pointer handler never fires | `isKinematic` left at its `true` default |
+| touches never arrive where there is no DOM (nx.js, a Web Worker) | melonJS older than 20.14 listened for mouse events there; update. Touch is then read from `TouchEvent`s dispatched on the canvas given as `settings.canvas` |
 | handlers fire twice, or on dead objects | registered in the constructor instead of `onActivateEvent` |
 | camera drag jumps around | using world coordinates instead of `gameScreenX`/`gameScreenY` |
 | `gameX` holds screen coords where world coords were expected | read on `event.POINTERMOVE`, or on a floating region — use `gameWorldX`/`gameWorldY` |
 | drag stops when leaving the object | region events end at the region — use `event.POINTERMOVE` |
 | release never detected outside the region | no global pointer-up event — add a raw listener |
 | jump fires every frame while held | `bindKey` without its third `lock` argument |
+| the hero keeps walking after an Alt-Tab, until the key is pressed again (before 20.14) | the key's release went to another window: update, held keys are now released on blur |
+| a region with only a `"pointerup"` callback never gets it, or the first finger's release is lost with two on one region (before 20.14) | the release was only delivered to the last pointer to press the region: update |
+| a key bound with `bindPointer` never fires once the mouse has entered the canvas (before 20.12) | the pointer's button bindings were replaced on each event: update |
+| firing (a key bound with `bindPointer`) stops while the button is held and the wheel turns (before 20.14) | a wheel event released the main button's key: update |
+| clicks land off target after browser zoom or a move to another screen (before 20.14) | the pointer was scaled by the live pixel ratio against a canvas sized with the old one: update |
+| a `Draggable` jumps away when grabbed, and stays stuck dragging, once the camera has moved (before 20.14) | it mixed screen and world coordinates: update |
 | `invalid event type` thrown at registration | non-pointer name (`"click"`, `"mousedown"`, …) passed to `registerPointerEvent` |
-| `no action defined for keycode N` | `bindGamepad` called before `bindKey` for that keycode |
+| `no action defined for keycode N` | `bindGamepad` or `bindPointer` called before `bindKey` for that keycode |
+| floating stick ignores the right half of the screen | its `area` defaults to `"half"`, its own side — use `area: "screen"` |
+| `area: "screen"` stick still ignores part of the screen | a floating button's area comes first there — the overlap order is fixed buttons, fixed sticks, floating buttons, floating sticks |
+| a quick tap on a stick moves instead of acting | it leaned past `dpadThreshold` or outlasted `tap.time` before lifting |
 | stick has to be pushed well past its `threshold` before it registers | `threshold` is ADDED to the deadzone, not used instead of it |
 | one half of a stick does nothing | each half is a separate `bindGamepad`, chosen by the sign of `threshold` |
-| a widget under an overlapping panel still reacts | the panel consumes nothing — return `false` from its `onClick` and `onOver` |
+| a key stays pressed after its pad is unplugged, or a stick bound on one side holds its key after coming back to the centre (before 20.12) | update: an unplugged pad lets go of what it held, and a stick lets go when it returns to rest, even just past the centre |
+| a widget under an overlapping panel still lights up | the panel consumes no hover: return `false` from its `onOver` (presses already stop at UI elements; `UIPanel` with `blocking` does both) |
 | a widget stays highlighted after the pointer moves onto a panel over it | the panel consumes no `pointermove`, so nothing takes the pointer off the widget |
 | a child's big `z` does not put it in front of another container | `pos.z` is container-local — use `ancestor.moveToTop()` on the container |
 | every click in the game stops working | a handler on `app.viewport` returning `false`, which is asked first |

package/skills/melonjs-lighting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-lighting
-description: "Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
+description: "Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, softness, soft light, lightHeight, setRadii, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
 license: MIT
 ---
 
@@ -31,6 +31,11 @@ intensity = 0.7)`, and `pos` is the light's **centre** — its `anchorPoint` is
 `(0.5, 0.5)`, and `centerX` / `centerY` are overridden to return `pos` directly.
 Give `radiusY` a different value for a stretched, elliptical light.
 
+Resize a light with `light.setRadii(radiusX, radiusY)`, which resizes its
+bounds too. Writing `radiusX` alone changes nothing you can see: the glow, the
+hole in the darkness and the normal-map shading are all sized from the bounds,
+on every backend.
+
 A `Light2d` added to the world **registers itself with the stage's ambient
 overlay on activate**, so you add it like any other renderable and it takes part
 in the lighting pass. It draws additively (`blendMode = "lighter"`); set
@@ -105,6 +110,11 @@ const hero = new Sprite(x, y, {
 canvas, `ImageBitmap`, a `Texture2d`). Assigning anything else — including an
 `HTMLVideoElement`, which would freeze on frame 0 — throws a `TypeError`.
 
+How grazing the light is comes from `light.lightHeight`, its height above the
+sprite plane in the same units as its radius (default `max(radiusX, radiusY) *
+0.075`). Lower it for light raking across the surface, which shows the relief
+off; raise it for flatter, more even shading.
+
 Normal maps are typically authored in **SpriteIlluminator**. The sidecar pattern
 above — one `_n` image beside each diffuse image — is the simplest setup, but an
 atlas can carry one too: `new TextureAtlas(json, image, { normalMap })` pairs a
@@ -209,6 +219,8 @@ See the `melonjs-3d` skill.
 | sprite not shaded by a light, only glowed over | no `normalMap` on the sprite, or the Canvas backend is active |
 | normal-mapped sprite is pure black where unlit | `Stage.ambientLightingColor` left at black |
 | the 33rd light shades nothing | `MAX_LIGHTS = 32` for the normal-map pipeline |
+| changing `radiusX` / `radiusY` does nothing | everything is sized from the bounds, which `setRadii()` updates and a bare field write does not |
+| normal-mapped relief looks flat under a light | `lightHeight` is high relative to the radius; lower it for a grazing light |
 | `TypeError` assigning `normalMap` | not an image-like value (a video element is rejected outright) |
 | lighting misaligned under a 3D camera | the 2D light pass is not projection-aware — use `Light3d` |