melonjs 20.2.0 → 20.3.0

package/skills/melonjs-20-migration/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: melonjs-20-migration
+description: "Use this skill when writing melonJS code that may be based on pre-20.x knowledge, when migrating a game from melonJS 19.x or earlier, or when an API you expected does not exist. Covers the mandatory async Application.init(), the WebGL 2 baseline and WebGPU backend, renderable post effects replacing the shader property, and the deprecated exports still present. Triggers on: migration, upgrade, melonJS 19, me.game, me.video.init, renderable.shader, Compositor, CanvasTexture, me.Math, deprecated."
+license: MIT
+---
+
+# Migrating to melonJS 20.x
+
+> What changed in melonJS 20.x, and which older APIs are gone, deprecated, or
+> renamed. Read this before writing melonJS code from memory — much of what is
+> published about melonJS predates 20.0.
+
+**Why this skill exists:** most melonJS material in circulation describes 19.x or
+earlier. Code written from that knowledge looks correct and fails at runtime.
+The items below are ordered by how likely they are to be reproduced from memory.
+
+## 1. `Application.init()` is mandatory and asynchronous
+
+Since 20.0, constructing an `Application` no longer initialises it.
+
+```js
+// ✗ pre-20.x — the constructor called init(width, height, options) for you
+const app = new Application(800, 600, { parent: "screen" });
+app.world.addChild(sprite);          // added, but nothing ever renders
+
+// ✓ 20.x
+const app = new Application(800, 600, { parent: "screen" });
+await app.init();                    // REQUIRED
+app.world.addChild(sprite);
+```
+
+`init()` is async because acquiring a WebGPU device is async. There is no
+synchronous alternative, and no automatic fallback that papers over the missing
+call. Nothing that then breaks names it: the constructor still builds
+`app.world`, so children can be added and simply never draw — no canvas is
+appended, the app never subscribes to the frame tick, and `app.renderer` /
+`app.viewport` stay `undefined` — while constructing a `Sprite` or `Text` first
+throws a `TypeError` on the unset global `game` instead.
+
+The signature changed too: 19.x took `init(width, height, options)`, 20.x takes
+none, and anything passed is ignored (settings come from the constructor).
+
+**`video.init(...)` no longer exists.** The `video` module now exports only the
+four renderer constants (`AUTO`, `CANVAS`, `WEBGL`, `WEBGPU`) — there is no
+`init` on it to call. Any code shaped like `me.video.init(800, 600, {...})` is
+from a removed API. Build an `Application` and await `init()`.
+
+Note that `import * as me from "melonjs"` still works, so `me.Sprite` style is
+fine. It is the *globals bootstrap* that is gone, not the namespace import.
+
+## 2. Post effects replaced the `shader` property
+
+`renderable.shader = …` is **deprecated since 19.2.0**. Use the post-effect API:
+
+```js
+// ✗ deprecated
+mySprite.shader = new ShaderEffect(app.renderer, glslBody);
+
+// ✓
+mySprite.addPostEffect(new ShaderEffect(app.renderer, glslBody));
+```
+
+Related trap: **`removePostEffect()` destroys the effect** — and so does
+assigning `renderable.shader`, which destroys whatever it replaces. Only an
+effect carrying `shared = true` is spared. To turn one off temporarily, toggle
+`effect.enabled` instead: remove-and-re-add hands you back an object whose GPU
+resources have already been freed.
+
+## 3. WebGL 2 is the baseline; WebGPU is the default attempt
+
+`video.AUTO` now tries **WebGPU → WebGL 2 → Canvas**. WebGL 1 is gone.
+
+Consequences:
+
+- Which backend runs is a runtime fact. Do not write code that assumes WebGL.
+- Custom shaders can carry both GLSL and WGSL in one asset, so one effect runs
+  on either GPU backend.
+- Features needing a programmable pipeline are inert on Canvas and warn once
+  rather than throwing.
+
+## 4. Deprecated exports still present
+
+These resolve but should not be used in new code:
+
+| deprecated | since | use instead |
+|---|---|---|
+| `CanvasTexture` | 17.1.0 | `CanvasRenderTarget` |
+| `Compositor` | 18.1.0 | `WebGLBatcher` |
+| `PrimitiveCompositor` | 18.1.0 | `PrimitiveBatcher` |
+| `QuadCompositor` | 18.1.0 | `QuadBatcher` |
+| `Math` (capitalised) | 18.0.0 | `math` (lowercase) |
+| `device.requestFullscreen` / `exitFullscreen` | 19.7.0 | `app.requestFullscreen()` / `app.exitFullscreen()` |
+| `renderable.shader = …` | 19.2.0 | `addPostEffect()` |
+| `Entity` | 18.1.0 | `Sprite` / `Renderable` + a `Body` |
+| `loader.onload` / `onProgress` / `onError` | 18.2.0, **removed 20.3** | the `LOADER_*` events, or `preload(assets, onloadcb)` |
+| `response.overlap` / `overlapN` / `overlapV` | — | `response.depth` / `response.normal` |
+| `setLineWidth()` | 17.3.0 | the `lineWidth` property |
+
+Two of these deserve emphasis:
+
+- **`Entity`** is still exported, so code using it compiles and runs while being
+  the wrong shape for 20.x. Compose a `Sprite`/`Renderable` with a `Body`
+  instead.
+- **The capitalised `Math`** shadows the global `Math` if imported carelessly.
+  `me.Math.random()` from older docs resolves to the deprecated re-export.
+
+## 5. The global `game` is not the modern shape
+
+`game` is still exported, but since 20.0 it names the most recently
+**initialized** `Application` and is `undefined` until the first `init()`
+resolves — so anything reading it at module scope gets `undefined`. Take the
+`Application` instance as a parameter instead: `Stage#onResetEvent` and
+`onDestroyEvent` are handed it, and any renderable can reach it through
+`parentApp`.
+
+## 6. Node and SSR
+
+melonJS imports cleanly under Node — useful for isomorphic apps and for tooling.
+It has **no runtime dependencies** as of 20.3. Do not add polyfills for
+`globalThis`, `String.trimStart` or `String.trimEnd`: the published bundle
+targets ES2022, so every environment that can parse it already has them.
+
+## 7. Browser support
+
+The published bundle targets **ES2022** and uses private class members. A browser
+that predates that cannot parse the file at all — it fails at load, not when a
+feature is used. Transpile if you need older browsers, and note that transpiling
+handles *syntax* only: built-in methods need separate polyfills, which a
+bundler's `target` setting will never add.
+
+## The shipped examples are not all current
+
+The examples in this repository are the best reference for how melonJS is
+assembled, but a few contain stale comments or legacy calls. Do not learn these
+from them:
+
+- `webgpu/` has a comment claiming *"`video.AUTO` never selects the WebGPU
+  backend"*. That is pre-20 leftover — AUTO tries WebGPU **first**. The code is
+  right; the comment is wrong.
+- Several examples assign `viewport.shader = …` / `sprite.shader = …`, which is
+  deprecated. `addPostEffect()` is current.
+- Five files set `this.z = Number.POSITIVE_INFINITY` on a HUD. That property
+  does not exist; those HUDs draw on top only because they are added last.
+- `platformer/entities/player.ts` reads `response.overlapV`, the deprecated
+  field. Use `response.depth` / `response.normal`.
+- Particle speeds tuned before 20.2 look wrong now: the particle transform fix
+  changed how far a burst travels, and emitters were retuned upward to match.
+
+## Checklist when code "should work" but doesn't
+
+1. Is `await app.init()` there?
+2. Is the code assuming WebGL when it might be running on Canvas or WebGPU?
+3. Is it using `renderable.shader =` instead of `addPostEffect()`?
+4. Is it importing a deprecated symbol from the table above?
+5. Is it referencing a global `game`?
+
+## Related skills
+
+- `melonjs-getting-started` — the correct 20.x bootstrap in full
+- `melonjs-renderables` — post effects, pointer events and custom draw code

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

