melonjs 20.12.0 → 20.14.0

package/skills/melonjs/SKILL.md

@@ -34,25 +34,25 @@ dependencies.
 | [melonjs-scenes-and-state](../melonjs-scenes-and-state/SKILL.md) | `Stage` subclasses, the state manager, transitions, pausing, the update loop, timers, tweens, saved data. |
 | [melonjs-renderables](../melonjs-renderables/SKILL.md) | Subclassing `Renderable`, custom `draw()`, draw order, anchors, `floating`, post effects on an object. |
 | [melonjs-sprites-and-animation](../melonjs-sprites-and-animation/SKILL.md) | `Sprite`, frame animation, texture atlases (TexturePacker / Aseprite / ShoeBox), tint, flip, pooling. |
-| [melonjs-input](../melonjs-input/SKILL.md) | Keyboard actions, pointer and touch handling, drag, gamepad, virtual controls. |
-| [melonjs-physics](../melonjs-physics/SKILL.md) | Collision, bodies, movement, spatial queries, and the planck / matter adapters. |
+| [melonjs-input](../melonjs-input/SKILL.md) | Keyboard actions, pointer and touch handling, drag, gamepad, virtual controls (fixed or floating sticks and buttons, tap to act). |
+| [melonjs-physics](../melonjs-physics/SKILL.md) | Collision, bodies, movement, spatial queries, and the planck / matter / Rapier adapters. |
 | [melonjs-math](../melonjs-math/SKILL.md) | Vectors and matrices: what mutates, what allocates, and interpolating with lerp, slerp, damp or moveTowards. |
-| [melonjs-tilemaps](../melonjs-tilemaps/SKILL.md) | Tiled maps — TMX/TSX loading, spawning entities from objects, collision layers, isometric maps. |
+| [melonjs-tilemaps](../melonjs-tilemaps/SKILL.md) | Tiled maps — TMX/TSX loading, spawning entities from objects, collision layers, isometric maps, reading and changing tiles at run time (a tile layer as the game board). |
 | [melonjs-audio](../melonjs-audio/SKILL.md) | Sound effects, music, audio sprites, spatial audio, procedural tone and noise. |
 | [melonjs-effects-and-shaders](../melonjs-effects-and-shaders/SKILL.md) | Post effects, custom GLSL/WGSL shaders, blend modes, colour grading, screen capture. |
 | [melonjs-3d](../melonjs-3d/SKILL.md) | Anything 3D or 2.5D — `Camera3d`, meshes, instancing, `Sprite3d` billboards, `Light3d`, distance fog, glTF scenes. |
 | [melonjs-3d-assets](../melonjs-3d-assets/SKILL.md) | Loading glTF/GLB or OBJ models — materials, imported lights, instancing, and what is not supported. |
 | [melonjs-camera-and-drawing](../melonjs-camera-and-drawing/SKILL.md) | Camera follow, bounds, shake and fade, coordinate conversion, and immediate-mode shape drawing. |
-| [melonjs-ui-and-text](../melonjs-ui-and-text/SKILL.md) | HUDs, buttons, menus, drag-and-drop, `Text` and `BitmapText`, web fonts, panels. |
+| [melonjs-ui-and-text](../melonjs-ui-and-text/SKILL.md) | HUDs, menus and options screens — buttons, checkboxes, sliders, progress bars, laid-out and scrolling panels — drag-and-drop, `Text` and `BitmapText`, web fonts. |
 | [melonjs-particles-and-trails](../melonjs-particles-and-trails/SKILL.md) | `ParticleEmitter`, burst versus stream, `referenceSpace`, and the `Trail` renderable. |
 | [melonjs-lighting](../melonjs-lighting/SKILL.md) | 2D dynamic lighting — `Light2d`, stage ambient, normal-mapped sprites. |
