melonjs 20.13.0 → 20.14.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, Trail3d, ribbon, exhaust trail, 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, setBasis, getBasis, lookAt, up vector, gimbal, slerp, great circle, turn a direction."
+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, Trail3d, ribbon, exhaust trail, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, shadowGroundPoint, lit, emissive, specular, shininess, normalMap, alphaCutoff, depthTest, vertexColors, worldToScreen, followOffset, setBasis, getBasis, lookAt, up vector, gimbal, slerp, great circle, turn a direction."
 license: MIT
 ---
 
@@ -69,7 +69,8 @@ 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.
+`Camera2d`, so follow, fade, shake and post effects all still work (follow with
+a difference, see the camera traps).
 
 ### Keep the camera, do not fish it back out
 
@@ -193,8 +194,15 @@ class GameStage extends Stage {
   sense to `lookAt`'s, and one negation apart.
 - **`worldToLocal` does not project.** It is a 2D camera's offset subtraction.
   To pin a label or marker to a point in the scene use
-  `camera.worldToScreen(x, y, z)`, which applies the projection and returns
+  `camera.worldToScreen(point, out?)`: it takes a `Vector3d`, applies the
+  projection and returns a `Vector2d` in the camera's pixels (y down), or
   `null` behind the camera. See `melonjs-camera-and-drawing`.
+- **`follow()` tracks exactly.** Under a `Camera3d` the camera sits at the
+  target's position plus `followOffset` (world space, set with
+  `camera.setFollowOffset(x, y, z)`) every frame. The 2D follow's axis,
+  deadzone and damping are not applied. For a damped chase camera, leave the
+  target unset and move the camera yourself (`math.damp`, or `slerp` below for
+  its facing).
 
 ## Where an up vector earns its keep
 
@@ -299,6 +307,11 @@ 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.
 
+A `Container`'s depth carries to its children when they are drawn, as it
+already did for culling and the sort: a group at depth 400 draws its sprites
+and meshes 400 units further away. One more reason to give containers an
+explicit z.
+
 **`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
@@ -327,8 +340,9 @@ Meshes render in two phases. The **opaque pass** writes depth in sort order; the
 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.
+blending off, so a faded mesh that stays there (as every one did before 20.4)
+comes out **darkened toward black** rather than see-through — the background
+contributes 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"`.
@@ -376,8 +390,9 @@ const halo = new Sprite3d(0, 0, {
 });
 ```
 
-Honoured in the transparent pass on both GPU backends; the Canvas renderer has
-no depth buffer and ignores it.
+Honoured in the **transparent pass only**, on both GPU backends: a mesh drawn
+in the opaque pass ignores it, so pair it with `transparent: true` as above.
+The Canvas renderer has no depth buffer and ignores it.
 
 Blending uses the renderable's existing `blendMode`, so a glow is one property.
 The advanced modes (`"overlay"`, `"difference"`, and the rest that need a
@@ -482,6 +497,8 @@ the built-in ones:
 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
+uniform vec4 uFogHeight;  // height falloff: xyz = falloff x world-up axis,
+                          // in VIEW space; w = pre-baked altitude term
 ```
 
 Your vertex stage computes the distance itself — `length((uViewMatrix *
@@ -490,6 +507,12 @@ 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.
 
+`uFogHeight` is only needed to honour `heightFalloff`, and is fed only to a
+program that also declares `uFogParams`. The engine's own shaders multiply the
+distance by `uFogHeight.w * (exp(k) - 1.0) / k`, with `k = dot(uFogHeight.xyz,
+viewPos)` and the factor taken as `uFogHeight.w` when `k` is near zero. Leave it
+out and your mesh fogs uniformly at every altitude.
+
 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.
@@ -510,7 +533,32 @@ const cube = new Mesh(x, y, {
 `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.
