melonjs 20.12.0 → 20.14.0

package/skills/melonjs-3d-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-3d-assets
-description: "Use this skill when loading 3D models into melonJS — glTF and GLB scenes, OBJ/MTL models, materials, imported lights, node animation, ground shadows and GPU instancing. Covers level.load options including the async flag, the rightHanded conversion, and exactly what the loader does and does not support. Triggers on: glTF, gltf, glb, OBJ, MTL, 3D model, getGLTF, getOBJ, getMTL, GLTFModel, GLTFScene, level.load glb, rightHanded, lightIntensityScale, castGroundShadow, shadowGroundY, EXT_mesh_gpu_instancing, KHR_lights_punctual, skinning, Blender export, 3D asset."
+description: "Use this skill when loading 3D models into melonJS — glTF and GLB scenes, OBJ/MTL models, materials, imported lights, node animation, ground shadows and GPU instancing. Covers level.load options including the async flag, the rightHanded conversion, and exactly what the loader does and does not support. Triggers on: glTF, gltf, glb, OBJ, MTL, 3D model, getGLTF, getOBJ, getMTL, GLTFModel, GLTFScene, level.load glb, rightHanded, lightIntensityScale, castGroundShadow, shadowGroundY, EXT_mesh_gpu_instancing, KHR_lights_punctual, alphaMode, doubleSided, map_d, map_bump, normalize, animationspeed, skinning, Blender export, 3D asset."
 license: MIT
 ---
 
@@ -36,16 +36,8 @@ or it renders flat. See `melonjs-3d` for the camera.
 | `onLoaded` | `game.onLevelLoaded` | called with the **level id**, not the scene |
 | `async` | `false` | return a promise that settles once the scene is in the world, instead of a boolean |
 | `rightHanded` | `true` | see below |
-| `lights` | `true` | instantiate authored `KHR_lights_punctual` lights as `Light3d` world children |
+| `lights` | `true` | instantiate authored `KHR_lights_punctual` lights as `Light3d` children of `container`; `false` also builds the meshes unlit |
 | `lightIntensityScale` | — | keep authored intensity ratios instead of normalising every light to 1 |
-
-Those `game.` defaults are the engine's, not a recommendation. `game` is
-whichever `Application` finished `init()` last, so **pass `container`
-explicitly** from a `Stage`, where the right one is in your hand:
-
-```js
-level.load("sceneId", { container: this.app.world, scale: 40 });
-```
 | `castGroundShadow` | inherits the app setting (**on**) | blob shadows for this scene's meshes |
 | `shadowGroundY` | each object's own base | world Y of the floor the blobs land on |
 | `shadowOpacity` | `0.45` | how dark the blobs are |
@@ -56,6 +48,16 @@ level.load("sceneId", { container: this.app.world, scale: 40 });
 | `shadowGroundNormal` | world up | up normal of the floor, for a scene that is not level |
 | `shadowLight` | — | a `Light3d` to take the direction from, re-read every draw |
 
+Those `game.` defaults are the engine's, not a recommendation. `game` is
+whichever `Application` finished `init()` last, so **pass `container`
+explicitly** from a `Stage`, where the right one is in your hand:
+
+```js
+onResetEvent(app) {
+    level.load("sceneId", { container: app.world, scale: 40 });
+}
+```
+
 `shadowGroundPoint` is **not** on that list, and a scene load drops it without
 a warning. One floor POINT shared by every part of a scene would stack the
 whole thing's blobs on a single spot, which is nonsense where one floor