-| [melonjs-deployment](../melonjs-deployment/SKILL.md) | Scaffolding a project, building, browser support and transpiling, native and mini-game platforms. |
-| [melonjs-loading-assets](../melonjs-loading-assets/SKILL.md) | Resource descriptors, the asset type list, base URLs, cross-origin, progress events, unloading. |
+| [melonjs-deployment](../melonjs-deployment/SKILL.md) | Scaffolding a project, building, browser support and transpiling, native and mini-game platforms, running with no DOM (nx.js on the Nintendo Switch, Web Workers). |
+| [melonjs-loading-assets](../melonjs-loading-assets/SKILL.md) | Resource descriptors, the asset type list, a multi-level game's assets as bundles (`common` + one per level), loading and freeing a level's assets, base URLs, cross-origin, progress events. |
 | [melonjs-renderer-backends](../melonjs-renderer-backends/SKILL.md) | A feature works on one machine but not another; choosing or pinning a backend; degrading gracefully. |
 | [melonjs-display-and-scaling](../melonjs-display-and-scaling/SKILL.md) | Blurry, soft or cropped output; the design resolution, how the canvas fills its page, and pixel-perfect integer scaling. |
 | [melonjs-events](../melonjs-events/SKILL.md) | The event bus, per-frame and lifecycle events, and subscribing without leaking. |
 | [melonjs-performance](../melonjs-performance/SKILL.md) | Dropped frames, draw-call counts, pooling, batching, culling, baking, profiling. |
-| [melonjs-plugins](../melonjs-plugins/SKILL.md) | Registering the debug, Spine or Tiled-inflate plugins, physics adapters, or writing your own plugin. |
+| [melonjs-plugins](../melonjs-plugins/SKILL.md) | Registering the debug, Spine, Tiled-inflate, gamepad (touch controls) or Capacitor plugins, installing a physics adapter, or writing your own plugin. |
 
 
 ## Escape hatch: the full API index
@@ -97,7 +97,9 @@ Whatever the task, these produce code that runs and is wrong:
    it after does not resort (except under `Camera3d`).
 3. **`isKinematic` defaults to `true`**, which silently excludes a renderable
    from pointer events and from the physics broadphase. Plain `Renderable` and
-   `Sprite` subclasses need `this.isKinematic = false`.
+   `Sprite` subclasses with no body need `this.isKinematic = false`; adding a
+   body sets it for you, on every adapter (matter-adapter before 1.6 and
+   planck-adapter before 1.7 did not).
 
 ## Companion packages
 
