melonjs 20.3.0 → 20.5.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, 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: () => {
@@ -134,6 +144,27 @@ model.pause();
 an explicit `loop: false` stops looping. `setCurrentAnimation` **throws** on a
 clip name the asset does not define — check `getAnimationNames()` first.
 
+### 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:
+
+```js
+const boat = new me.GLTFModel(me.loader.getGLTF("boat"), { scale: 40, lit: false });
+boat.setCurrentAnimation("paddle", { loop: true });
+app.world.addChild(boat);
+
+boat.pos.set(steerX, waterLevel);
+boat.depth = travelled;
+boat.rotate(lean - lastLean, AXIS_Z);   // `rotate` is RELATIVE — feed it the delta
+boat.animationspeed = 0.85 + 0.9 * pace; // one authored tempo, many run speeds
+```
+
+Constructing one directly from `loader.getGLTF(name)` is fine and is the way to
+go when the model is a game object rather than a scene — `level.load` is for
+loading a whole scene into the world.
+
 **Vertex skinning is out of scope** — `JOINTS_0` / `WEIGHTS_0` are not read, and
 neither are morph targets. A smoothly-deforming character will not deform. The
 options are: rig it hierarchically instead (separate meshes parented into a
@@ -166,6 +197,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`,
@@ -203,6 +240,117 @@ MTL contributes `Kd` (diffuse tint), `d` / `Tr` (opacity), `Ke` (emissive),
 want it directly. OBJ has no scene graph, no lights, no animation — use glTF for
 anything beyond a single static model.
 
+## Authoring assets for the engine
+
+Notes from modelling props and a rigged character against this loader. They are
+Blender-specific in the API details, general in the traps.
+
+### One clip means one action
+
+glTF names an animation after the **action** it came from, so three objects
+each carrying their own action export as three separate clips — and a game can
+only play one clip at a time, so the other two never move. Put every animated
+object in **one action**, using slots (Blender 4.4+):
+
+```python
+shared = bpy.data.actions.new("paddle")
+for ob in (pivot, shoulder_l, shoulder_r, body):
+    ad = ob.animation_data_create()
+    ad.action = shared
+    ad.action_slot = shared.slots.new('OBJECT', ob.name)
+```
+
+Exporting with the scene/whole-timeline mode does **not** merge per-object
+actions into one clip — it still emits one per action. Slots are the fix.
+
+In Blender 5.x, `action.fcurves` no longer exists; curves live under
+`action.layers[].strips[].channelbags[].fcurves`, and a channelbag identifies
+its slot as `cb.slot.identifier` (there is no `slot_identifier`).
+
+### Never re-parent or join a rig that is mid-pose
+
+Both parenting and joining bake the objects' **current world transforms**.
+Parenting a child while the parent sits in an animated pose writes the inverse
+of that pose into `matrix_parent_inverse`, which silently cancels the animation
+— the part renders rigid while the curves still exist. Detach the action, zero
+the rig, do the surgery, then reattach:
+
+```python
+saved = [(o, o.animation_data.action_slot) for o in animated]
+for ob, _ in saved:
+    ob.animation_data.action = None
+    ob.rotation_euler = (0, 0, 0)
+# ...re-parent / join here...
+for ob, slot in saved:
+    ob.animation_data.action = act
+    ob.animation_data.action_slot = slot
+```
+
+A joined mesh also inherits the **active** object's scale, so joining into a
+box that was scaled to `(0.8, 2.0, 0.1)` leaves a node with that non-uniform
+scale and geometry divided back through it. It renders in the right place but
+skews flat-shaded normals — apply transforms (`rotation=True, scale=True`)
+after joining. Watch for a related trap: setting `ob.scale.x` on a mesh whose
+size was already applied *multiplies* rather than replaces it.
+
+### A model only needs to stay split where something animates it
+
+Every glTF primitive is a draw call. Merge everything static into one mesh and
+keep separate nodes only for the parts a clip actually drives — a boat with a
+rabbit and a paddle went from 28 primitives to 5 that way, with no visible
+change.
+
+### One palette strip beats one material per colour
+
+An `InstancedMesh` is **one geometry and one material**, so a prop that wants
+five colours cannot use five materials. Give the whole model a single material
+whose image is an *N*×1 strip, one pixel per shade, and point each face's UVs
+at a cell centre (`u = (cell + 0.5) / N`, `v = 0.5`) with the sampler set to
+nearest. A whole scene's palette then costs one tiny texture, a merged mesh can
+be twenty colours, and there is nothing to bleed between cells.
+
+Colour-space trap when generating that strip programmatically: Blender's
+`image.pixels` are scene-linear floats, but this export path writes them out
+**verbatim**, so pre-converting sRGB→linear darkens every colour. White is the
+tell — it is the one value identical in both spaces, so if white survives and
+everything else came out dark, that is the bug. Verify by decoding the PNG back
+out of the GLB and comparing bytes to the source palette.
+
+### Feeding an authored mesh into an `InstancedMesh`
+
+`EXT_mesh_gpu_instancing` covers instances authored *in the file*. When the
+game places them itself, take the geometry off the parsed descriptor instead:
+
+```js
+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,
+    texture: palette, textureFilter: "nearest", scale: 40,
+    instanceCount: count,
+});
+```
+
+`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
+origin, base on the floor, and apply transforms before exporting.
+
+One geometry stamped out hundreds of times reads as one object *copied*
+hundreds of times, so vary each instance in its transform. Rotate **after**
+translating, or the instance swings around the group origin instead of turning
+where it stands:
+
+```js
+placement.identity().translate(x / s, -y / s, z / s)
+         .rotate(math.randomFloat(0, Math.PI * 2), AXIS_Y);
+const j = math.randomFloat(0.82, 1.18);
+placement.scale(j, j, j);
+```
+
+Sizing every prop against **one** scale constant, rather than giving each its
+own, keeps "this looks wrong" a modelling question instead of a scaling one.
+
 ## Packaging
 
 A self-contained GLB is one file with nothing to resolve — the safest thing to
