melonjs 20.6.0 → 20.8.0

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-3d
-description: "Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, lit."
+description: "Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, lit, setBasis, getBasis, lookAt, up vector, gimbal."
 license: MIT
 ---
 
@@ -20,11 +20,15 @@ This is the single most important thing on this page.
 | 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, and `Camera3d` exposes all three: `camera.pitch`
+`Camera3d` exposes three rotation angles: `camera.pitch`
 (X, look up/down), `camera.yaw` (Y, look left/right) and `camera.roll` (Z, bank
 the horizon). The view is `R(yaw) ∘ R(pitch) ∘ R(roll)` inverted, and the frustum
 planes come off that same matrix — so culling follows a banked view.
 
+The basis those angles produce is **readable and writable**: `getBasis(right,
+up, forward)` reads it, `setBasis(right, up, forward)` poses the camera from
+one.
+
 `camera.rotate()` is NOT the way to bank a 3D camera. It writes the inherited
 `currentTransform`, which a 3D view never reads, so the call is silently inert.
 Set `roll`. (On a `Camera2d` it is the other way round: roll IS that transform's
@@ -89,11 +93,72 @@ class GameStage extends Stage {
   `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.
+- **`lookAt(target)` solves pitch and yaw only**, so on its own it cannot
+  express "up is this direction" and it leaves `roll` alone. Pass an up to
+  bank the horizon too: `camera.lookAt(target, up)`, where `up` is what should
+  appear UP ON SCREEN. This engine renders Y-down, so a level horizon is
+  `(0, -1, 0)`. There is deliberately no default, because giving one would
+  silently level every camera that had banked its own horizon.
+- **When the game already has all three axes, hand them over**:
+  `camera.setBasis(right, up, forward)`, the writable counterpart of
+  `getBasis`. The case that needs it is a view over a curved surface, where up
+  is the surface normal and differs at every point, so no pitch and yaw pair
+  expresses it and integrating towards one drifts and gimbals at the poles.
+  `setBasis` absorbs a triple that has drifted off orthonormal rather than
+  leaving the camera holding something that is not a rotation, and it does not
+  care what the axes are scaled to: a direction is a direction, so anything
+  from a denormal to 1e300 resolves the same way. Note its `up` is the camera's
+  local +Y column, which under Y-down points DOWN the screen: the opposite
+  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
   `null` behind the camera. See `melonjs-camera-and-drawing`.
 
+## Where an up vector earns its keep
+
+Three cases. In the first two, `lookAt(target)` on its own is already right and
+an up would be noise. The third is the one it exists for.
+
+```js
+// 1. ordinary third-person: world up never changes, so say nothing
+camera.setPosition(x, y, z).lookAt(player);
+
+// 2. a deliberate dutch angle: this is a ROLL, not an up vector
+camera.lookAt(player);
+camera.roll = Math.PI / 32;
+
+// 3. a view over a curved surface: up is the surface normal, and it is
+//    different at every point on the globe. No pitch and yaw pair expresses
+//    it, and integrating towards it drifts and gimbals over the poles.
+const up = player.pos.clone().sub(planetCentre).normalize();  // surface normal
+camera.setPosition(eye.x, eye.y, eye.z).lookAt(player, up.negate());
+```
+
+Note the `negate()` in case 3. The surface normal points away from the planet,
+which is the direction the player's head points, and `up` wants what should
+appear UP ON SCREEN. This engine renders Y-down, so `(0, -1, 0)` is a level
+horizon and a world-space "up" direction has to be handed over in that sense.
+Get it backwards and the view is upside down, which is the single most likely
+mistake with this argument.
+
+If the game already computes all three axes, skip the solve entirely:
+
+```js
+// a surface frame the game is already maintaining
+camera.setBasis(right, up, forward);
+```
+
+`setBasis` takes the camera's OWN columns, where `up` is local +Y and so points
+down the screen: the opposite sense to `lookAt`'s, one negation apart. It also
+absorbs a frame that has drifted off orthonormal, which one integrated over
+thousands of steps will have.
+
+**A camera posed this way and a world rotated into a fixed camera's frame are
+the same picture.** If a game already transforms its world into view space by
+hand, there is nothing to gain by switching; the value of `setBasis` is not
+having to write that transform in the first place.
+
 ## Depth sorting
 
 Under `Camera3d` the world sorts on `"depth"` **every frame** (recursively), so
@@ -153,6 +218,40 @@ geometry with an opaque one would drag the opaque half into the transparent pass
 
 **`transparent: false`** pins a mesh to the opaque pass however it is faded.
 
+### `depthTest: false` for something with no surface to be occluded on
+
+`transparent` decides the PASS, and the transparent pass turns depth *writing*
+off on its own so overlapping blended draws blend instead of fighting. Whether
+geometry in front of a mesh **hides** it is a separate question, and
+`depthTest` is where you answer it. The default, `true`, is what you want for
+anything genuinely in the scene — a muzzle flash behind a wall should still be
+behind the wall, and this is not a synonym for "additive".
+
+Set it `false` for a mesh standing in for a screen-space effect: an additive
+glow carrying a world position only so it can sort and move with the thing it
+belongs to. A world-space caption billboarded over a prop wants it for the
+same reason, since it has no surface for the prop's own foliage to be in front
+of. Left depth tested, a flat billboard is sliced along a hard straight
+line the moment any geometry is nearer at some pixel. That shows up worst
+around something round — a glow on a rock near a planet's limb gets cut,
+and no offset escapes it, because the near surface bulges further toward the
+camera than any offset you would dare apply.
+
+```js
+const halo = new Sprite3d(0, 0, {
+    image: glowTexture,
+    width: rock.radius * 3, height: rock.radius * 3,
+    billboard: "spherical",
+    blendMode: "additive",
+    transparent: true,     // the blended pass
+    alphaCutoff: 0,        // do not cut the soft falloff
+    depthTest: false,      // and do not let the world slice it
+});
+```
+
+Honoured in the transparent pass on both GPU backends; 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
 compositing pass) fall back to `"normal"` here, on both backends:
@@ -233,10 +332,14 @@ mesh shaders, so a screen-space overlay stays clean with no work.
 **A custom mesh shader is not fogged unless it asks to be.** Fog is compiled
 into the engine's own mesh programs — `#define FOG` on WebGL, an `enable_fog`
 overridable constant on WebGPU — and a shader you supply is yours: the engine
-binds it as written and never substitutes a fogged variant. So a mesh carrying a
-`ShaderEffect` keeps full contrast while the scene around it recedes. It is safe
-— nothing throws, and the camera's fog is simply not applied — but it is usually
-surprising.
+binds it as written and never substitutes a fogged variant. So a mesh given its
+own `GLShader` keeps full contrast while the scene around it recedes. It is
+safe — nothing throws, and the camera's fog is simply not applied — but it is
+usually surprising.
+
+A hosted `ShaderEffect` is the other case and needs nothing: its body is
+spliced into the engine's own mesh program as a colour hook, and fog is applied
+to the hook's result, so such a mesh fogs like any other.
 
 To opt in, declare the same uniforms and the engine will feed them, because the
 fog values are pushed to any mesh program that declares them rather than only to
@@ -475,6 +578,22 @@ 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.
 
+A billboard takes its **orientation** from the camera, so `rotate()` has no
+effect on one: a card already turned to face the camera has no free rotation
+left to give. Everything that is not an orientation still applies, `scale()`
+and `meshScale` included, so animating the size of a shockwave or a pickup is
+the ordinary call and the cull bounds grow with it:
+
+```js
+const wave = new Sprite3d(x, y, { image: "ring", width: 64, height: 64,
+                                  billboard: "spherical", transparent: true });
+wave.scale(1 + 3 * t);          // grows; `scale` accumulates, so drive it
+                                 // from the authored size, not per frame
+```
+
+For an in-plane rotation, a bolt streak or an exhaust, use `billboard: false`
+and orient the quad yourself.
+
 ## Lighting
 
 `Light3d` takes **one argument — the options object** (it has no `x, y, z`
@@ -527,23 +646,147 @@ and spot, a stylised quadratic falloff, not inverse-square),
 **`Light2d` is 2D-only** and produces visible artifacts under perspective
 projection. Do not combine it with `Camera3d`.
 
+**`lit: true` only does anything under a `Camera3d`.** Lighting a mesh needs
+world-space normals and a world-space fragment position, and the 2D-camera path
+has neither: its vertices are already the projected output, so there is no world
+space left to light in. Such a mesh degrades to unlit and warns once, naming the
+fix. If you want lit 3D props in an otherwise 2D game, set
+`cameraClass: Camera3d` on the application. (For 2D **sprites**, lighting is a
+separate system that works under a 2D camera as normal, see the lighting skill.)
+
+A `lit` mesh takes a **tangent-space normal map**, so relief comes from the
+material rather than from geometry — `settings.normalMap` (a loader key or any
+image-like source), or MTL `map_bump` / `bump` / `norm`, which the MTL loader
+fetches and applies per material. The tangent frame is derived per fragment, so
+the model needs no tangent attribute, and an unmapped mesh is unaffected. This
+is the 3D counterpart of the `Sprite` normal maps in the lighting skill; they
+are separate systems and a `Mesh` uses this one.
+
+### What the ground-shadow tier can and cannot do
+
+Check this table before claiming a setting is unsupported. Every one of these
+is read **every draw**, so all of them can be animated.
+
+| setting | `Mesh` / `Sprite3d` / `GLTFModel` part | `InstancedMesh` |
+|---|---|---|
+| `castGroundShadow` | yes | yes |
+| `shadowGroundY` | yes, the caster's own floor | yes, **one plane** through the SET's origin |
+| `shadowGroundNormal` | yes | yes, one plane for the set |
+| `shadowOpacity` | yes | yes |
+| `shadowScale` | yes | yes |
+| `shadowOffset` | yes | yes, one throw for the set |
+| `shadowStretch` | yes | yes, one stretch for the set |
+| `shadowDirectionX` / `Z` | yes | yes |
+| `shadowLight` | yes | yes |
+| height fade as the caster rises | yes | **no** |
+| a different value per instance | n/a | **no**, and there is no plan for one |
+
+The two "no"s are the same limitation seen twice: a set gets ONE shadow plane
+and ONE shared quad, so the instance's own height is dropped and nothing can
+vary between instances. Everything else is one value for the whole set, which
+is what a set means. A scatter over curved ground is therefore one set per flat
+facet, and a flying scatter wanting a height fade has to be per-object meshes.
+
+Nothing here is per-object-only. If a claim that a setting "does not work on an
+`InstancedMesh`" is in your head, it is out of date: `shadowOffset` and
+`shadowStretch` both reached the instanced tier in 20.8.
+
 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.
+given, safeguard included; `shadowGroundY` names the floor the blob lands on,
+`shadowOpacity` how dark it is and `shadowScale` how big it is.
 
 The blob is an ellipse sized to the caster's own footprint and placed at the
-caster's x/z — it is **never offset by light direction**. So a tall or narrow
-object (a character, a tree, a pickup) shows its shadow clearly, while a wide,
-flat-bottomed one resting on the floor covers its own completely from a camera
-looking down at it. That is the shadow behaving correctly, not a bug.
+caster's x/z. So a tall or narrow object (a character, a tree, a pickup) shows
+its shadow clearly, while a wide, flat-bottomed one resting on the floor covers
+its own completely from a camera looking down at it. That is the shadow
+behaving correctly, not a bug.
 
 **Do not chase it by raising `shadowGroundY`.** Lifting the plane does not slide
 the blob out from under the object, it floats the blob *up* — and past a few
-units it projects over the top of the caster as a dark halo ringing it. If an
-object needs a visible shadow, give it a smaller footprint relative to its
-height, or accept that a boulder bedded in the ground has none.
+units it projects over the top of the caster as a dark halo ringing it.
+
+The simplest fix is a bigger blob, so its edge shows past the object:
+
+```js
+mesh.shadowScale = 1.5;        // 1 is the default; 0 hides the shadow
+```
+
+`shadowScale` works everywhere, `InstancedMesh` included. Changing it on a
+set rewrites the shared quad's four corners in place rather than rebuilding
+it, as does a `shadowLight` that moves, so an animated sun costs no
+allocation.
+
+Or, for the look of a sun that is not overhead, use the shape controls:
+
+```js
+mesh.shadowOffset = 1.5;       // slide it out, in blob radii
+mesh.shadowDirectionX = 1;     // the ground direction it is cast along
+mesh.shadowDirectionZ = 0;
+mesh.shadowStretch = 2;        // and lengthen it along the same line
+```
+
+`shadowOffset` is measured in multiples of the blob's **own radius**, not in
+world units, so one value serves a boulder and a pebble and every part of a
+glTF model. About `stretch - 1` is what keeps the shadow attached to its
+caster. It is honoured **only when `shadowGroundY` is set**, because the
+blob is a flat quad on one named plane: sliding it across a plane the game has
+not named puts it where there may be no floor. `shadowStretch` is clamped to 3
+and the blob fades as it pulls, so an extreme value degrades to nothing rather
+than to a smear.
+
+An `InstancedMesh` honours both, as **one** offset and **one** stretch for the
+whole set, which is all a shared set can carry. Both ride the quad the blobs
+share rather than the matrix that also places them: a stretch in the matrix
+would scale the instance positions too and smear the scatter instead of
+lengthening its blobs. So a scatter can sit next to loose props under the same
+sun without looking lit from somewhere else.
+
+`shadowLight` takes the direction from a `Light3d` you name, re-read every
+draw, so a moving sun carries the shadows with it. Nothing is inferred: the
+engine never picks a dominant light, because a scene with several has no
+non-arbitrary answer and one with none has no answer at all.
+
+### A floor that is not level
+
+`shadowGroundY` says where the floor is; `shadowGroundNormal` says which way
+it faces:
+
+```js
+prop.shadowGroundY = floorY;
+prop.shadowGroundNormal = [Math.sin(0.35), -Math.cos(0.35), 0];  // a 20 deg slope
+```
+
+World up is `(0, -1, 0)`, because render space is Y-down, and that is the
+default. The blob is **rotated** onto the plane rather than projected, so it
+keeps its size; it still sits directly under the caster, since the normal
+turns it rather than moving it. The tilt is clamped at 75 degrees, past which
+an edge-on blob has nothing left to show. It needs `shadowGroundY`, for the
+same reason the offset does: tilting the bounds fallback has no anchor to turn
+about.
+
+On an `InstancedMesh` one plane serves the **whole set**: it passes through
+the set's origin at `shadowGroundY`, faces the normal, and every blob is
+projected onto it whatever height its own instance sits at, exactly as the
+level case puts every blob at one height. A scatter over curved ground is
+therefore one set per flat facet, each with the facet's own plane, not one
+set with an averaged normal.
+
+All three compose on a set: the stretch turns the shared quad, the offset
+slides the whole set along the light, and both are carried onto the tilted
+plane rather than applied flat, so a bank's planting lies along its slope
+instead of hovering across it.
+
+Give blobs to the plants that stand apart. Dense low ground cover is better
+left without: a thousand blobs each as wide as its own fern sum to a darkened
+hillside, not to a thousand shadows, and ground cover is the ground.
+
+These are **art direction, not a projection**. A stretched ellipse is not a
+silhouette and has no contact with terrain, so on ground that is not the plane
+you named it will not lie on it. Direction-correct shadows want a shadow map,
+which this tier does not do.
 
 ### Get the sign right: the floor is a GREATER y
 
@@ -571,10 +814,28 @@ caster's own y and check which one is larger.
 
 ## Collision in 3D
 
-Use `Box3d` bodies, not a hand-rolled distance check. `Box3d`-vs-`Box3d` is
-the engine's 3D narrowphase and the only contact that pushes back along Z; the
-response carries `overlapNZ` / `overlapZ` for the depth axis. See the physics
-skill for the contract and the mixed-pair caveat.
+Use a body with a depth shape, not a hand-rolled distance check. Two shapes
+carry depth — `Box3d` and `Sphere` — and any pair of them is resolved in three
+dimensions; the response carries `overlapNZ` / `overlapZ` for the depth axis.
+
+Pick by whether the thing turns. `Box3d` is world-axis-aligned and cannot be
+oriented, so it fits walls, floors and crates and misfits anything that
+tumbles. `Sphere` has no orientation at all, which makes it the shape for
+spinning debris, projectiles, and anything spread over a curved surface: on a
+globe each object's own "up" points a different way, so one axis-aligned box
+cannot fit any of them.
+
+A hand-rolled check is the usual mistake here and it costs twice — it throws
+away the penetration vector the response already carries, and it is invisible
+to the debug plugin's hitbox overlay, which draws from `body.shapes`. If the
+red boxes never appear, the reason is usually that there is no body to draw.
+
+Against a planar shape, either 3D shape degrades to its XY footprint with the
+planar side read as unbounded along Z, so a sphere or box body still collides
+with an ordinary collision layer, just without a depth result. And mind the
+normal: a box pair separates along one world axis, a sphere along the line
+between two centres, so a sphere contact fills the 2D and depth halves of the
+response at the same time. See the physics skill for the full contract.
 
 ## glTF / GLB scenes
 
@@ -583,6 +844,13 @@ 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 });
+
+// every ground-shadow setting travels, not just those two: a loaded scene can
+// be told where its sun is, and `shadowLight` is re-read every draw
+level.load("diorama", {
+    scale, castGroundShadow: true, shadowGroundY: 0,
+    shadowLight: sun, shadowOffset: 0.6, shadowStretch: 1.8, async: true,
+});
 ```
 
 `.obj` / `.mtl` are also supported loader types.
@@ -642,6 +910,7 @@ To branch rather than fail, read `app.renderer.supportsDepthBuffer` after
 | a `lit` mesh renders fullbright | it had no normals — supply them, or let the engine generate them |
 | a gradient across one mesh is impossible | `tint` is per object — use `vertexColors` / `setVertexColor` |
 | a mesh stays solid as you fade it out | meshes render opaque; only `alpha` 0 (hidden) and 1 differ |
+| 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` |
 | `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 |
@@ -660,11 +929,16 @@ To branch rather than fail, read `app.renderer.supportsDepthBuffer` after
 | fog does not match the sky after a background fade | an explicit `color` was passed; omit it to track `renderer.backgroundColor` |
 | geometry clips before it has finished fading | fog `far` beyond the clip far — omit the distances and they default to the clip planes |
 | one marker must stay readable in fog | `fog: false` on that mesh |
-| an object casts no visible shadow | wide and flat-bottomed — its own blob is underneath it; raising `shadowGroundY` haloes it instead of revealing it |
+| an object casts no visible shadow | wide and flat-bottomed — its own blob is underneath it; raise `shadowScale` (or slide it out with `shadowOffset`), not `shadowGroundY`, which haloes it instead of revealing it |
 | a dark ring around the top of an object | `shadowGroundY` lifted too far, floating the blob up into the caster |
 | a mesh sits at the wrong depth after being added | `autoDepth` overwrote `pos.z` with the child index — pass `addChild(mesh, z)` |
 | a mesh sits half its size off | `anchorPoint` — only on the 2D-camera path; a `Camera3d` mesh pivots on its model origin |
 | a billboard tips over when the camera looks down | `"spherical"`, or a mistyped mode string falling through to it — use `true` / `"cylindrical"` |
+| `rotate()` does nothing on a billboard | the camera owns its orientation; `billboard: false` and orient the quad yourself |
+| the camera will not tilt its horizon to an arbitrary up | `lookAt(target)` solves pitch and yaw only; pass the up as the next argument, or hand all three axes to `setBasis` |
+| the view is upside down after `lookAt(target, up)` | `up` is the direction that should appear UP ON SCREEN, and this is Y-down, so a level horizon is `(0, -1, 0)` |
+| `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 |
 | lighting looks wrong under a 3D camera | `Light2d` used instead of `Light3d` |
 

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

