melonjs 20.3.0 → 20.4.0

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-3d
-description: "Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, castGroundShadow, lit."
+description: "Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, lit."
 license: MIT
 ---
 
@@ -97,6 +97,157 @@ index** — a real world depth in a 3D scene, and never the one you wanted. Pass
 it (`world.addChild(mesh, z)`), or set `mesh.depth` afterwards. The glTF
 importer turns `autoDepth` off on the container it loads into for this reason.
 
+**`floating` does not opt out of this sort.** It skips the camera *transform*,
+not the depth *order*. A floating child is ordered by `|pos.z|` alone — its
+`pos.x/y` are screen pixels, and the camera does not move relative to it — so
+the magnitude is the distance and the sign is ignored:
+
+```js
+world.addChild(hud, -150);       // small -> nearer than anything -> on top
+world.addChild(skybox, -10000);  // large -> farther -> behind everything
+world.addChild(skybox, 100000);  // equally far: sign does not matter
+```
+
+Both hold at any camera position. A HUD given the huge z that would put it on
+top in 2D lands at the far end of the level instead, with the scenery drawing
+over it.
+
+## Transparency
+
+A mesh fades by setting its opacity — there is nothing else to switch on:
+
+```js
+ghost.setOpacity(0.4);
+```
+
+Meshes render in two phases. The **opaque pass** writes depth in sort order; the
+**transparent pass** replays afterwards, back-to-front, blending and writing no
+depth. A draw lands in the second whenever its alpha is fractional.
+
+That default matters because the opaque path writes premultiplied colour with
+blending off, so before this a faded mesh came out **darkened toward black**
+rather than see-through — the background contributed nothing.
+
+**`transparent: true`** when the transparency is in the TEXTURE rather than the
+opacity — a soft-edged glow, smoke, a glTF material with `alphaMode: "BLEND"`.
+The automatic check reads the draw's alpha and cannot see into a texture. Watch
+`alphaCutoff` here: it discards texels *before* blending sees them, so a soft
+edge needs a low cutoff (`Sprite3d` drops its own default to `1/255` when you
+set `transparent: true`). The cutoff thresholds the MATERIAL's alpha, not the
+drawn alpha, so a fading cutout mesh keeps its shape instead of disappearing at
+its own threshold.
+
+The glTF loader does **not** set this for you: one loaded mesh can merge several
+materials and the flag routes the whole mesh, so a `"BLEND"` material sharing
+geometry with an opaque one would drag the opaque half into the transparent pass.
+
+**`transparent: false`** pins a mesh to the opaque pass however it is faded.
+
+Blending uses the renderable's existing `blendMode`, so a glow is one property.
+The advanced modes (`"overlay"`, `"difference"`, and the rest that need a
+compositing pass) fall back to `"normal"` here, on both backends:
+
+```js
+const glow = new Mesh(0, 0, {
+    ...quad, texture: glowTexture,
+    transparent: true, blendMode: "additive", alphaCutoff: 0,
+});
+```
+
+| | |
+| --- | --- |
+| sorting | **per object**, by distance from the camera |
+| intersecting transparent meshes | may pop as the camera moves — split them, or accept it |
+| `InstancedMesh` | sorts as **one** object; instances draw in buffer order |
+| needs | a GPU backend and a `Camera3d` |
+
+Ground shadows ride the same pass — a blob is a decal, and decals are its first
+client rather than a feature of their own.
+
+## Distance fog
+
+Off until you ask for it, and one call on the camera:
+
+```js
+camera.setFog({ near: 2000, far: 7000 });   // linear: name the two distances
+camera.setFog({ mode: "exp2", density: 4e-4 }); // or one density
+camera.setFog(null);                         // off
+```
+
+It is the cheapest thing that stops a 3D scene reading as flat cut-outs, and it
+lets props arrive at the far plane without a visible edge.
+
+**Every parameter is optional, and the omitted ones track live.** Distances
+default to the camera's own clip planes, so fog cannot silently disagree with
+them after a later `setClipPlanes`. The colour defaults to
+`renderer.backgroundColor` and follows it, so geometry dissolves into whatever
+sky you already set — including through a day/night fade. Pass `color` only
+when the fog should deliberately differ from the backdrop:
+
+```js
+camera.setFog({ far: 5000, color: "#8899aa" });
+```
+
+A `Color` is held by reference, so mutating it animates the fog.
+
+**Height falloff** makes mist pool in low ground instead of hanging at every
+altitude equally — the difference between fog reading as weather and as a global
+desaturation:
+
+```js
+camera.setFog({ near: 1200, far: 7000, fogHeight: 0, heightFalloff: 0.0015 });
+```
+
+`heightFalloff` defaults to **0**, which is uniform fog — not a special case,
+the same integral with the dial at zero, so leaving it out changes nothing.
+Render space is **Y-down**, so `fogHeight` is the floor and density rises
+*below* it; every published form of this formula assumes Y-up and has the
+opposite sign.
+
+Fog is measured **radially** from the camera and applied **per fragment**, so
+it does not slide as the camera turns and does not band across large triangles.
+It lives on the camera, so a split-screen or minimap view fogs independently —
+and a `Camera2d` never fogs at all.
+
+**Per object:** `fog: false` exempts a mesh however far away it is — for a
+waypoint or objective marker that has to stay readable. It exempts the mesh and
+not the ground shadow it casts: a blob is a mark on the floor and fogs with the
+floor. Emissive surfaces fog
+like everything else (light travelling through fog is attenuated too), so a
+neon sign that should punch through wants `fog: false`, not a brighter
+emissive.
+
+Only meshes fog. 2D content, HUDs and `floating` renderables never reach the
+mesh shaders, so a screen-space overlay stays clean with no work.
+
+**A custom mesh shader is not fogged unless it asks to be.** Fog is compiled
+into the engine's own mesh programs — `#define FOG` on WebGL, an `enable_fog`
+overridable constant on WebGPU — and a shader you supply is yours: the engine
+binds it as written and never substitutes a fogged variant. So a mesh carrying a
+`ShaderEffect` keeps full contrast while the scene around it recedes. It is safe
+— nothing throws, and the camera's fog is simply not applied — but it is usually
+surprising.
+
+To opt in, declare the same uniforms and the engine will feed them, because the
+fog values are pushed to any mesh program that declares them rather than only to
+the built-in ones:
+
+```glsl
+uniform vec3 uFogColor;   // straight (unpremultiplied) fog colour
+uniform vec4 uFogParams;  // x = mode (0 off / 1 linear / 2 exp2),
+                          // y = near, z = 1/(far - near), w = density
+```
+
+Your vertex stage computes the distance itself — `length((uViewMatrix *
+uModelMatrix * vec4(aVertex, 1.0)).xyz)`, radially so it does not swim as the
+camera turns — and the blend must scale the fog colour by the fragment's own
+alpha, `mix(uFogColor * a, rgb, f)`, because `vColor` arrives premultiplied.
+Mixing toward the unscaled colour haloes every alpha-cutout edge.
+
+The flip side is the reason fog costs nothing when unused: with no camera fog,
+the mesh programs are compiled without any of it, on both backends. It is not a
+branch that is skipped at runtime — the code is not there.
+
 ## Meshes
 
 ```js
@@ -115,9 +266,127 @@ there — place the origin where you want the pivot at authoring time, or nest t
 mesh under a transformed parent. The anchor is only honoured on the legacy
 2D-camera path.
 
+### InstancedMesh, and when it is the wrong tool
+
 **`InstancedMesh`** draws one mesh many times in a single draw call — the
 difference between a hundred trees and a hundred thousand. glTF scenes using
-`EXT_mesh_gpu_instancing` load as an `InstancedMesh` automatically.
+`EXT_mesh_gpu_instancing` load as one automatically; by hand it is a `Mesh`
+with a count:
+
+```js
+const trees = new InstancedMesh(0, 0, { ...treeGeometry, instanceCount: 400 });
+const at = new Matrix3d();               // one scratch, reused
+for (let i = 0; i < trees.instanceCount; i++) {
+    at.identity().translate(x, y, z);
+    trees.setInstance(i, at);
+}
+world.addChild(trees, 0);
+
+trees.visibleInstanceCount = 120;        // draw fewer, without re-uploading
+```
+
+It is not a free upgrade. One `InstancedMesh` is **one geometry and one
+material**, and four things move from per-object to per-group:
+
+| | with `Mesh` | with `InstancedMesh` |
+| --- | --- | --- |
+| depth sort | each object sorts on its own `pos` | the whole set has **one** sort key |
+| ground shadow | one blob per object | one instanced draw for the set |
+| removal | `removeChild`, indices unaffected | `removeInstance(i)` swaps the **last** instance into the hole, so any index you were holding is now wrong |
+| colour | `tint` per object | needs `instanceColors: true` and `setInstanceColor(i, …)` |
+
+So the question is not "how many are there" but **"does the game address them
+individually"**:
+
+- **Scenery — instance it.** Trees, rocks, grass, debris: the game never asks
+  about one of them.
+- **Collision-tested props — still fine.** You test against positions you
+  already own; instancing only changes how they are *drawn*.
+- **Collectibles and enemies — usually not.** Anything removed one at a time
+  makes `removeInstance`'s swap your problem: you have to keep an index↔object
+  map and repair it on every removal. At small counts a pooled `Mesh` each is
+  less code and no slower.
+
+Under a few hundred objects the draw-call saving is not what limits you
+anyway — reach for it when the count is in the thousands, or when the objects
+are pure scenery and it costs nothing to.
+
+## Normals are generated for you
+
+A `lit` mesh needs per-vertex normals for the shader to light with. Supply them
+if you have them; **omit them and the engine computes them from the geometry**:
+
+```js
+const mesh = new Mesh(x, y, { vertices, uvs, indices, lit: true });
+// normals derived from the triangles — nothing else to do
+```
+
+You do not choose flat or smooth, because the geometry already decides. Face
+normals accumulate into their vertices weighted by area, so where faces **share**
+a vertex they average and the surface shades smoothly, and where every triangle
+carries its **own** three vertices — a triangle soup, which is how most
+hand-built geometry comes out — each vertex belongs to one face and the result
+is that face's normal, so it shades flat. Want faceted edges: duplicate the
+vertices. Want smooth: share them.
+
+An explicit `settings.normals` always wins, and an unlit mesh gets none — there
+would be nothing to read them.
+
+**A lit mesh with no normals used to render fullbright**, which looks like the
+lighting is broken rather than absent. If an older scene suddenly picks up
+shading, that is why.
+
+## Colouring a mesh
+
+There are four levels, and picking the wrong one is the usual reason a colour
+"does not apply". They all multiply together.
+
+| level | how | use for |
+|---|---|---|
+| whole object | `mesh.tint.setColor(r, g, b)` | flash on hit, team colour, fading one object |
+| per vertex | `settings.vertexColors`, or `mesh.setVertexColor(i, color)` | a gradient *within* one mesh — distance haze, a darker crease |
+| per material | `textureGroups`, from a multi-material OBJ + MTL | a model whose parts differ, in one draw call |
+| per instance | `new InstancedMesh(…, { instanceColors: true })` then `setInstanceColor(i, color)` | a thousand copies that differ |
+
+**`tint` is per object.** That is the trap: build a terrain as one big mesh and
+you can tint the whole valley or none of it. Anything that varies *across* a
+single mesh is per-vertex.
+
+```js
+// fade a procedural terrain toward the sky the further out it goes
+const ground = new Color(217, 230, 244);
+const sky = new Color(207, 230, 247);
+const haze = new Color();
+for (let i = 0; i < mesh.vertexCount; i++) {
+    const t = Math.min(1, mesh.originalVertices[i * 3 + 2] / 6000);
+    mesh.setVertexColor(i, haze.copy(ground).lerp(sky, t));
+}
+```
+
+Supply the whole array at construction when you already have it —
+`vertexColors` takes a packed `Uint32Array` (the form the batchers read, so no
+conversion) or one `Color` per vertex. A length that does not match
+`vertexCount` **throws**; it is not padded, because a short array would leave
+the tail of the mesh mis-coloured and that reads as a lighting bug.
+
+Mutating the array directly is fine, but say so afterwards:
+
+```js
+mesh.vertexColors[i] = color.toUint32(color.alpha);
+mesh.needsUpdate = true;   // the retained Camera3d path uploads once
+```
+
+`setVertexColor` does that for you. Skip it and the colour applies under a 2D
+camera and silently does not under `Camera3d`.
+
+On a lit mesh the colour multiplies the **lit** result, so it behaves as albedo
+rather than as an emissive override — a vertex colour will not make an unlit
+face bright.
+
+`alpha` hides a mesh as it hides anything else: at 0 the draw is skipped. There
+is no *partial* mesh transparency though — the mesh path renders opaque, so a
+mesh at `alpha = 0.5` draws fully opaque rather than half see-through. Fade a
+mesh out and it will stay solid until it vanishes.
 
 ## Sprite3d and billboards
 
@@ -164,6 +433,18 @@ skip geometry with no vertical extent — a ground plane. Per object,
 `castGroundShadow: true`/`false` overrides the app setting and is obeyed as
 given, safeguard included; `shadowGroundY` names the floor the blob lands on.
 
+The blob is an ellipse sized to the caster's own footprint and placed at the
+caster's x/z — it is **never offset by light direction**. So a tall or narrow
+object (a character, a tree, a pickup) shows its shadow clearly, while a wide,
+flat-bottomed one resting on the floor covers its own completely from a camera
+looking down at it. That is the shadow behaving correctly, not a bug.
+
+**Do not chase it by raising `shadowGroundY`.** Lifting the plane does not slide
+the blob out from under the object, it floats the blob *up* — and past a few
+units it projects over the top of the caster as a dark halo ringing it. If an
+object needs a visible shadow, give it a smaller footprint relative to its
+height, or accept that a boulder bedded in the ground has none.
+
 ## glTF / GLB scenes
 
 Loaded through the same level director as everything else:
@@ -209,11 +490,29 @@ To branch rather than fail, read `app.renderer.supportsDepthBuffer` after
 
 | symptom | cause |
 |---|---|
+| a `lit` mesh renders fullbright | it had no normals — supply them, or let the engine generate them |
+| a gradient across one mesh is impossible | `tint` is per object — use `vertexColors` / `setVertexColor` |
+| a mesh stays solid as you fade it out | meshes render opaque; only `alpha` 0 (hidden) and 1 differ |
+| vertex colour applies under a 2D camera but not `Camera3d` | wrote the array directly without setting `needsUpdate` |
+| `Mesh: vertexColors has N entries, expected M` | one colour per *vertex*, not per triangle or per index |
 | nothing renders, or a backdrop covers everything | wrong depth sign — "far" is *larger* z when looking along +Z |
 | distant objects vanish or warp | scene exceeds the default far plane; `setClipPlanes` |
 | distant surfaces z-fight | `near` too small for the scene scale |
 | black canvas under `Camera3d` | Canvas renderer (no depth buffer) — check the `console.warn` |
 | everything flat and unlit | `lit: true` with no `Light3d` in the world (falls back to fullbright), or a mesh under a 2D camera |
+| a faded mesh goes dark instead of see-through | `transparent: false` on it, or a 2D camera — the transparent pass needs a `Camera3d` |
+| a soft-edged glow has hard edges | `alphaCutoff` discarded the soft texels; lower it |
+| a glTF `alphaMode: "BLEND"` material draws opaque | the loader does not set `transparent` — one mesh can merge several materials, so set it yourself |
+| two transparent objects pop as the camera moves | per-object sorting cannot order intersecting geometry |
+| a `floating` HUD draws behind the scenery | a large \|z\| is *far* under `Camera3d` — use a small depth |
+| fog hangs in the sky as thickly as in the valley | uniform fog — add `heightFalloff` so it pools low |
+| mist sits on the ridges instead of the valley floor | the `fogHeight` sign — Y is DOWN here, density rises below it |
+| distant geometry pops in against the sky | no fog — `camera.setFog({})` picks up the clip planes and background colour |
+| fog does not match the sky after a background fade | an explicit `color` was passed; omit it to track `renderer.backgroundColor` |
+| geometry clips before it has finished fading | fog `far` beyond the clip far — omit the distances and they default to the clip planes |
+| one marker must stay readable in fog | `fog: false` on that mesh |
+| an object casts no visible shadow | wide and flat-bottomed — its own blob is underneath it; raising `shadowGroundY` haloes it instead of revealing it |
+| a dark ring around the top of an object | `shadowGroundY` lifted too far, floating the blob up into the caster |
 | a mesh sits at the wrong depth after being added | `autoDepth` overwrote `pos.z` with the child index — pass `addChild(mesh, z)` |
 | a mesh sits half its size off | `anchorPoint` — only on the 2D-camera path; a `Camera3d` mesh pivots on its model origin |
 | a billboard tips over when the camera looks down | `"spherical"`, or a mistyped mode string falling through to it — use `true` / `"cylindrical"` |

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, 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, skinning, Blender export, 3D asset."
 license: MIT
 ---
 
@@ -34,6 +34,7 @@ or it renders flat. See `melonjs-3d` for the camera.
 | `scale` | `1` | pixels per glTF unit, applied to the whole scene. Blender's metre-scale export usually needs 20–100. |
 | `container` | `game.world` | where the nodes are added |
 | `onLoaded` | `app.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 |
 | `lightIntensityScale` | — | keep authored intensity ratios instead of normalising every light to 1 |