@@ -227,13 +375,23 @@ 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 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 |
+| one part of a rig renders rigid while its curves exist | it was re-parented mid-pose, baking the inverse into `matrix_parent_inverse` |
+| a merged mesh lights wrong along one axis | it inherited the active object's non-uniform scale on join — apply transforms |
+| an authored palette comes out uniformly dark, but white is correct | linear values written to a strip that is saved verbatim |
+| `getGLTF(name).nodes[0]` geometry lands in the wrong place | `nodes` is per primitive, each with its own `world`; merge to one primitive and export at the origin |
+| a prop casts no visible shadow | wide and flat-bottomed — the blob is under it; `shadowGroundY` haloes it rather than revealing it |
+| shadows only show on casters near the camera | `shadowGroundY` is on the wrong side — Y-down means the floor is a **greater** y, so a `pos.y - lift` puts the blob inside the caster and the depth test leaves only a hairline ring |
 | 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

@@ -141,6 +141,23 @@ audio.noise({ duration: 0.5, filter: { type: "lowpass", frequency: 800 } });
 `"white"`), `attack`, `pan`, `filter` and `filterSweep`. `gain` defaults to `0.1`
 on both.
 
+### Sequencing: `delay`, not `setTimeout`
+
+Both take `delay` — seconds before the sound starts, scheduled on the **audio
+clock**. That is what builds a multi-part sound: a stinger's second note, an
+explosion's double-tap.
+
+```js
+audio.tone({ freq: 392, duration: 0.12 });
+audio.tone({ freq: 587, duration: 0.18, delay: 0.11 });
+audio.tone({ freq: [784, 1176], duration: 0.75, delay: 0.23 });
+```
+
+Do not reach for `setTimeout` here. A timer fires on the main thread, so a busy
+frame slips the note late and the sequence audibly loses time — the fault is
+easy to blame on the sound design rather than the scheduling. `delay` is
+sample-accurate because the whole envelope is scheduled up front.
+
 Both are **silent no-ops** when there is no WebAudio context — they bail on
 `getAudioContext() === null` rather than throwing. Neither needs the clip to be
 loaded; neither goes through the file-playback path at all.
@@ -195,6 +212,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 +243,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

@@ -78,6 +78,30 @@ whichever of world/screen matches the region — screen for a `floating` region,
 world otherwise. Use the screen pair for anything that *moves* the camera, or
 the drag feeds back on itself.
 