+2D-camera path. `Sprite3d` is the exception: it bakes its `anchorPoint` into
+the quad's vertices, so a `"bottom"` anchor works under either camera.
+
+### Material settings
+
+What a material file can state is also a setting, so a hand-built mesh gets the
+same surface. All but `baseColorFactor` are GPU-only; the Canvas renderer
+ignores them.
+
+| setting | what it does | needs |
+|---|---|---|
+| `emissive: [r, g, b]` | self-illumination added on top, 0..1 (above 1 for an HDR glow) | nothing, lit or unlit |
+| `specular: [r, g, b]` + `shininess` | a highlight; `shininess` 0, the default, turns it off however bright `specular` is | `lit`, a `Light3d`, normals |
+| `normalMap` | tangent-space relief, a loader key or image (see Lighting below) | `lit` and a `Camera3d` |
+| `alphaCutoff` | discard texels below this alpha: foliage, fences | nothing |
+| `alphaMap` | per-texel opacity, multiplied in before the cutoff | a non-zero `alphaCutoff` |
+| `baseColorFactor` | a LINEAR colour, encoded into `tint` (see `melonjs-3d-assets`) | nothing |
+
+`emissive`, `specular` and `shininess` can be changed after construction too;
+`setBaseColorFactor()` is the method form of the last row.
+
+A `ShaderEffect` can shade a mesh as well: `mesh.addPostEffect(fx)` splices it
+into the mesh shader as a colour hook on both GPU backends, so the mesh keeps its
+placement, cutout, lighting and fog. A few builtins are unavailable there, and an
+`InstancedMesh` cannot host one; both warn once. See
+`melonjs-effects-and-shaders`.
 
 ### InstancedMesh, and when it is the wrong tool
 
@@ -578,9 +626,9 @@ 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.
+**A lit mesh with no normals used to render fullbright** (before 20.4), which
+looks like the lighting is broken rather than absent. If an older scene suddenly
+picks up shading, that is why.
 
 ## Colouring a mesh
 
@@ -591,7 +639,7 @@ There are four levels, and picking the wrong one is the usual reason a colour
 |---|---|---|
 | whole object | `mesh.setTint("#ff8800")`, or `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 material | a multi-material OBJ + MTL | a model whose parts differ: each `Kd` is baked into the vertex colours, and only a different `map_Kd` costs a draw (one per `textureGroups` entry) |
 | 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
@@ -629,10 +677,11 @@ 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.
+`alpha` hides a mesh as it hides anything else: below 1/255 the draw is skipped.
+A fractional `alpha` fades it, through the transparent pass described under
+Transparency above, which needs a `Camera3d` on a GPU backend. Without that pass
+(a 2D camera on a GPU backend, or `transparent: false`) the mesh path does not
+blend, and a faded mesh darkens instead of turning see-through.
 
 ## Moving a mesh in 3D
 
@@ -649,6 +698,12 @@ rotates about that axis. Both write to `currentTransform`, a **`Matrix3d`**,
 which `Mesh` folds into its model matrix — so orienting a mesh costs a matrix
 update, not new geometry.
 
+Under a `Camera3d` on a GPU backend the geometry is uploaded once and redrawn
+from the GPU, so moving, turning, scaling or re-tinting needs no signal. Editing the geometry
+itself does: after writing into `originalVertices`, the UVs, normals or
+indices, set `mesh.needsUpdate = true`, or the change shows under a 2D camera and
+not under the 3D one.
+
 This matters most for the case it is least obvious for: a horizontal plane.
 `Sprite3d` with `billboard: false` is a quad in the sprite plane — upright —
 and the way to lay one flat (water, a road, a shadow decal) is to rotate it a
@@ -657,13 +712,14 @@ geometry instead is tiling: a `Sprite3d` bakes its UVs 0..1 from its atlas
 frame, so a surface that needs `textureRepeat` across many world units still
 wants an explicit `vertices`/`uvs` mesh.
 
-## The mesh pass is opaque
+## The opaque pass does not blend
 
 Worth stating plainly, because the symptom does not look like a blending
-problem: **the mesh pass disables blending**. A soft-edged texture — a glow, a
-sun, a halo, anything with a gradient alpha — composites as a hard-edged disc
-with a grey rim, which reads as a broken texture rather than as a missing
-feature.
+problem: **the opaque mesh pass disables blending**, and a draw goes there
+unless its alpha is fractional or it says `transparent: true`. A soft-edged
+texture — a glow, a sun, a halo, anything with a gradient alpha — drawn at full
+opacity composites as a hard-edged disc with a grey rim, which reads as a broken
+texture rather than as a missing feature.
 
 `transparent: true` routes it through the transparent pass, and `blendMode:
 "additive"` on top of that makes a light source add to the sky instead of
@@ -741,11 +797,13 @@ world.addChild(new Light3d({ type: "spot", position: torch.pos, range: 400 }));
 ```
 
 `direction` and `position` take an `[x, y, z]` array **or** a `Vector3d`, and