@@ -41,10 +42,19 @@ or it renders flat. See `melonjs-3d` for the camera.
 | `shadowGroundY` | each object's own base | world Y of the floor the blobs land on |
 
 `onLoaded` receives the level id — it is a "done" signal, not a handle on the
-scene. You need it: with the game loop running, `level.load` stops the loop and
-defers the actual load to the next tick, so it returns *before* anything is in
-the world. To get at what was loaded, load into a container you own, or look the
-nodes up by their authored names:
+scene. You need it, or `async`: with the game loop running, `level.load` stops
+the loop and defers the actual load to a timer, so by default it returns
+*before* anything is in the world.
+
+```js
+await level.load("diorama", { scale: 50, async: true });
+// the scene is in the world here
+```
+
+Note `await level.load("diorama")` without the flag does not await the load — the
+call returns a boolean, and `await true` resolves immediately. To get at what was
+loaded, load into a container you own, or look the nodes up by their authored
+names:
 
 ```js
 level.load("diorama", { scale: 50, onLoaded: () => {
@@ -166,6 +176,12 @@ Omit `shadowGroundY` and each blob sits at its own object's base at full
 strength, which is right for props already resting on the ground. Set it when
 things jump or fly, so the shadow stays on the floor and shrinks with height.
 
+A blob is centred on its caster's x/z and is never offset by light direction, so
+a wide flat-bottomed prop hides its own shadow under itself. Raising
+`shadowGroundY` to force one into view floats the blob up over the object as a
+dark ring rather than sliding it clear — the setting is for things that leave
+the ground, not a visibility knob.
+
 ## OBJ/MTL
 
 A different shape entirely: OBJ produces raw geometry you hand to a `Mesh`,
@@ -227,13 +243,16 @@ need a prefix.
 | 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) |
 | a hundred copies tank the frame rate | exported without `EXT_mesh_gpu_instancing` |
+| a prop casts no visible shadow | wide and flat-bottomed — the blob is under it; `shadowGroundY` haloes it rather than revealing it |
 | 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) |
 
 ## Related skills
 
-- `melonjs-3d` — conventions, `Camera3d`, meshes, `Light3d`, instancing
+- `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-loading-assets` — the loader, asset types and base URLs
 - `melonjs-plugins` — the Spine plugin, for skeletal characters

package/skills/melonjs-audio/SKILL.md

@@ -195,6 +195,25 @@ same switch under its backend name.) `on` accepts the full lifecycle set:
 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 `stream: true` clip 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.
+
+**Failing clips and `setStopOnAudioError(false)`.** The default is to fail the
+preload when a clip cannot be loaded after its retries: the error reaches the
+loader, so `await loader.preload(...)` rejects and your `catch` runs, and the
+reason is logged. Turn the flag off and the engine mutes audio, warns
+(`failed loading <name>, disabling audio`) and lets the load *continue* — the
+preload finishes and the game reaches the next scene without sound.
+
+Before 20.4 both halves were broken: with the flag off it disabled audio and
+failed the preload anyway, and a clip whose bytes arrived but would not decode
+(a missing file served as HTML by an SPA rewrite, say) reported nothing at all
+either way — blank screen, empty console.
+
 ## Symptom → cause
 
 | symptom | cause |
@@ -207,6 +226,8 @@ Re-preloading a manifest that already contains a loaded clip is a no-op —
 | music keeps playing after leaving a scene | used `play` instead of `playTrack`, or no `stopTrack` in teardown |
 | `stereo` / `position` do nothing | the clip was loaded with `stream: true` — spatial is WebAudio-only |
 | one format works, another does not | that codec is not in the `audio.init()` list |
+| audio behind a login fails, or the preload hangs | `loader.setOptions({ withCredentials: true })` — the same switch every asset type uses |
+| 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` |
 

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