@@ -102,9 +104,10 @@ world.addChild(new Trigger(x, y, {
 
 Every `level.load` option above travels, including the whole ground-shadow set,
 and so do `container`, `onLoaded`, `flatten` and `setViewportBounds`. The list is
-**derived** from `level.loadOptions` rather than restated, so an option added to
-a level format arrives here for free. It used to be hand-written and had fallen
-three releases behind the glTF path (#1649).
+**derived** from the options each level format declares beside the code that
+reads them, rather than restated, so an option added to a level format arrives
+here for free. It used to be hand-written and had fallen three releases behind
+the glTF path (#1649).
 
 **`async` is deliberately excluded.** A trigger with a `color` + `duration`
 sets it itself, because it needs the promise to sequence its fade and reveal; a
@@ -132,24 +135,34 @@ Do not add a flip of your own on top; two corrections cancel back to wrong.
 The importer covers a deliberate subset:
 
 - `pbrMetallicRoughness` **base colour texture and factor**
+- `COLOR_0` **vertex colours**, multiplied with the factor and the texture
 - metallic/roughness **factors** converted to the engine's specular model
 - `emissiveFactor`, including `KHR_materials_emissive_strength`
 - `KHR_materials_unlit` — honoured, for baked/stylised workflows
 - `alphaMode: "MASK"` — the cutout threshold is applied
 - `doubleSided`
+- the base colour texture's sampler: `wrapS` / `wrapT` (repeat by default, as
+  the spec says) and `magFilter`
+
+`alphaMode: "BLEND"` is read as opaque: the loader does not set `transparent`,
+because one loaded mesh can merge materials and the flag routes the whole mesh.
+Set `transparent: true` on the part yourself (see `melonjs-3d`).
 
 Not imported: **normal maps**, metallic/roughness *textures*, occlusion maps,
 morph targets, `KHR_texture_transform`. Nothing errors — the material simply
 arrives without them, which reads as "flatter than the preview in my authoring
-tool". Bake what you need into the base colour.
+tool". Bake what you need into the base colour. (OBJ/MTL does carry a normal
+map, see below.)
 
 **Draco compression is the exception that does error.** Its geometry sits in
 accessors with no buffer view, which the parser rejects outright, so the whole
 asset fails to load. Export uncompressed.
 
-`textureFilter` on the Application settings (`"nearest"` / `"linear"` /
-`"auto"`) drives sampling; glTF materials that declare their own sampler carry
-it through. Pixel-art models want `"nearest"`.
+`textureFilter` on the Application settings (`"auto"` / `"nearest"` /
+`"linear"` / `"linear-mipmap"`) drives sampling; glTF materials that declare
+their own sampler carry it through. Pixel-art models want `"nearest"`. A mesh
+already samples mipmaps under `"linear"`, so `"linear-mipmap"` changes nothing
+for one.
 
 ### `baseColorFactor` is LINEAR; a `tint` is sRGB
 **Pass the factor as a setting and the encoding is done for you.** `Mesh`
@@ -222,8 +235,10 @@ screen, a HUD tint or a glow, are already sRGB: `* 255` is right for those.
 ## Lights
 
 Authored `KHR_lights_punctual` lights — sun, point, spot — become `Light3d`
-world children, plus a soft ambient fill, and each keeps its authored name.
-A scene carrying any of them renders through the **lit** path automatically.
+children of the container the scene loads into, plus a soft white ambient fill
+at intensity 0.3, and each keeps its authored name. A scene carrying any of them
+renders through the **lit** path automatically (except `KHR_materials_unlit`
+materials); one carrying none renders unlit.
 
 glTF stores physical units — lux for suns, candela for lamps — and a Blender
 daylight sun is 1000+, which blows out the engine's stylised shading. So every
@@ -235,7 +250,10 @@ set, scale instead of normalising:
 level.load("diorama", { scale: 50, lightIntensityScale: 0.001 });
 ```
 
-Pass `lights: false` to manage lighting yourself.
+Pass `lights: false` to leave the authored lights out. The meshes are then built
+**unlit**, so a `Light3d` of your own does not shade them either. To light a
+scene your own way, keep the authored lights and retune them by name, or remove
+them once the load has finished and add yours: the meshes stay lit.
 
 ## Animation
 
@@ -258,13 +276,18 @@ model.pause();
 
 `speed` is a playback multiplier (1 = authored speed), not a frame delay. Only
 an explicit `loop: false` stops looping. `setCurrentAnimation` **throws** on a
-clip name the asset does not define — check `getAnimationNames()` first.
+clip name the asset does not define — check `getAnimationNames()` first. Called
+with the clip that is already playing it returns at once and ignores its
+options, so retime a running clip through `model.animationspeed`, not a second
+`setCurrentAnimation(name, { speed })`.
 
 ### Placing and moving a model
 
 A `GLTFModel` is placed like any other renderable — `pos`, `depth`, `rotate`
 and `scale` move the **whole rig**, and compose with whatever the active clip
-is doing, so a walk cycle plays wherever the character stands:
+is doing, so a walk cycle plays wherever the character stands. They apply just
+the same while the clip is paused, finished or was never played, and `scale()`
+multiplies the `scale` option the model was built with:
 
 ```js
 const boat = new me.GLTFModel(me.loader.getGLTF("boat"), { scale: 40, lit: false });
@@ -295,6 +318,11 @@ hundred thousand. Export with instancing enabled where your tool supports it.
 Sparse accessors on the instancing attributes are rejected with a clear error
 rather than silently misplacing every instance.
 
+Face culling is decided once per mesh, so instances with a **negative scale**
+(mirrored linked duplicates) render inside-out. Building the scene or model
+warns when it meets them; mark the material `doubleSided`, which turns culling
+off for the set.
+
 ## Ground shadows
 
 ```js
@@ -353,7 +381,7 @@ world.addChild(mesh);
 ```
 
 **The MTL loader fetches the textures it references itself** — `map_Kd`,
-`map_d` and `map_bump` are resolved relative to the `.mtl` and preloaded for
+`map_d` and the normal map are resolved relative to the `.mtl` and preloaded for
 you, so there is no image entry in the manifest above. Passing `texture:`
 explicitly overrides that and pins *one* binding over the whole model, which on
 a multi-material model suppresses the per-material texture split; leave it out
@@ -361,19 +389,23 @@ unless you mean that.
 
 MTL contributes `Kd` (diffuse tint), `d` / `Tr` (opacity), `Ke` (emissive),
 `Ks` + `Ns` (specular highlight), `map_Kd` (diffuse texture), `map_d`
-(per-texel opacity) and `map_bump` / `bump` / `norm` (tangent-space normal
-map — needs `lit: true`, and the tangent frame is derived per fragment, so the
-model needs no tangent attribute). All three normal-map spellings are read as
-normal maps even though the format specifies two of them as height maps, which
-is what every exporter actually writes. Specular *maps* (`map_Ks`) and the PBR
-extension's `map_Pr` / `map_Pm` are not supported and warn — the `Pr` / `Pm`
-*scalars* are read and approximated onto the specular terms, the maps would
-need a real PBR model.
+(per-texel opacity) and `map_bump` / `map_Bump` / `bump` / `norm`
+(tangent-space normal map — needs `lit: true`, and the tangent frame is derived
+per fragment, so the model needs no tangent attribute). Every normal-map
+spelling is read as a normal map even though the format specifies `bump` and
+`map_bump` as height maps, because a normal map is what exporters actually
+write there. Specular *maps* (`map_Ks`) and the PBR extension's `map_Pr` /
+`map_Pm` are not supported and warn — the `Pr` / `Pm` *scalars* are read and
+approximated onto the specular terms, the maps would need a real PBR model.
+
+`map_d` cuts out only against a non-zero `alphaCutoff`, and the loader sets
+none: pass one in the `Mesh` settings (`alphaCutoff: 0.5`), or nothing is cut
+out.
 
 `Ka` (ambient) and `illum` (illumination model) are read onto the material and
 readable from `loader.getMTL(name)`, but take no part in shading. That is
 deliberate rather than pending: `Ka` predates scene-wide ambient light and would
-fight `Stage.ambientLightingColor`, and `illum` enumerates fixed-function
+fight an `"ambient"` `Light3d`, and `illum` enumerates fixed-function
 behaviours this renderer has no equivalent for. In particular an `illum` of 0 or
 1 nominally means "no specular", and the engine does **not** honour that — `Ns`
 stays the only gate, so a model that renders correctly today is not restyled by
@@ -469,11 +501,19 @@ const node = me.loader.getGLTF("palm").nodes[0];
 const trees = new me.InstancedMesh(0, groundY, {
     vertices: node.vertices, uvs: node.uvs,
     normals: node.normals, indices: node.indices,
+    normalize: false,     // keep the authored units; see below
     texture: palette, textureFilter: "nearest", scale: 40,
     instanceCount: count,
 });
 ```
 
+**Pass `normalize: false` whenever the geometry comes off a descriptor.** The
+default fits the geometry into a unit cube, centred, which throws away the
+authored size and the base-on-the-floor origin. Before 20.14 it was worse: the
+default normalized the loader's own array in place, so every later mesh built
+from that node, and a `level.load` of the same asset, got the shrunken
+geometry. A normalized mesh works on a copy now.
+
 `nodes` is one entry **per primitive**, each in its own local space with a
 separate `world` matrix — so this only works cleanly when the asset is a single
 merged primitive exported with an identity node transform. Model it at the
@@ -515,8 +555,16 @@ need a prefix.
 | the asset fails to load entirely | an external buffer/image `uri` that 404s, or Draco-compressed geometry |
 | everything is blown out white | authored lux/candela intensities; use `lightIntensityScale` |
 | materials flatter than the authoring-tool preview | no normal or metallic/roughness *textures* are imported |
+| a glTF `alphaMode: "BLEND"` material draws opaque | the loader does not set `transparent`; set it on that part yourself |
+| an MTL `map_d` cuts nothing out | it needs a non-zero `alphaCutoff`, which the loader does not set |
+| a mesh built from `getGLTF(name).nodes` comes out unit-sized | `normalize` defaults to `true`; pass `normalize: false` to keep the authored units |
+| after one normalized mesh of a model, the scene or other meshes of that model load shrunken (before 20.14) | the default normalized the loader's cached array in place; update, or pass `normalize: false` |
+| some copies in an imported scatter render inside-out | negative-scale (mirrored) instances under per-mesh face culling; make the material `doubleSided` |
 | a character does not deform | vertex skinning is out of scope; rig hierarchically or billboard |
 | animation names come back empty | the asset has no node-TRS channels (skin-only rig) |
+| `setCurrentAnimation(name, { speed })` changes nothing | that clip is already playing, so the call returns at once; set `animationspeed` |
+| `model.scale(2)` throws "not a function" on a `GLTFModel` (before 20.14) | the `scale` option hid the method: update |
+| a `GLTFModel` ignores `pos` / `rotate` once its clip is paused or finished (before 20.14) | it was only re-posed while a clip played: update |
 | a hundred copies tank the frame rate | exported without `EXT_mesh_gpu_instancing` |
 | a whole scatter looks like one object repeated | every instance shares the group transform — vary yaw/scale per instance, rotating *after* the translate |
 | three clips where you authored one | one action per object; use a single action with a slot each |
@@ -530,12 +578,14 @@ need a prefix.
 | a shadow smeared across the whole floor | a ground plane cast its own blob — use the scene-wide opt-in |
 | `onLoaded` gets a string, not the scene | it is called with the level id; load into your own container instead |
 | scene renders flat and unlit | no `Camera3d` — the 2D-camera path is CPU-projected and unlit (with a `Camera3d` on Canvas you get a black canvas instead) |
+| scene renders in perspective but unlit | the asset carries no sun, point or spot light (or was loaded with `lights: false`), so its meshes are built unlit; author one in the asset and tune it at runtime by name |
 
 ## Related skills
 
 - `melonjs-3d` — conventions, `Camera3d`, meshes, `Light3d`, instancing, and
   `camera.setFog` (an outdoor scene almost always wants it; it is set on the
   camera, so a loaded scene needs no per-node work)
-- `melonjs-lighting` — how `Light3d` behaves once imported
+- `melonjs-lighting` — the 2D `Light2d` system; imported lights are `Light3d`,
+  covered in `melonjs-3d`
 - `melonjs-loading-assets` — the loader, asset types and base URLs
 - `melonjs-plugins` — the Spine plugin, for skeletal characters

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
@@ -463,10 +497,12 @@ the level starts. The loader calls the same function, so the same rules apply.
 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.
 
-**Credentials use the same global switch as every other asset type** —
-`loader.setOptions({ withCredentials: true })`, not an audio-specific option.
-Buffered audio fetches through the shared loader path, so it honours it exactly
-as an image or a JSON file does. A streamed clip (`stream: true`, or
+**Credentials work as for every other asset type.** Buffered audio on the
+game's own origin carries its cookies and HTTP auth with no option; a clip on
+another origin behind a login needs `loader.setOptions({ withCredentials: true })`,
+not an audio-specific option, and that server must allow credentials. Buffered
+audio fetches through the shared loader path, so it behaves exactly as an image
+or a JSON file does. A streamed clip (`stream: true`, or
 `preload: false`) does not: it plays
 through an `<audio>` element, which needs a `crossorigin` attribute rather than
 fetch credentials. Preload a clip buffered if it sits behind a login.
@@ -488,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 |
@@ -498,18 +535,24 @@ either way — blank screen, empty console.
 | `stereo` / `position` do nothing | the clip was loaded with `stream: true` or `preload: false` — spatial is WebAudio-only |
 | a `preload: false` clip never plays, and `audio.state()` stays `"unloaded"` | melonJS before 20.12.0 never fetched such a clip; preload it, or update |
 | one format works, another does not | that codec is not in the `audio.init()` list |
-| audio behind a login fails, or the preload hangs | `loader.setOptions({ withCredentials: true })` — the same switch every asset type uses |
+| audio on another origin behind a login fails, or the preload hangs | `loader.setOptions({ withCredentials: true })` — the same switch every asset type uses. Audio on the game's own origin needs nothing (before 20.13 it needed it too) |
 | a streamed clip ignores `withCredentials` | `stream: true` plays through an `<audio>` element; preload it buffered instead |
 | `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` |
 | 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, 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
@@ -143,6 +192,12 @@ app.viewport.worldToLocal(x, y);   // world → screen
 app.viewport.localToWorld(x, y);   // screen → world
 ```
 
+They agree with where the camera draws: a level smaller than the view is
+centred by offsetting the world container (`world.pos`), which the default
+camera draws and a minimap, corner or zoomed camera leaves out, and each
+camera's conversions follow suit (20.13 and later; before, a minimap's were off
+by `world.pos`).
+
 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)`.
@@ -205,6 +260,14 @@ and an overridden `postDraw`:
 this.cameras.set("minimap", new MinimapCamera());
 ```
 
+A stage's cameras draw in the order they were added, each over the ones before
+it, so a full-screen second camera is a layer: a `Camera3d` drawing a 3D
+background first, the game's own camera over it, each kept to its part of the
+world with `visibilityLayer` / `cullMask` (below). A camera's post effects
+apply to what that camera draws: the first camera's pass starts the frame, and
+a later camera's is blended over what is already there (20.13 and later;
+before, it wiped out the cameras before it).
+
 View state is per camera, not per scene: a `Camera3d` carries its own distance
 fog (`setFog`), so a minimap or split-screen view fogs independently of the main
 one — and a `Camera2d` never fogs. See `melonjs-3d`.
