melonjs 20.3.0 → 20.5.0

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

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