@@ -87,6 +87,10 @@ and an overridden `postDraw`:
 this.cameras.set("minimap", new MinimapCamera());
 ```
 
+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`.
+
 ## Immediate-mode drawing
 
 Inside a custom `draw(renderer)` you can draw shapes directly. Remember the two

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

@@ -174,4 +174,5 @@ same question after construction.
 ## Related skills
 
 - `melonjs-renderables` — where post effects attach, and the destroy trap
-- `melonjs-3d` — custom mesh shaders and the GPU-backend requirement
+- `melonjs-3d` — the GPU-backend requirement, and why a custom mesh shader is
+  not affected by the camera's distance fog

package/skills/melonjs-loading-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-loading-assets
-description: "Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, asset, preload, LOADER_COMPLETE, loading screen, unload."
+description: "Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload."
 license: MIT
 ---
 
@@ -138,6 +138,32 @@ If you preload without a loading stage and then change state immediately, pass
 state.change(state.PLAY, true);
 ```
 
+## Cross-origin and authenticated assets
+
+Two settings, both global and both applying to **every** asset type — there is
+no per-asset or per-type spelling to remember:
+
+```js
+loader.setOptions({
+    crossOrigin: "anonymous",   // CORS mode for remote assets
+    withCredentials: true,      // send cookies / auth with the request
+});
+```
+
+`withCredentials` is what an asset behind a session cookie or an
+`Authorization`-style login needs. Every fetched asset — image, json, binary,
+tmx, tsx, shader, gltf/glb, obj, mtl, aseprite, video — carries it, and so does
+buffered audio.
+
+**Set them through `setOptions`.** `loader.crossOrigin` and
+`loader.withCredentials` are read-only module bindings; assigning to them
+throws, the same trap as the removed `loader.onload` / `onProgress`.
+
+| | |
+| --- | --- |
+| one streamed clip (`stream: true` / `html5: true`) ignores `withCredentials` | it plays through an `<audio>` element, which needs a `crossorigin` attribute rather than fetch credentials. Preload it buffered if it is behind auth |
+| credentials silently dropped for audio before 20.4 | the loader forwarded them under a pre-20.3 name the backend never read — a hung preload rather than an error |
+
 ## Symptom → cause
 
 | symptom | cause |
@@ -146,6 +172,9 @@ state.change(state.PLAY, true);
 | audio fails, `preload()` rejects with "Failed loading resource" | `audio.init()` not called before preloading — the real message is replaced by the loader's |
 | blank level, missing tiles | `.tsx` or tileset image not listed in the resources |
 | cross-origin textures fail | missing `loader.setOptions({ crossOrigin: "anonymous" })` |
+| assets behind a login 401 / audio preload hangs | missing `loader.setOptions({ withCredentials: true })` — one switch, all asset types |
+| `TypeError` assigning `loader.withCredentials` / `crossOrigin` | read-only module bindings; use `loader.setOptions({ … })` |
+| preload never finishes, blank screen, no error | a failing sound with `audio.setStopOnAudioError(false)` before 20.4 — it disabled audio *and* failed the preload |
 | text renders in a fallback font | web font not preloaded as `"fontface"` |
 | `BitmapText` renders nothing | the `.fnt` (as `"binary"`) or its image is missing |
 | `TypeError` assigning `loader.onProgress` / `onload` | removed in 20.3; they were never writable — use the `LOADER_*` events |

package/skills/melonjs-performance/SKILL.md

@@ -126,6 +126,11 @@ collapse to one.
 between a hundred trees and a hundred thousand. glTF scenes using
 `EXT_mesh_gpu_instancing` load as an `InstancedMesh` automatically.
 
+It trades per-object control for the draw call: the set gets ONE depth sort key
+and ONE ground shadow, and `removeInstance` swaps the last instance into the
+hole so held indices go stale. Scenery yes; anything the game removes or
+queries one at a time, usually not. See `melonjs-3d` for the decision table.
+
 ## Update loops
 
 - `update(dt)` should **return `true` only when something changed**. Returning

package/skills/melonjs-tilemaps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-tilemaps
-description: "Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers. Covers the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax."
+description: "Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers. Covers the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, level.load, level.load async, await level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax."
 license: MIT
 ---
 
@@ -33,18 +33,37 @@ also skip `src` and pass the map inline via `data` (with `format: "json"` or
 `"xml"`).
 
 `level.load(levelId, options)` accepts `container` (default `game.world`),
-`onLoaded` (default `game.onLevelLoaded`), `flatten` (default `game.mergeGroup`)
-and `setViewportBounds` (default **`true`**). It throws `level <id> not found`
-for an unknown id.
+`onLoaded` (default `game.onLevelLoaded`), `flatten` (default `game.mergeGroup`),
+`setViewportBounds` (default **`true`**) and `async` (default `false`). It throws
+`level <id> not found` for an unknown id — synchronously, in both forms, because
+that is a typo rather than a load failure.
 
 **`level.load` is deferred while the game loop is running.** It calls
-`state.stop()` and finishes the load in a `setTimeout`, so it returns `true`
-before anything is in the world. Do follow-up work from the `onLoaded` callback
-or an `event.LEVEL_LOADED` listener, not on the next line.
+`state.stop()` and finishes the load on a timer, after the current frame, so by
+default it returns `true` before anything is in the world. Two ways to sequence
+work after it:
 
-`level.reload()`, `level.next()`, `level.previous()`, `level.getCurrentLevelId()`
-and `level.levelCount()` round out the namespace. `flatten: false` wraps each
-Tiled object group in its own `Container` named after the group.
+```js
+// await it
+await level.load("map1", { async: true });
+// the world is populated here
+
+// ...or use the callback / event, which fire in both forms
+level.load("map1", { onLoaded: () => this.spawnPlayer() });
+```
+
+`async: true` is the only thing that changes the return value — everything else
+behaves identically, `onLoaded` included. Without it the call returns a boolean,
+so `await level.load("map1")` is not an error and does not await the load:
+`await true` resolves immediately, while the load is still sitting on a timer.
+Pass the flag when you mean to await.
+
+`level.reload()`, `level.next()` and `level.previous()` take the same `async`
+option and resolve the same value they return — so `if (level.next())` becomes
+`if (await level.next({ async: true }))`. Running out of levels reports `false`
+either way rather than throwing. `level.getCurrentLevelId()` and
+`level.levelCount()` round out the namespace. `flatten: false` wraps each Tiled
+object group in its own `Container` named after the group.
 
 ## Spawning entities from Tiled objects
 
@@ -177,7 +196,8 @@ unanimated layer into the offscreen-bake path instead.
 | symptom | cause |
 |---|---|
 | a Tiled object becomes a plain shape with no behaviour | its class/name does not match any registered factory, or it was registered after `level.load` |
-| the world is still empty right after `level.load` | the load is deferred via `setTimeout` while the loop runs — use `onLoaded` / `LEVEL_LOADED` |
+| the world is still empty right after `level.load` | the load is deferred to a timer while the loop runs — `await level.load(id, { async: true })`, or use `onLoaded` / `LEVEL_LOADED` |
+| `await level.load(id)` returned `true` rather than a promise | without `async: true` the call returns a boolean; `await true` resolves immediately and the load has not run yet — pass the flag when you mean to await |
 | `level <id> not found` | the map was never preloaded, or the asset `name` differs from the id passed to `load` |
 | `unknown or invalid resource type` | asset `type` set to `"tmj"` / `"tsj"` — use `"tmx"` / `"tsx"` with the `.tmj` / `.tsj` file |
 | camera will not scroll | `setViewportBounds: false`, or the map was added with `addTo()` (which defaults to `false`) |