@@ -109,10 +111,11 @@ Tiled inflate plugin are *required* for their use cases, not merely convenient.
 |---|---|
 | [`@melonjs/planck-adapter`](https://www.npmjs.com/package/@melonjs/planck-adapter) | You want full rigid-body dynamics — stacking, joints, realistic restitution. Pass it as the Application's `physic` setting; the portable `raycast` and `queryAABB` calls work unchanged across adapters (`querySphere` and `raycast3d` are built-in-adapter only). |
 | [`@melonjs/matter-adapter`](https://www.npmjs.com/package/@melonjs/matter-adapter) | Same, backed by matter-js. Choose one adapter per game. |
+| [`@melonjs/rapier2d-adapter`](https://www.npmjs.com/package/@melonjs/rapier2d-adapter) | Same again, backed by Rapier compiled to WebAssembly: many bodies, per-body continuous collision, a character controller. About 3 MB loaded on demand, so make it with `await RapierAdapter.create()`. |
 | [`@melonjs/tiled-inflate-plugin`](https://www.npmjs.com/package/@melonjs/tiled-inflate-plugin) | **Required** to load gzip-, zlib- or zstd-compressed Tiled maps. Without it, parsing such a map throws `No inflate function set`. |
 | [`@melonjs/spine-plugin`](https://www.npmjs.com/package/@melonjs/spine-plugin) | Skeletal animation authored in Spine, as a melonJS renderable. |
 | [`@melonjs/debug-plugin`](https://www.npmjs.com/package/@melonjs/debug-plugin) | An in-game debug panel — FPS, draw counts, collision-shape and bounds overlays. Register it after `app.init()`. |
-| [`@melonjs/gamepad-plugin`](https://www.npmjs.com/package/@melonjs/gamepad-plugin) | On-screen touch controls for phones and tablets: sticks and buttons reported as a gamepad, so the game's `bindGamepad` bindings drive it. Use it rather than writing virtual controls. |
+| [`@melonjs/gamepad-plugin`](https://www.npmjs.com/package/@melonjs/gamepad-plugin) | On-screen touch controls for phones and tablets: sticks and buttons reported as a gamepad, so the game's `bindGamepad` bindings drive it; fixed or floating under the thumb, hidden until touched, tap to act. Use it rather than writing virtual controls. |
 | [`@melonjs/capacitor-plugin`](https://www.npmjs.com/package/@melonjs/capacitor-plugin) | Wrapping a game as a native iOS/Android app: it bridges Capacitor's lifecycle — pause/resume, the hardware back button, orientation lock, splash screen. |
 | [`create-melonjs`](https://www.npmjs.com/package/create-melonjs) | Scaffolding a new project — start here rather than assembling a build by hand. |
 
@@ -136,7 +139,7 @@ const app = new Application(800, 600, {
     parent: "screen",
     // gravity is in pixels/s²; pixelsPerMeter converts it to the adapter's
     // metres. Both are shown at their defaults; subSteps defaults to 1
-    physic: new PlanckAdapter({
+    physic: await PlanckAdapter.create({
         gravity: { x: 0, y: 320 },
         pixelsPerMeter: 32,
         subSteps: 2,
@@ -145,15 +148,36 @@ const app = new Application(800, 600, {
 await app.init();
 ```
 
+Every adapter is made the same way, with `await X.create(options)`. A running
+game switches adapter with `app.world.setAdapter(await X.create(options))`,
+which rebuilds every body from its `bodyDef`; `world.adapter` itself is
+read-only. `melonjs-physics` says which adapter suits which game.
+
 `melonjs-plugins` covers the registry, the version gate and writing your own.
 
 ## Prefer built-in features
 
 melonJS covers a lot that is easy to reimplement badly. Before hand-rolling,
-check for: `ParticleEmitter` and `Trail`, `Tween` with easing, the built-in
-`ShaderEffect` presets (vignette, scanline, chromatic aberration, glow, dissolve
-and more), `Light2d` / `Light3d`, `UIBaseElement` / `UISpriteElement` /
-`UITextButton`, `NineSliceSprite`, `TextureAtlas` (TexturePacker, ShoeBox,
-Aseprite), `BitmapText`, `CanvasRenderTarget` for bake-once drawing,
-`NoiseTexture2d`, `viewport.shake` / `fadeIn` / `fadeOut`, and `save` for
-localStorage-backed persistence.
+check for:
+
+- **Effects and motion:** `ParticleEmitter`, `Trail` / `Trail3d`, `Tween` with
+  easing, the built-in `ShaderEffect` presets (vignette, scanline, chromatic
+  aberration, glow, outline, dissolve, bloom and more), `Light2d` / `Light3d`,
+  `viewport.shake` / `fadeIn` / `fadeOut`.
+- **UI:** `UIPanel` (laid out, scrolling, skinnable), `UITextButton`,
+  `UICheckbox` (a radio button with a `group`), `UISlider`, `ProgressBar`,
+  `UISpriteElement`, keyboard and gamepad navigation between widgets once one
+  has `focus()`, `NineSliceSprite`, `Draggable` / `DropTarget`, `BitmapText`.
+- **Art:** `TextureAtlas` (TexturePacker, ShoeBox, Aseprite),
+  `CanvasRenderTarget` for bake-once drawing, `NoiseTexture2d`.
+- **Game flow:** `state.transition()` (`"fade"`, `"mask"` or `"pixelate"`)
+  between screens, `state.pause()` / `state.resume()` behind a pause menu,
+  `save` for localStorage-backed persistence, `createPool` / `getPool` for
+  recycling.
+- **Levels:** Tiled tile layers read and changed with `cellAt` / `setTile`,
+  and asset bundles (`loader.preload({ common: [...], level1: [...] })`, then
+  `loader.unload("level1")` / `loader.load("level1")`) to free and reload a
+  level's assets.
+- **Physics and controls:** a rigid-body adapter (planck, matter or Rapier,
+  switched at run time with `world.setAdapter()`) rather than a hand-written
+  solver, and `@melonjs/gamepad-plugin` rather than hand-made touch sticks.

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-20-migration
-description: "Use this skill when writing melonJS code that may be based on pre-20.x knowledge, when migrating a game from melonJS 19.x or earlier, or when an API you expected does not exist. Covers the mandatory async Application.init(), the WebGL 2 baseline and WebGPU backend, renderable post effects replacing the shader property, and the deprecated exports still present. Triggers on: migration, upgrade, melonJS 19, me.game, me.video.init, renderable.shader, Compositor, CanvasTexture, me.Math, deprecated."
+description: "Use this skill when writing melonJS code that may be based on pre-20.x knowledge, when migrating a game from melonJS 19.x or earlier, or when an API you expected does not exist. Covers the mandatory async Application.init(), the WebGL 2 baseline and WebGPU backend, renderable post effects replacing the shader property, the deprecated exports still present, and what changed again during 20.x. Triggers on: migration, upgrade, melonJS 19, me.game, me.video.init, video.renderer, renderable.shader, Compositor, CanvasTexture, me.Math, pool.pull, pool.register, world.adapter, uvOffset, deprecated."
 license: MIT
 ---
 
@@ -43,7 +43,13 @@ none, and anything passed is ignored (settings come from the constructor).
 **`video.init(...)` no longer exists.** The `video` module now exports only the
 four renderer constants (`AUTO`, `CANVAS`, `WEBGL`, `WEBGPU`) — there is no
 `init` on it to call. Any code shaped like `me.video.init(800, 600, {...})` is
-from a removed API. Build an `Application` and await `init()`.
+from a removed API. Build an `Application` and await `init()`. Its siblings
+went with it: `video.renderer`, `video.createCanvas()` and `video.getParent()`
+are now `app.renderer`, `app.renderer.createCanvas()` and
+`app.getParentElement()`.
+
+`init()` runs once: a second call is ignored with a console warning, and after
+`app.destroy()` it throws. A destroyed `Application` is final; build a new one.
 
 Note that `import * as me from "melonjs"` still works, so `me.Sprite` style is
 fine. It is the *globals bootstrap* that is gone, not the namespace import.
@@ -77,6 +83,16 @@ Consequences:
   on either GPU backend.
 - Features needing a programmable pipeline are inert on Canvas and warn once
   rather than throwing.
+- Test capabilities, not the backend: `renderer.shaderLanguage` and
+  `renderer.supportsDepthBuffer` replace checks on `renderer.gl` or
+  `instanceof WebGLRenderer`, which answer "no" on WebGPU.
+  `renderer.WebGLVersion` is always `2` (deprecated), and the `preferWebGL1`
+  setting and the `#webgl1` URL flag are gone.
+- A custom WebGL batcher extends `WebGLBatcher` (`Batcher` is now the
+  backend-neutral base), and a custom shader on a `Mesh` receives model-space
+  geometry: position with
+  `uProjectionMatrix * uViewMatrix * uModelMatrix * vec4(aVertex, 1.0)` and
+  tint with `uTint`. Sprite and post-effect shaders are unchanged.
 
 ## 4. Deprecated exports still present
 
@@ -93,8 +109,14 @@ These resolve but should not be used in new code:
 | `renderable.shader = …` | 19.2.0 | `addPostEffect()` |
 | `Entity` | 18.1.0 | `Sprite` / `Renderable` + a `Body` |
 | `loader.onload` / `onProgress` / `onError` | 18.2.0, **removed 20.3** | the `LOADER_*` events, or `preload(assets, onloadcb)` |
-| `response.overlap` / `overlapN` / `overlapV` | — | `response.depth` / `response.normal` |
+| `response.overlap` / `overlapN` / `overlapV` | 19.5.0 | `response.depth` / `response.normal` |
 | `setLineWidth()` | 17.3.0 | the `lineWidth` property |
+| `pool.register` / `pool.pull` / `pool.push` | 18.0.0 (a console notice since 20.9) | `createPool()` / `getPool()`; `registerTiledObjectClass()` for a class a Tiled map names |
+| `body.fromJSON()`, a shape list given to `addShape()` | 20.7.0 (the `Body` constructor form throws) | `bodyDef = { type, shapes: "<json asset>", id }` |
+| `body.ignoreGravity` | 19.5.0 | `gravityScale = 0`, or `body.setGravityScale(0)` |
+| `app.updateAverageDelta` | 20.0.0 | `app.lastUpdateDelta` |
+| `loader.crossOrigin = …` / `loader.withCredentials = …` | 20.4.0 (assigning throws) | `loader.setOptions({ crossOrigin, withCredentials })` |
+| `UITextButton#bitmapText` | 20.13.0 | `label` |
 
 Two of these deserve emphasis:
 
@@ -128,6 +150,25 @@ feature is used. Transpile if you need older browsers, and note that transpiling
 handles *syntax* only: built-in methods need separate polyfills, which a
 bundler's `target` setting will never add.
 
+## 8. Changed again during 20.x
+
+Code written against an early 20.x release can still trip on these:
+
+- **`world.adapter` is read-only** (20.14): assigning it throws a
+  `TypeError`. `app.world.setAdapter(adapter)` switches adapters, rebuilding
+  every body from its `bodyDef`.
+- **`renderer.uvOffset` and the `textureSeamFix` setting are removed** (20.11).
+  Code that added `uvOffset` to a size should drop it.
+- **The engine's classes are no longer in the legacy pool** (20.9):
+  `pool.pull("Sprite")`, `pool.pull("Text")` and the other built-in names
+  throw `Cannot instantiate object of type`. Call the constructor, or
+  `getPool("text")`, `getPool("tween")`, `getPool("particle")`,
+  `getPool("colorLayer")` to recycle. `pool.register(name, Class, true)` no
+  longer returns an instance to the pool on removal either; `createPool` does.
+- **A container sorted on `"x"` or `"y"` re-sorts its children as they move**
+  (20.11, `autoSort` on by default). Turn `autoSort` off to keep an order set
+  by hand. A `"z"` sort is unchanged.
+
 ## The shipped examples are not all current
 
 The examples in this repository are the best reference for how melonJS is
@@ -139,10 +180,11 @@ from them:
   right; the comment is wrong.
 - Several examples assign `viewport.shader = …` / `sprite.shader = …`, which is
   deprecated. `addPostEffect()` is current.
-- Five files set `this.z = Number.POSITIVE_INFINITY` on a HUD. That property
-  does not exist; those HUDs draw on top only because they are added last.
-- `platformer/entities/player.ts` reads `response.overlapV`, the deprecated
-  field. Use `response.depth` / `response.normal`.
+- Three files (in `platformer-matter/` and `pool-matter/`) set
+  `this.z = Number.POSITIVE_INFINITY` on a HUD or a virtual joypad. That
+  property does not exist; they draw on top only because they are added last.
+- `platformer/entities/player.ts` and `enemies.ts` read `response.overlapV`,
+  the deprecated field. Use `response.depth` / `response.normal`.
 - Particle speeds tuned before 20.2 look wrong now: the particle transform fix
   changed how far a burst travels, and emitters were retuned upward to match.
 
@@ -153,6 +195,7 @@ from them:
 3. Is it using `renderable.shader =` instead of `addPostEffect()`?
 4. Is it importing a deprecated symbol from the table above?
 5. Is it referencing a global `game`?
+6. Is it relying on something section 8 lists as changed during 20.x?
 
 ## Related skills
 

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