@@ -40,6 +40,13 @@ or it renders flat. See `melonjs-3d` for the camera.
 | `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 |
+| `shadowOpacity` | `0.45` | how dark the blobs are |
+| `shadowScale` | `1` | blob footprint multiplier; `0` or less hides them |
+| `shadowOffset` | `0` | slide them along the light, in blob radii; needs `shadowGroundY` |
+| `shadowStretch` | `1` | lengthen them along it, clamped to 3 |
+| `shadowDirectionX` / `shadowDirectionZ` | `0` | the ground direction they are cast along |
+| `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 |
 
 `onLoaded` receives the level id — it is a "done" signal, not a handle on the
 scene. You need it, or `async`: with the game loop running, `level.load` stops
@@ -63,6 +70,33 @@ level.load("diorama", { scale: 50, onLoaded: () => {
 }});
 ```
 
+### The same options from a Tiled `Trigger`
+
+A `Trigger` authored in Tiled forwards these to `level.load()`, so a trigger that
+walks the player into a glTF level carries the scene's settings as Tiled
+properties:
+
+```js
+world.addChild(new Trigger(x, y, {
+    shapes: [new Rect(0, 0, 100, 100)],
+    to: "diorama",              // the level id — `to`, not `level`
+    scale: 50,
+    rightHanded: false,
+    castGroundShadow: false,
+}));
+```
+
+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).
+
+**`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
+trigger without one loads fire-and-forget and never sets it. Either way an
+authored `async` property is ignored rather than honoured.
+
 ## `rightHanded` — and the default that differs between the two APIs
 
 glTF is authored **Y-up, right-handed**; melonJS is **Y-down, +Z forward**.