-`color` takes a `Color`, a CSS string or an `[r, g, b]` array — so a value the
-game already holds can go straight in. Each is read, not retained: move your
-vector afterwards and the light stays where it was.
+`color` takes a `Color`, a CSS string or an `[r, g, b]` array in **0..1** (the
+glTF convention, not 0..255) — so a value the game already holds can go straight
+in. The vectors are read, not retained: move your vector afterwards and the
+light stays where it was. A `Color` is kept as given, so mutating it recolours
+the light.
 
-Two things still bite, both silently:
+Three things still bite, all silently:
 
 - `new Light3d(0, 0, {…})` — the constructor takes **options alone**. JavaScript
   drops the extra arguments, so `options` becomes the number `0` and every
@@ -766,6 +824,10 @@ Two things still bite, both silently:
 
   `position` follows the same convention: a lamp above the floor has a
   **smaller** y than the floor.
+- **`position` and `direction` are in world coordinates, wherever the light
+  sits in the tree.** A `Light3d` added under a container does not move or turn
+  with it, and its own `pos` is never read. To carry a lamp with a car or a
+  torch, write the object's world position into `light.position` each frame.
 
 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
@@ -776,6 +838,10 @@ 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).
 
+Up to **32** directional, point and spot lights shade a mesh; ambient lights are
+summed into one fill and do not count. Lights past the 32nd are dropped without
+a warning.
+
 **`Light2d` is 2D-only** and produces visible artifacts under perspective
 projection. Do not combine it with `Camera3d`.
 
@@ -858,7 +924,10 @@ the fade clamps to full strength and the blob never fades at all; and a point
 on the wrong side of the caster reads as a large height, so the blob
 disappears outright rather than thinning to a ring the way a backwards
 `shadowGroundY` does. It is also the one shadow setting that THROWS rather
-than clamping or hiding: a non-finite component is rejected on the spot.
+than clamping or hiding: a non-finite component is rejected on the spot. A
+two-component point (a `Vector2d`, a 2-element array) does not throw: its z
+silently becomes 0. The point is copied, so moving the vector you passed moves
+nothing; assign it again.
 
 The blob is an ellipse sized to the caster's own footprint and placed at the
 caster's x/z, or at `shadowGroundPoint` when one is set. So a tall or narrow object (a character, a tree, a pickup) shows