@@ -0,0 +1,226 @@
+---
+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."
+license: MIT
+---
+
+# 3D and 2.5D in melonJS
+
+> melonJS is a 2D engine that grew a real 3D tier: perspective cameras, meshes,
+> instancing, glTF scenes and 3D lights. Most of what a model "knows" about 3D
+> graphics comes from the OpenGL convention, and **melonJS's is the inverse**.
+> Read the conventions section before writing any 3D code.
+
+## Coordinate conventions — the inverse of OpenGL
+
+This is the single most important thing on this page.
+
+| | melonJS | OpenGL convention |
+|---|---|---|
+| vertical | **Y-down** — higher `y` is *lower* on screen | Y-up |
+| depth | **+Z forward** — higher `z` is *farther* away | −Z forward |
+
+Rotations are extrinsic XYZ. `Camera3d` exposes two of the three: `camera.pitch`
+(X, look up/down) and `camera.yaw` (Y, look left/right). **There is no `roll`**;
+neither camera applies a Z-axis bank to the view, so assigning one does nothing.
+
+The payoff is that 2D code translates directly — anywhere you used `pos.x` /
+`pos.y`, add `pos.z` and the maths still holds. The cost is that every
+OpenGL-shaped instinct is backwards.
+
+**Consequence that bites immediately:** "behind everything" is the *largest*
+depth when the camera looks along +Z. Put a backdrop on the wrong side and it
+either paints over the whole scene (it is nearer than everything else) or
+disappears without trace (it falls in front of the near plane and the GPU clips
+it). Which sign means "far" depends on which side the camera sits, so check the
+camera before picking a backdrop depth.
+
+glTF assets are authored Y-up right-handed. `level.load` converts them by
+rotation (`rightHanded: true` is its default), so you do not apply a flip
+yourself. The **`Mesh` constructor defaults `rightHanded` to `false`**, which
+bridges by mirroring instead — geometry you hand to a `Mesh` directly comes in
+flipped left/right unless you pass `rightHanded: true`. See
+`melonjs-3d-assets`.
+
+## Opting in
+
+3D starts with the camera class, and nothing else has to change. Set it once on
+the `Application`:
+
+```js
+import { Application, Camera3d } from "melonjs";
+
+const app = new Application(1024, 768, {
+    parent: "screen",
+    cameraClass: Camera3d,      // ← the opt-in
+});
+await app.init();
+```
+
+That flips the world's sort to `"depth"`, switches the broadphase to a 3D index,
+and renders sprites and meshes with perspective projection. `Camera3d` extends
+`Camera2d`, so follow, fade, shake and post effects all still work.
+
+Per-stage opt-in also works, which is useful when the loading screen is 2D:
+
+```js
+class GameStage extends Stage {
+    constructor() {
+        super({ cameras: [new Camera3d(0, 0, 1024, 768, { fov: Math.PI / 3 })] });
+    }
+}
+```
+
+## Camera traps
+
+- **There is no sky.** The frame clears to `renderer.backgroundColor` (opaque
+  black unless the renderer was created transparent), and `world.backgroundColor`
+  clears over it when you set one — both are flat colours. Anything more is a
+  backdrop renderable, screen-fixed or placed at a far depth.
+- **Set the clip planes for your scene scale.** Defaults are near 0.1 / far 1000.
+  Objects beyond the far plane clip or project with bad w-divides; a `near` that
+  is too small wastes depth precision and distant props z-fight. Use
+  `camera.setClipPlanes(near, far)`.
+- **`camera.pos.set(x, y)` is 2-argument and zeroes z.** Use `camera.depth` —
+  the documented z accessor — or assign `pos.x`/`pos.y` individually.
+
+## Depth sorting
+
+Under `Camera3d` the world sorts on `"depth"` **every frame** (recursively), so
+unlike 2D you *can* assign `depth` after `addChild` and it will reorder. That is
+the one place where the usual z-ordering rule is relaxed — see
+`melonjs-renderables` for the 2D rules, which still apply everywhere else.
+
+You will often *have* to. A `Container` has `autoDepth: true` by default, so
+`addChild(child)` with no explicit z **overwrites `pos.z` with the child's
+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.
+
+## Meshes
+
+```js
+const cube = new Mesh(x, y, {
+    model: "cube",          // a preloaded OBJ name — no built-in primitives
+    texture: atlas,         // TextureAtlas, image, or a preloaded image name
+    width: 64, height: 64,
+    cullBackFaces: true,    // the default
+    lit: true,
+});
+```
+
+**A mesh pivots about its model origin `(0, 0, 0)`, not an anchor point.** Under
+`Camera3d` it opts out of the anchor offset entirely, so `anchorPoint` is inert
+there — place the origin where you want the pivot at authoring time, or nest the
+mesh under a transformed parent. The anchor is only honoured on the legacy
+2D-camera path.
+
+**`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.
+
+## Sprite3d and billboards
+
+`Sprite3d` is the 2.5D workhorse: a flat sprite living at a real depth, with
+`billboard` controlling how it faces the camera.
+
+| `billboard` | behaviour |
+|---|---|
+| `false` (default) / `"none"` | no rotation — a flat plane in the world |
+| `true` / `"cylindrical"` | yaws to face the camera, stays upright (characters, trees) |
+| `"spherical"` | always fully faces the camera (particles, impostors) |
+
+`"cylindrical"` is what you want for paper-thin characters in a 2.5D game.
+Billboarding needs a `Camera3d` drawing the frame; under a 2D camera the quad
+renders fixed-orientation. **Any other string falls through to the spherical
+branch**, so a guessed value like `"upright"` silently gives you spherical.
+
+## Lighting
+
+`Light3d` takes **one argument — the options object** (it has no `x, y, z`
+pair; a light carries its own `position`). Types are `"directional"` (the
+default), `"ambient"`, `"point"` and `"spot"`.
+
+```js
+world.addChild(new Light3d({ type: "directional", direction: [0.3, 1, 0.2] }));
+world.addChild(new Light3d({ type: "ambient", intensity: 0.3 }));
+```
+
+Use **both halves**: with a key light but no ambient, the shadow side of a mesh
+goes black. With no `Light3d` in the world at all, a `lit: true` mesh falls back
+to a white ambient and renders fullbright — indistinguishable from unlit, which
+is why "I added `lit: true` and nothing changed" is the usual first report.
+
+Other defaults worth knowing: `intensity` 1, `color` white, `range` 1000 (point
+and spot, a stylised quadratic falloff, not inverse-square),
+`innerConeAngle` 0 and `outerConeAngle` π/4 (spot).
+
+**`Light2d` is 2D-only** and produces visible artifacts under perspective
+projection. Do not combine it with `Camera3d`.
+
+Ground shadows are **on by default** (the `castGroundShadow` application
+setting), and need a GPU backend and a `Camera3d`. As a blanket default they
+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.
+
+## glTF / GLB scenes
+
+Loaded through the same level director as everything else:
+
+```js
+await loader.preload([{ name: "diorama", type: "glb", src: "data/diorama.glb" }]);
+level.load("diorama", { scale, castGroundShadow, shadowGroundY, onLoaded });
+```
+
+`.obj` / `.mtl` are also supported loader types.
+
+`melonjs-3d-assets` covers the rest: every `level.load` option, which material
+features are imported, imported lights and their intensity units, node-TRS
+animation (and the skinning that is out of scope), and OBJ/MTL.
+
+## Requires a GPU backend
+
+The whole 3D tier needs WebGPU or WebGL 2. The Canvas renderer has no depth
+buffer, no perspective path and no `drawMesh`, so a `Camera3d` scene does not
+render correctly there — usually a black canvas. `Light3d` and shader effects
+are inert too. A `Mesh` under a *2D* camera still renders, CPU-projected by
+painter's algorithm and unlit.
+
+`Application` does warn: constructing with a `cameraClass` whose
+`defaultSortOn` is `"depth"` on a renderer with no depth buffer logs a
+`console.warn`. But `video.AUTO` falls back silently to Canvas, so the strong
+gate is to ask for a GPU backend by name — `renderer: video.WEBGL` (or
+`video.WEBGPU`) makes `await app.init()` reject instead of misrendering:
+
+```js
+const app = new Application(1024, 768, {
+    parent: "screen",
+    renderer: video.WEBGL,      // init() rejects if WebGL 2 is unavailable
+    cameraClass: Camera3d,
+});
+await app.init();
+```
+
+To branch rather than fail, read `app.renderer.supportsDepthBuffer` after
+`init()`.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| 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 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"` |
+| an object jumps to the camera plane | `Vector3d.set(x, y)` / `camera.pos.set(x, y)` zeroed its z |
+| lighting looks wrong under a 3D camera | `Light2d` used instead of `Light3d` |
+
+## Related skills
+
+- `melonjs-renderables` — the 2D z-ordering rules, anchors, custom draw
+- `melonjs-getting-started` — Application settings and the renderer fallback

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