+### In 3D: `Camera3d#worldToScreen`
+
+`worldToLocal` is a 2D camera's offset subtraction — it knows nothing about a
+perspective projection. To pin a label, damage number or marker to a point in a
+3D scene, project it:
+
+```js
+const p = camera.worldToScreen(x, y, z);   // view + projection, divide included
+if (p !== null) {                          // null = at or BEHIND the camera
+    label.pos.set(p.x, p.y);
+}
+```
+
+It returns canvas pixels with the origin top-left and **y down**, which is the
+engine's own 2D draw space — so the result feeds a `floating` renderable or the
+immediate-mode API directly, with no flip.
+
+**Always check for `null`.** A point at or behind the camera (clip `w <= 0`)
+has no honest screen position, and projecting it anyway yields a mirrored
+coordinate that puts your label on the wrong side of the screen. Skip it.
+
+Do not hand-roll this with `Matrix3d` — the perspective divide and the behind-
+camera case are exactly what gets it wrong.
+
 ## Secondary cameras
 
 Cameras are first-class — a minimap is a second camera with `autoResize = false`
@@ -87,6 +111,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
@@ -114,6 +142,27 @@ of them and throw `Invalid geometry for fill/stroke` for anything else.
 noise — including seamless tiling and `asNormalMap` — so you rarely need to ship
 noise PNGs.
 