@@ -1028,7 +1097,9 @@ level.load("diorama", {
 An **animated** asset instantiates as a `GLTFModel`, which is a game object as
 much as a scene: construct it straight from the parsed descriptor, and place it
 with `pos` / `depth` / `rotate` / `scale` like any other renderable — the
-placement drives the whole rig and composes with the playing clip.
+placement drives the whole rig and composes with the playing clip, and still
+applies while the clip is paused, finished or was never played. `scale()`
+multiplies the `scale` option it was built with.
 
 ```js
 const model = new GLTFModel(loader.getGLTF("boat"), { scale: 40, lit: false });
@@ -1048,14 +1119,20 @@ 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.
+The 3D tier is built for WebGPU or WebGL 2: target one of them. The Canvas
+renderer has no depth buffer and no perspective path, so a `Camera3d` scene
+does not render there — usually a black canvas. `Light3d` and shader effects
+are inert too.
+
+A `Mesh` under a *2D* camera does render on Canvas, but only as a last resort:
+textured, CPU-projected, sorted back to front a triangle at a time (painter's
+algorithm) and unlit. Overlapping parts can show slivers of the wrong
+triangle, large textured faces are mapped without perspective correction, and
+it slows down as the triangle count grows. It keeps a 2D-camera game from going
+blank on a device with no GPU backend; do not design for it or tune on it.
 
-`Application` does warn: constructing with a `cameraClass` whose
-`defaultSortOn` is `"depth"` on a renderer with no depth buffer logs a
+`Application` does warn: `await app.init()` 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:
@@ -1070,23 +1147,42 @@ await app.init();
 ```
 
 To branch rather than fail, read `app.renderer.supportsDepthBuffer` after
-`init()`.
+`init()`: a `Camera3d` game should refuse Canvas there with a message, while a
+game whose meshes sit under a 2D camera can let it through as the fallback.
+
+```js
+const app = new Application(1024, 768, { parent: "screen", renderer: video.AUTO });
+await app.init();
+if (!app.renderer.supportsDepthBuffer) {
+    // the Canvas fallback: no GPU backend on this device. Meshes under the
+    // 2D camera still draw (CPU-projected, unlit); keep the scene small, or
+    // tell the player the game needs WebGL 2 or WebGPU.
+}
+```
 
 ## Symptom → cause
 
 | symptom | cause |
 |---|---|
 | scene lit from underneath | `direction` Y sign — this is Y-down, so a sun overhead is **+Y** |
-| a `lit` mesh renders fullbright | it had no normals — supply them, or let the engine generate them |
+| `model.scale(2)` throws "not a function" on a `GLTFModel` (before 20.14) | the `scale` option hid the method: update |
+| a `GLTFModel` ignores `pos` / `rotate` once its clip is paused or finished (before 20.14) | it was only re-posed while a clip played: update |
+| a sprite or mesh in a container draws too near under `Camera3d`, and pops in and out at the wrong time (before 20.14) | the container's depth was used to cull and sort its children but not to draw them: update |
+| a lit mesh inside a moved or turned container is lit as if the container were at the origin (before 20.14) | lights were not taken into the container's frame: update. Under a *scaled* container, a point light's range is measured in the container's units |
+| objects at the screen edge pop in a frame late while the camera turns, or a camera cut shows one empty frame (before 20.14) | culling used the camera as it was at the last `camera.update()`: update |
+| a `lit` mesh renders fullbright | no `Light3d` in the world, or a 2D camera (which warns once). Before 20.4 a mesh with no normals did it too; they are generated now |
 | 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 |
 | a glow is cut along a hard straight line, worst near a round object's limb | a flat billboard being depth tested against the geometry behind it — `depthTest: false` |
-| vertex colour applies under a 2D camera but not `Camera3d` | wrote the array directly without setting `needsUpdate` |
+| `depthTest: false` changes nothing | the mesh draws in the opaque pass, which ignores it — add `transparent: true` |
+| `specular` is set but no highlight appears | `shininess` is 0 (the default), or the mesh is not `lit` |
+| `setInstanceColor` does nothing | the set was built without `instanceColors: true`; the slot does not exist |
+| a vertex colour or a geometry edit 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` |
+| a 2D-camera mesh shows slivers where it overlaps itself, or slows with many triangles | the Canvas fallback, a last resort: ask for `video.WEBGL` or `video.WEBGPU` |
 | 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 |
@@ -1114,9 +1210,13 @@ To branch rather than fail, read `app.renderer.supportsDepthBuffer` after
 | `setBasis` throws "forward must have a non-zero length" | `forward` is all zeros, the one case that names no direction; a short one is fine, so a surface frame that shrank as it drifted still works |
 | roll is ignored when the target is straight up or down | no rotation about the view axis is determined there, so `lookAt` keeps the roll it had and `setBasis` falls back to the `right` axis |
 | an object jumps to the camera plane | `Vector3d.set(x, y)` / `camera.pos.set(x, y)` zeroed its z |
+| a follow camera ignores its deadzone and damping | `Camera3d` follows exactly, at the target plus `followOffset`; damp it yourself with no target set |
+| a `Light3d` parented to a moving object stays behind | `position` is in world coordinates and its container is not applied; copy the world position into it each frame |
 | lighting looks wrong under a 3D camera | `Light2d` used instead of `Light3d` |
 
 ## Related skills
 
+- `melonjs-3d-assets` — glTF/GLB and OBJ/MTL loading, imported materials and lights
+- `melonjs-effects-and-shaders` — a `ShaderEffect` hosted on a mesh, and custom mesh shaders
 - `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

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