@@ -0,0 +1,239 @@
+---
+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."
+license: MIT
+---
+
+# Loading 3D assets
+
+> glTF/GLB is the primary path for 3D content, and it goes through the **level
+> director** rather than the world directly: `level.load("scene")`, the same call
+> a Tiled map uses. OBJ/MTL is the simpler path for a single static model.
+
+## Loading a glTF/GLB scene
+
+```js
+await loader.preload([
+    { name: "diorama", type: "glb", src: "data/scenes/diorama.glb" },
+]);
+
+level.load("diorama", { scale: 50 });
+```
+
+`type: "gltf"` (JSON plus external buffers) and `type: "glb"` (single binary)
+are both loader types. A self-contained GLB is the better shipping format — one
+request, nothing to resolve relatively.
+
+The scene loads under whatever camera the stage has; view it under a `Camera3d`
+or it renders flat. See `melonjs-3d` for the camera.
+
+### `level.load` options for glTF/GLB
+
+| option | default | what it does |
+|---|---|---|
+| `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 |
+| `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 |
+| `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 |
+
+`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:
+
+```js
+level.load("diorama", { scale: 50, onLoaded: () => {
+    const sun = app.world.getChildByName("Sun")[0];   // note: returns an array
+    sun.intensity = 2;
+}});
+```
+
+## `rightHanded` — and the default that differs between the two APIs
+
+glTF is authored **Y-up, right-handed**; melonJS is **Y-down, +Z forward**.
+There are two ways to bridge that, and they are not equivalent:
+
+- a **rotation** — preserves chirality, matches the authoring tool
+- a **mirror** (negate Y only) — flips the scene left/right
+
+`level.load` defaults `rightHanded: true`, so a scene loaded through the level
+director comes in correctly. **The `Mesh` constructor defaults it to `false`**,
+so glTF or OBJ geometry you feed to a `Mesh` yourself comes in mirrored unless
+you pass `rightHanded: true`. A model that is subtly wrong — text backwards, a
+character's gear on the wrong side — is this and nothing else.
+
+Do not add a flip of your own on top; two corrections cancel back to wrong.
+
+## Materials — what actually arrives
+
+The importer covers a deliberate subset:
+
+- `pbrMetallicRoughness` **base colour texture and factor**
+- 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`
+
+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.
+
+**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"`.
+
+## 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.
+
+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
+light is normalised to intensity 1 by default. To keep the *ratios* the artist
+set, scale instead of normalising:
+
+```js
+// a 1000-lux sun lands at 1, a 500-lux fill lands at 0.5
+level.load("diorama", { scale: 50, lightIntensityScale: 0.001 });
+```
+
+Pass `lights: false` to manage lighting yourself.
+
+## Animation
+
+Node-TRS animation **is** supported: translation, rotation and scale channels,
+the rigid hierarchical animation used by blocky/low-poly character packs. An
+animated asset instantiates as a single `GLTFModel` keeping the node hierarchy
+intact, with an API deliberately mirroring `Sprite`. The model carries the asset
+name, which is how you get hold of it after loading:
+
+```js
+const model = app.world.getChildByName("hero")[0];   // the GLTFModel
+
+model.getAnimationNames();                           // ["idle", "walk", ...]
+model.setCurrentAnimation("walk", { loop: true, speed: 1, onComplete });
+model.setCurrentAnimation("jump", { next: "idle" }); // chain
+model.isCurrentAnimation("walk");
+model.play();
+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.
+
+**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
+node tree), use `Sprite3d` billboards, or use the Spine plugin for 2D skeletal
+work.
+
+## Instancing
+
+A node using `EXT_mesh_gpu_instancing` loads as an `InstancedMesh` — one draw
+call for every copy, which is the difference between a hundred trees and a
+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.
+
+## Ground shadows
+
+```js
+level.load("diorama", { scale: 50, castGroundShadow: true, shadowGroundY: 0 });
+```
+
+`castGroundShadow` is tri-state: set it and it overrides the application setting
+for this scene in both directions; omit it and the scene inherits — and that
+setting is `true` by default, so shadows are already on. As a scene-wide opt-in
+it skips nodes with no vertical extent — a ground plane is exactly that, and
+shadowing it with itself smears a blob across the whole floor. Blob shadows need
+a GPU backend and a `Camera3d`; nothing is drawn on the 2D-camera or Canvas
+paths.
+
+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.
+
+## OBJ/MTL
+
+A different shape entirely: OBJ produces raw geometry you hand to a `Mesh`,
+not a scene. Preload the two files and name them in the `Mesh` settings — the
+`model` and `material` names are independent, the same name for both is just a
+convention:
+
+```js
+await loader.preload([
+    { name: "fox", type: "obj", src: "models/fox.obj" },
+    { name: "fox", type: "mtl", src: "models/fox.mtl" },
+]);
+
+const mesh = new Mesh(400, 300, {
+    model: "fox",
+    material: "fox",        // texture resolved from the material's map_Kd
+    width: 200,
+    height: 200,
+    rightHanded: true,      // the Mesh default is false — see above
+});
+world.addChild(mesh);
+```
+
+**The MTL loader fetches the textures it references itself** — `map_Kd` and
+`map_d` 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 unless you mean
+that.
+
+MTL contributes `Kd` (diffuse tint), `d` / `Tr` (opacity), `Ke` (emissive),
+`Ks` + `Ns` (specular highlight), `map_Kd` (diffuse texture) and `map_d`
+(per-texel opacity). Normal and specular *maps* are not supported.
+`loader.getOBJ(name)` and `loader.getMTL(name)` return the parsed data if you
+want it directly. OBJ has no scene graph, no lights, no animation — use glTF for
+anything beyond a single static model.
+
+## Packaging
+
+A self-contained GLB is one file with nothing to resolve — the safest thing to
+ship. External references still work in both formats: `.bin` buffers and image
+`uri`s are resolved **relative to the asset's own URL** (a GLB with an external
+texture loads as-shipped). But an external file that 404s rejects the parse, so
+the whole asset fails to load rather than arriving partially — no untextured
+fallback. Note that `loader.setBaseURL("*", …)` deliberately skips `gltf`,
+`glb`, `obj` and `mtl` for this reason; set those types individually if you
+need a prefix.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| model mirrored — text backwards, gear on the wrong side | `Mesh` defaults `rightHanded` to `false`; pass `true` |
+| model upside down | a manual axis flip on top of the loader's conversion |
+| scene is enormous or invisibly small | `scale` left at 1 against a metre-scale export |
+| 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 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 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-lighting` — how `Light3d` behaves once imported
+- `melonjs-loading-assets` — the loader, asset types and base URLs
+- `melonjs-plugins` — the Spine plugin, for skeletal characters