@@ -228,6 +291,9 @@ minimap.cullMask = ~PARTICLES;         // the minimap draws every layer but 2
   set it on an emitter and none of its particles are drawn. The world itself
   obeys it too, and so does what it contains: a child is drawn only if it and
   every container above it share a bit with the camera.
+- Particles are on their emitter's layers, and follow a change to them on the
+  emitter's next update, so a camera that draws only the emitter's layer draws
+  its particles too.
 - A renderable on layer `0` is drawn by no camera; a `cullMask` of `0` draws
   nothing.
 - It decides drawing only: what a camera leaves out still updates, collides and
@@ -256,9 +322,56 @@ draw(renderer) {
 }
 ```
 
+**The colour's alpha and the global alpha are two things**, as on a 2D
+context. A fill or a stroke is drawn at the alpha of `setColor` times
+`setGlobalAlpha` (which is where the renderable's opacity comes in), an image at
+the global alpha (times the tint) alone, and `getGlobalAlpha()` never moves with
+`setColor`. So to fade a translucent shape, lower the global alpha and keep the
+colour; folding the colour's alpha into `setGlobalAlpha` as well counts it twice.
+
+`lineWidth`, `lineJoin`, the colour and the global alpha are all part of what
+`save()` / `restore()` keep, and every renderable's `draw()` runs between the
+two, so set them freely there: the next renderable gets them back.
+
+`fillArc` / `strokeArc` read their angles like `CanvasRenderingContext2D.arc`:
+an end before the start wraps round (`end + 2π`), and a span of 2π or more in
+the arc's own direction is the whole circle. A filled part-circle differs by
+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)` /
@@ -319,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.
 
