melonjs 20.1.1 → 20.3.0

package/skills/melonjs/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: melonjs
+description: "Use this skill FIRST for any melonJS task; it routes to the right specialised skill and lists the companion packages. melonJS is an open-source 2D, 2.5D and 3D HTML5 game engine running on WebGPU, WebGL 2 or Canvas. Covers Application setup, the scene graph, renderables, sprites, tilemaps, physics, audio, particles, shaders, and the 3D tier — perspective cameras, meshes and glTF scenes. Triggers on: melonjs, melonJS, me.game, Application, app.init, app.world, Renderable, Sprite, Stage, state.change, Camera2d, Camera3d, Mesh, tilemap, Tiled, TMX, ParticleEmitter, ShaderEffect, how do I make a game, HTML5 game engine."
+license: MIT
+---
+
+# melonJS
+
+Entry point for the melonJS skill collection. melonJS is an open-source HTML5
+game engine for indie developers, covering 2D, 2.5D and 3D — perspective and
+orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects,
+custom shaders, 3D meshes, polygon-accurate physics and modern Tiled workflows.
+It runs on WebGPU, WebGL 2 or Canvas with automatic fallback, and has no runtime
+dependencies.
+
+## How to use this skill
+
+1. Find the specialised skill below that matches the task and follow it.
+2. If the task involves anything 3D, read `melonjs-3d` **first** — melonJS's
+   coordinate conventions are the inverse of OpenGL's, so untutored 3D instincts
+   are backwards.
+3. If you are writing melonJS from prior knowledge rather than from the current
+   docs, read `melonjs-20-migration` — most published melonJS material predates
+   20.0 and its bootstrap no longer exists.
+4. If none of them covers the task, use the escape hatch below rather than
+   guessing at an API.
+
+## Skill router
+
+| Skill | Load when… |
+|---|---|
+| [melonjs-getting-started](../melonjs-getting-started/SKILL.md) | Bootstrapping a game, `new Application`, `await app.init()`, choosing a renderer, preloading assets. |
+| [melonjs-20-migration](../melonjs-20-migration/SKILL.md) | Code based on melonJS 19.x or earlier, or an API that "should exist" but doesn't — `video.init`, `Entity`, `renderable.shader =`. |
+| [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-tilemaps](../melonjs-tilemaps/SKILL.md) | Tiled maps — TMX/TSX loading, spawning entities from objects, collision layers, isometric maps. |
+| [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`, 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-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-renderer-backends](../melonjs-renderer-backends/SKILL.md) | A feature works on one machine but not another; choosing or pinning a backend; degrading gracefully. |
+| [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. |
+
+
+## Escape hatch: the full API index
+
+These skills are hand-written and deliberately partial — they cover the paths
+people actually take and the mistakes those paths invite. When the task needs
+something they do not mention, do **not** infer an API from the shape of the
+engine. Fetch the generated index instead:
+
+<https://melonjs.github.io/melonJS/llms.txt>
+
+It is regenerated on every docs build from the same TSDoc comments the reference
+pages render, so it is always current for `master`. It lists every exported
+class, function, interface, type and namespace with a one-line summary and a
+link to its page — fetch the pages you need from there.
+
+Two things it gives you that this collection cannot:
+
+- **Members.** The skills name classes; `llms.txt` links to the page listing
+  every method, property, default and `@since` tag on them.
+- **Deprecations.** Entries marked `**deprecated**` are exactly the APIs that a
+  model trained on older melonJS material will reach for. If something you were
+  about to write appears with that marker, follow the page for the replacement.
+
+If a class, function, namespace or type is absent from `llms.txt`, it is absent
+from the engine's public API — that is the useful negative answer, and it is
+worth acting on rather than writing code around something that does not exist.
+The index lists top-level exports only, so a *member* missing from it proves
+nothing: follow the owning class's page to check that.
+
+## The three rules that catch everyone
+
+Whatever the task, these produce code that runs and is wrong:
+
+1. **`await app.init()` is mandatory** since 20.0. The constructor builds the
+   world but not the renderer: a plain renderable can still be added and simply
+   never draws, while `new Sprite(...)` / `new Text(...)` throw a `TypeError`
+   on the global `game`, which is unset until the first `init()` resolves.
+   Neither symptom names the missing call.
+2. **`addChild(child, z)` is the only way to set draw order.** `renderable.z`
+   does not exist; setting `depth` before `addChild` is overwritten, and setting
+   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`.
+
+## Companion packages
+
+melonJS ships optional packages alongside the engine. Reach for these rather
+than reimplementing what they cover — and note the physics adapters and the
+Tiled inflate plugin are *required* for their use cases, not merely convenient.
+
+| Package | Use when |
+|---|---|
+| [`@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/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/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. |
+
+Plugins are registered **after** `init()`, into a global registry:
+
+```js
+import { plugin } from "melonjs";
+import { DebugPanelPlugin } from "@melonjs/debug-plugin";
+
+await app.init();
+plugin.register(DebugPanelPlugin, "debugPanel");
+```
+
+Physics adapters are different — they are an `Application` setting, not a
+plugin:
+
+```js
+import { PlanckAdapter } from "@melonjs/planck-adapter";
+
+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({
+        gravity: { x: 0, y: 320 },
+        pixelsPerMeter: 32,
+        subSteps: 2,
+    }),
+});
+await app.init();
+```
+
+`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.

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

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

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

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