@@ -103,6 +137,54 @@ asset fails to load. Export uncompressed.
 `"auto"`) drives sampling; glTF materials that declare their own sampler carry
 it through. Pixel-art models want `"nearest"`.
 
+### `baseColorFactor` is LINEAR; a `tint` is sRGB
+
+The loader handles this for you. It only bites when you build meshes yourself
+from `loader.getGLTF(name).nodes` — which is what you do for per-node control,
+since there is no public per-node `Mesh` factory — and reach for the obvious
+`* 255`:
+
+```js
+// WRONG — every untextured material renders far too dark
+mesh.tint.setColor(f[0] * 255, f[1] * 255, f[2] * 255, 1);
+```
+
+glTF defines `pbrMetallicRoughness.baseColorFactor` in **linear** space (spec
+3.9.2), while a melonJS `tint` is 8-bit **sRGB** — the same space as a CSS
+colour or a texel out of a PNG. They are not the same number, and the gap is
+widest exactly where art tends to live:
+
+| linear | `* 255` | correct | 
+|---|---|---|
+| 0.05 | 13 | 63 |
+| 0.20 | 51 | 124 |
+| 0.42 | 107 | 173 |
+| 0.72 | 184 | 221 |
+| 1.00 | 255 | 255 |
+
+`Color.setLinear` does the encoding for you — it is the linear-space sibling of
+`setFloat`, which takes the same `0..1` range but treats it as already-sRGB:
+
+```js
+mesh.tint.setLinear(...node.baseColorFactor);   // encodes; what you want
+mesh.tint.setFloat(...node.baseColorFactor);    // does NOT encode; too dark
+```
+
+It clamps, so the slightly out-of-range factors some exporters emit cannot turn
+into `NaN`, and it keeps the encoded value as a float rather than rounding
+through 8 bits.
+
+Measured on a scene whose every material went through `* 255`: mean frame luma
+85.5 against 147.8 once encoded, with each channel sitting 60 to 73 counts low.
+
+**Fix it early.** It is nearly invisible as a bug, because the scene still
+looks coherent — just moody — so lighting and bloom thresholds get tuned
+against the wrong values. Correcting the encoding afterwards blows the frame
+out and forces a lighting retune, which is a much bigger job than the encode.
+
+This applies only to factors coming out of glTF. Colours **you** author for the
+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`
@@ -197,11 +279,21 @@ 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.
+A blob sits on its caster's x/z by default, so a wide flat-bottomed prop hides
+its own shadow under itself. The knob for that is `shadowScale`, which widens
+the blob until its edge shows past the prop, or `shadowOffset` plus a direction,
+which slides it clear. **Not** `shadowGroundY`: raising that floats the blob up
+over the object as a dark ring instead of sliding it out, because it is for
+things that leave the ground, not a visibility control.
+
+For a light that is not overhead, name one: `shadowLight` takes the direction
+from a `Light3d` and is re-read every draw, so a day or night cycle carries
+every shadow in the scene with it. Nothing is inferred — a scene with no named
+light and no `shadowDirectionX`/`Z` gets no direction, because a scene with
+several lights has no non-arbitrary answer. `shadowStretch` lengthens the blob
+along that direction and fades it as it pulls; `shadowGroundNormal` lays it on
+a floor that is not level. All of these apply to an `InstancedMesh` too, as one
+value for the whole set.
 
 ## OBJ/MTL
 
@@ -226,16 +318,33 @@ const mesh = new Mesh(400, 300, {
 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.
+**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
+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.
+`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.
+
+`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
+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
+a field its exporter wrote inconsistently.
+
 `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.
@@ -380,6 +489,7 @@ need a prefix.
 | 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 |
+| every untextured glTF material renders too dark, white unaffected | `baseColorFactor` is linear and a `tint` is sRGB — `tint.setLinear(...)`, not `* 255` or `setFloat` |
 | `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 |