@@ -383,6 +497,7 @@ const data = await rt.toImageData(0, 0, w, h);
 
 | symptom | cause |
 |---|---|
+| a second camera's post effect wipes out what the first camera drew | before 20.13 a later camera's post-effect pass replaced the whole frame; update, or put the effects on a container instead of the camera |
 | `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 |
@@ -390,12 +505,24 @@ const data = await rt.toImageData(0, 0, w, h);
 | 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 |
+| after a translucent `setColor`, images, later colours and the next renderables come out faded (WebGL / WebGPU) | before 20.13 the colour's alpha leaked into the global alpha; update |
+| a translucent colour comes out fainter than asked | its alpha folded into `setGlobalAlpha` as well, so it counts twice |
+| a `lineWidth` set in one `draw()` thickens everything drawn after it (WebGL / WebGPU) | before 20.13 `restore()` did not put `lineWidth` back; update, or put it back yourself |
+| `fillArc` with the end angle before the start fills the wrong part of the circle (WebGL / WebGPU) | before 20.13 the GPU renderers did not wrap the angles like Canvas; update |
+| a minimap's `worldToLocal` / `localToWorld` are off by the level's centring offset | before 20.13 they applied `world.pos`, which a non-default camera does not draw; update |
 | 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` |
 | `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` |