+Two things to get right when one is animated:
+
+- **Drive it yourself.** `update(dt)` advances the time axis and re-bakes; the
+  engine never calls it. An `animated: true` texture nobody updates is a still
+  image, with no error to say so.
+- **Hand consumers the texture, not its canvas.** Re-baking bumps the
+  `Texture2d`'s `version`, and that bump is what tells the renderer to
+  re-upload. `getTexture()` returns the baked canvas, which carries no version
+  — so a mesh given the canvas shows frame one forever.
+
+Set `seamless: true` for anything tiled by UVs past 1, or every repeat carries a
+visible seam.
+
+**And it still will not animate on a `Mesh`.** Driving `update(dt)` genuinely
+re-bakes the field — the pixels change, the version increments — but the mesh
+path does not pick the new copy up, so a 3D surface textured with an animated
+noise renders frozen while every counter reports success. Verify with a
+checksum of `getTexture()` before concluding the animation is broken; it is the
+upload that is missing, not the bake. For a moving 3D surface, scroll the UVs
+or move the geometry instead.
+
 ## Clipping and masking
 
 ```js

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

@@ -25,6 +25,34 @@ app.viewport.addPostEffect(new VignetteEffect(app.renderer));
 `renderable.shader = …` is **deprecated since 19.2.0**, and its setter destroys
 whatever it replaces. Use `addPostEffect` / `getPostEffect` / `removePostEffect`.
 
+### A camera effect covers the HUD too
+
+A camera's post-effect brackets the **entire** world draw — floating children
+included. So the obvious way to write a full-screen pass also washes over every
+HUD label in that world, which is rarely what you want.
+
+To land a pass *after* the world but *before* the HUD, host the effect on a
+screen-filling floating renderable ordered below the HUD's z instead:
+
+```js
+const quad = new Sprite(0, 0, { image: anyImage });
+quad.anchorPoint.set(0, 0);
+quad.scale(viewW / anyImage.width, viewH / anyImage.height);
+quad.floating = true;                 // its own uv is now screen space
+quad.blendMode = "additive";
+quad.addPostEffect(myEffect);
+world.addChild(quad, HUD_Z - 10);     // BELOW the labels, not above
+```
+
+Two things follow from the quad filling the frame: its own `uv` is screen space
+(so a pass like this needs none of the `screen_uv` / `screen_texture` builtins),
+and the incoming `color` is the quad's own texture, which a body that paints
+from scratch can ignore entirely.
+
+Depth here is easy to get backwards — a higher z draws **later**, i.e. on top.
+Verify it by returning a flat colour from the body for one frame: whatever it
+tints is what the pass covers.
+
 ## Toggle with `enabled`, do not remove
 
 **`removePostEffect()` destroys the effect** — it calls `effect.destroy()` and
@@ -80,7 +108,34 @@ one `@group(3) @binding(0) var<uniform>` struct — so a single `setUniform` cal
 feeds whichever backend is live. `setTime` is a convenience for a `uTime`
 uniform and silently does nothing if the shader does not declare one.
 
-Shaders can also be preloaded as assets with loader type `"shader"`.
+### One effect is one program — prefer preloading, and share
+
+A `ShaderEffect` compiles and links in its **constructor**, and the link is
+checked with `getProgramParameter(LINK_STATUS)` straight after `linkProgram` —
+a blocking call. So the cost is paid on whatever frame the effect is
+constructed, and *n* identical effects cost it *n* times. `clone()` does not
+avoid it: it constructs a new effect and links a new program.
+
+Preload it instead. Loader type `"shader"` takes a `src` **or inline source via
+`data`**, compiles at load time (inside the loading screen), and hands back a
+**shared** instance:
+
+```js
+loader.preload([{ name: "ramp", type: "shader", data: myFragmentBody }]);
+// …then, for every label that wants it:
+label.addPostEffect(loader.getShader("ramp"));
+```
+
+Sharing one instance across renderables is safe *because* the loader sets
+`effect.shared`. Without that flag a renderable's teardown destroys its post
+effects, which would free the program out from under everything else still
+using it. Uniforms live on the effect, so a shared instance means one set of
+uniform values — fine when the look is uniform, and the reason to clone (and
+pay a link) when it is not.
+
+Note this covers **your** effects only. The engine's own mesh/quad shader
+variants are compiled lazily per feature combination on first draw and cannot be
+preloaded — see `melonjs-loading-assets` for the warm-up that covers those.
 
 ### Screen-reading builtins
 
@@ -109,6 +164,43 @@ Two places where a straight port really does differ:
   uniform (initialise it to `1.0`) and multiply vertical offsets by it; the
   renderer feeds `-1` on that path and `+1` everywhere else.
 
+## A ShaderEffect cannot shade a mesh on WebGPU
+
+The single-effect fast path swaps the renderable's program outright instead of
+rendering through an offscreen target. On WebGL that works for a `Mesh` too, so
+a custom mesh shader is a `ShaderEffect` away. **On WebGPU it does not** — the
+renderer says so in its own source, warns once, and then keeps the built-in
+mesh shading.
+
+Nothing throws. The mesh simply draws with its plain texture, which looks like
+a broken shader, a bad binding, or a texture that failed to load — and since
+`video.AUTO` prefers WebGPU where it is available, this is the default outcome
+on most desktops. It cost several hours here: the symptom was a water surface
+rendering flat white, and alpha, bindings, transparency and lighting were all
+eliminated before the backend was.
+
+2D renderables are unaffected: `Sprite`, `Text` and the rest go through the
+quad path, which hosts effects on both backends. So a gradient fill for text,
+or a refraction over a sprite, is fine — it is specifically the mesh path.
+
+If you need a genuinely custom mesh shader that runs everywhere, supply a full
+dual-language `GLShader` rather than a fragment body, and declare the fog
+uniforms yourself (see `melonjs-3d`).
+
+## Extra textures bind in setTexture order
+
+`setTexture("uFoo", …)` assigns bindings **1 and 2** to the first extra
+texture, **3 and 4** to the second, and so on. The WGSL must match:
+
+```wgsl
+@group(3) @binding(1) var uFoo : texture_2d<f32>;
+@group(3) @binding(2) var uFooSampler : sampler;
+```
+
+Copying a two-texture effect and deleting one leaves the survivor declared at
+3/4 while it is bound at 1/2 — the program fails to build and the effect is
+silently dropped.
+
 ## Blend modes
 
 Fourteen modes; thirteen of them are honoured by all three renderers:
@@ -174,4 +266,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
 ---
 
@@ -46,11 +46,107 @@ The type strings are melonJS-specific — this is not a generic loader:
 | `"binary"` | raw data, bitmap font `.fnt` descriptors |
 | `"fontface"` | web fonts (`.ttf`, `.woff`) |
 | `"aseprite"` | Aseprite JSON + image |
-| `"shader"` | GLSL/WGSL shader sources |
+| `"shader"` | GLSL/WGSL shader sources — `src` **or** inline via `data` |
 | `"obj"` / `"mtl"` | Wavefront models and materials |
 | `"gltf"` / `"glb"` | glTF scenes |
 | `"js"` | scripts |
 
+## What belongs in the manifest — and what cannot
+
+Preloading is not only for things with a URL. Three tiers, and the middle one
+is the one people miss.
+
+**1. Assets with a source.** Everything in the type table above. Note `"shader"`
+takes **inline source** as well as a `src`, via the `data` field:
+
+```js
+import { myRamp } from "./myRamp";   // a GLSL fragment body, in your own module
+
+loader.preload([
+    { name: "ramp", type: "shader", data: myRamp },
+]);
+const fx = loader.getShader("ramp");   // shared, already compiled
+```
+
+This matters more than it looks. A `ShaderEffect` compiles its program in its
+**constructor**, and `compileProgram` calls `getProgramParameter(LINK_STATUS)`
+immediately after `linkProgram` — a blocking call that forces the driver to
+finish. So building one during a scene costs that link on the frame it appears,
+and building three identical ones costs it three times. Preloaded as an asset it
+is compiled at load time, behind the loading screen, and the loader hands out a
+**shared** instance (`effect.shared === true`), which is what stops one
+renderable's teardown freeing it out from under the others. `clone()` does NOT
+help here — it constructs a new effect, and therefore links a new program.
+
+**2. Derived assets — build once, after the preload.** Canvases you bake,
+`NoiseTexture2d`, `TextureAtlas`: the loader cannot carry these, but they must
+not be rebuilt per scene either. The renderer's texture cache is keyed by the
+**image object**, so a freshly baked canvas is a brand new GPU texture with a
+new mip chain — rebuild one per stage and a title → play → game-over cycle
+uploads four copies of the same pixels. Build them once after `preload`
+resolves and share them, the way the platformer example builds its
+`TextureAtlas` into a module the scenes read from.
+
+**3. The engine's own shader variants — not preloadable at all.** The mesh
+batcher compiles a program per *feature combination* (lit, instanced, instance
+colours, instance data, fog — fog joins the key), lazily, on the first draw that
+needs it. There is no loader type for these and no API to warm the cache: the
+only lever is to **draw** that combination once while the loading screen is
+still up, then throw the scene away — the compiled programs stay in the
+renderer. Worth doing for a heavy 3D scene, where first-draw linking is easily a
+few hundred ms and lands as a freeze on the first frame of the first level.
+
+```js
+await loader.preload(resources);
+buildScene(app);                       // same geometry the level uses
+await twoFrames();                     // event.GAME_AFTER_DRAW
+removeOnlyWhatYouAdded(app);           // keep the programs, drop the scene
+state.change(state.PLAY);
+```
+
+**It borrows the LOADING stage's world, and that has three teeth**, all learned
+the hard way:
+
+- **Never tear down with `app.world.reset()`.** It clears *every* child of that
+  world, the loading screen's own included, and the screen goes blank for the
+  rest of the load. Snapshot `app.world.children` first and remove only what
+  you added.
+- **Restore anything the warm-up changes that the loading screen shows** — the
+  renderer's `backgroundColor` above all, or the warm-up flashes its own empty
+  first frame.
+- **Under a `Camera3d` it will hide the built-in loading screen, and there is no
+  clean way around it** — see below.
+
+### `DefaultLoadingScreen` lives in the WORLD, not on the screen
+
+The built-in loading screen is written for a `Camera2d`. Its progress bar and
+logo are added with `app.world.addChild(bar, 1)` / `addChild(logo, 2)` and are
+**`floating === false`** — ordinary world-space renderables. They read as an
+overlay only because that stage's world is otherwise empty.
+
+So with `cameraClass: Camera3d`, anything you add to that world is in the scene
+*with* them, and a 3D scene simply swallows them: the depth buffer puts terrain
+in front of a bar sitting at z = 1. What does NOT rescue it, all tried:
+
+- **Raising their `z`** — for a mesh on the `Camera3d` path `pos.z` IS world
+  depth, so the scene's own z values are geometry, not layering, and the bar
+  still loses to the depth test.
+- **`moveToTop()`** — it early-returns for a child already at index 0, which the
+  loading screen's children always are, having been added before anything else.
+  It silently does nothing.
+- **Flipping them to `floating = true`** for the duration — the scene still
+  covers them.
+
+If you want a warm-up (or any 3D behind a loading screen), write your own
+loading stage and draw its progress UI as **floating** renderables over the
+scene. That is also the nicer result: the player watches the level assemble
+instead of a logo. Budget it as real work, not a one-liner — and weigh it
+against what the warm-up actually saves.
+
+One more limit: a warm-up only covers the combinations it actually draws.
+Renderables the real level has and the warm-up does not will still link on
+entry.
+
 ## Two conventions that produce 404s
 
 **Audio `src` is a directory.** The loader appends the asset name plus each
@@ -138,6 +234,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 +268,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 |