melonjs 20.2.0 → 20.4.0

package/build/video/webgpu/texture/store.d.ts

@@ -1,149 +1,3 @@
-/**
- * Renderer-owned GPU texture store for the WebGPU backend — the counterpart
- * of `MaterialBatcher`'s createTexture2D/bindTexture2D/deleteTexture2D tier,
- * kept on the renderer (rather than a batcher) so the quad path and the
- * future mesh / tile-layer paths share one resident-texture map.
- *
- * The engine-side bookkeeping is untouched: `TextureCache` still allocates
- * the logical "unit" for each `(source, repeat)` pair; here a unit keys a
- * `{GPUTexture, view, bind groups}` record instead of a GL texture binding.
- * Bind groups pair the texture view with a cached `GPUSampler` — one bind
- * group per (texture, sampler) combination, invalidated wholesale when the
- * filter setting changes (textures stay resident; only the pairing is
- * rebuilt — the WebGPU analogue of `_reapplyTextureFilter`, without the
- * re-parameterization).
- * @ignore
- */
-export default class WebGPUTextureStore extends TextureStore {
-    /**
-     * @param {import("../webgpu_renderer.js").default} renderer - the owning renderer
-     */
-    constructor(renderer: import("../webgpu_renderer.js").default);
-    renderer: import("../webgpu_renderer.js").default;
-    device: GPUDevice | undefined;
-    /** @type {Map<string, GPUSampler>} */
-    samplers: Map<string, GPUSampler>;
-    onCacheReset: () => void;
-    /**
-     * resolve (creating on first use) the sampler for a filter/wrap combo
-     * @param {string} filter - "nearest" | "linear"
-     * @param {string} repeat - engine wrap mode string
-     * @returns {GPUSampler} the sampler
-     * @ignore
-     */
-    getSampler(filter: string, repeat: string, mipmaps?: boolean): GPUSampler;
-    /**
-     * The per-draw entry point: resolve the atlas to a bind group pairing
-     * its resident GPU texture with the currently-applicable sampler,
-     * uploading the source on first use (or re-uploading when forced — the
-     * video-frame path).
-     * @param {object} texture - a TextureAtlas
-     * @param {object} [options] - resolution options
-     * @param {boolean} [options.force=false] - re-upload the source pixels
-     * @param {string} [options.repeat] - per-use wrap override (else texture.repeat)
-     * @returns {GPUBindGroup} the material bind group for this draw
-     */
-    getBinding(texture: object, options?: {
-        force?: boolean | undefined;
-        repeat?: string | undefined;
-    }): GPUBindGroup;
-    lastRecord: {
-        handle: any;
-        version: number;
-        generation: number;
-    } | undefined;
-    /**
-     * Build the full mip chain of a freshly-uploaded record: one blit pass
-     * per level, each rendering the previous level with linear filtering.
-     * Runs in its own encoder submitted immediately — queue ordering places
-     * it after the level-0 copy (a queue operation) and before the frame's
-     * own command buffer, so the frame's draws sample a complete chain.
-     * @param {object} record - the resident record (mipLevelCount > 1)
-     * @ignore
-     */
-    generateMipmaps(record: object): void;
-    mipLayout: GPUBindGroupLayout | undefined;
-    mipPipeline: GPURenderPipeline | undefined;
-    mipSampler: GPUSampler | undefined;
-    /**
-     * Resolve the view + sampler a resident record should be bound with,
-     * plus the cache key identifying that pair. Shared by the one-texture
-     * material path and the mesh path, so the two cannot drift on which
-     * view a mip-wanting consumer gets.
-     * @ignore
-     */
-    viewAndSampler(record: any, texture: any, wrap: any, wantMips: any): {
-        view: any;
-        sampler: GPUSampler;
-        key: string;
-    };
-    /**
-     * The group-1 material for a MESH: the diffuse texture/sampler pair plus
-     * the per-texel opacity pair (MTL `map_d`, #1575).
-     *
-     * Always four bindings. A mesh with no alpha map passes the shared white
-     * pixel, whose red channel is 1 — so the shader's multiply is a no-op and
-     * the same pipeline layout serves both cases rather than splitting the
-     * mesh family in two.
-     * @param {TextureAtlas} texture - the diffuse texture
-     * @param {TextureAtlas} alphaTexture - the opacity map, or the white pixel
-     * @param {object} [options] - wrap / mipmap options, as `getBinding` takes
-     * @returns {GPUBindGroup} the group-1 bind group
-     * @ignore
-     */
-    getMeshBinding(texture: TextureAtlas, alphaTexture: TextureAtlas, options?: object): GPUBindGroup;
-    /**
-     * the per-sampler material bind group for a resident record (shared by
-     * the image and compressed upload paths)
-     * @ignore
-     */
-    bindGroupFor(record: any, texture: any, wrap: any, wantMips?: boolean): any;
-    /**
-     * Ensure the texture is resident (same upload/validation path as
-     * getBinding) and return its record — callers composing their own bind
-     * groups (the lit batcher pairs the color view with a normal map) need
-     * the raw view rather than the standard material group.
-     * @param {object} texture - the texture atlas to resolve
-     * @param {object} [options] - same options as getBinding
-     * @returns {object} the resident record ({texture, view, width, height, …})
-     */
-    getResidentRecord(texture: object, options?: object): object;
-    /**
-     * Dispose of a GPUTexture safely: while a frame is being recorded the
-     * texture may be referenced by already-recorded draws (destroying it
-     * would make `queue.submit()` reject the whole command buffer), so it
-     * parks on the renderer's retired list and is destroyed after submit.
-     * @param {GPUTexture} gpuTexture - the texture to dispose of
-     * @ignore
-     */
-    retire(gpuTexture: GPUTexture): void;
-    /**
-     * drop every (texture, sampler) bind-group pairing while keeping the
-     * textures resident — the filter setting changed and the next draw
-     * re-pairs each texture with the newly-resolved sampler
-     */
-    invalidateBindGroups(): void;
-    /**
-     * Destroy the resident GPU texture(s) associated with an image — every
-     * `(source, repeat)` unit the cache knows about, mirroring
-     * `MaterialBatcher.deleteTexture2D`'s multi-repeat sweep.
-     * @param {object} texture - a TextureAtlas
-     */
-    destroyTexture(texture: object): void;
-    /**
-     * drop every unit association and dispose of the resident textures
-     */
-    /**
-     * Release the GPU texture behind a record. The base calls this; the device
-     * defers the actual destroy until the frame that referenced it has retired.
-     * @param {GPUTexture} handle - the texture to release
-     * @ignore
-     */
-    onDestroy(handle: GPUTexture): void;
-    /**
-     * full teardown (device loss / renderer destroy)
-     */
-    destroy(): void;
-}
+
 import { TextureStore } from "../../gpu/texturestore.js";
 //# sourceMappingURL=store.d.ts.map

package/build/video/webgpu/texture/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/video/webgpu/texture/store.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH;IACC;;OAEG;IACH,sBAFW,OAAO,uBAAuB,EAAE,OAAO,EAoBjD;IAhBA,kDAAwB;IACxB,8BAA6B;IAC7B,sCAAsC;IACtC,UADW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CACT;IAKzB,yBAMC;IAIF;;;;;;OAMG;IACH,mBALW,MAAM,UACN,MAAM,sBACJ,UAAU,CAkCtB;IAED;;;;;;;;;;OAUG;IACH,oBANW,MAAM,YAEd;QAA0B,KAAK;QACN,MAAM;KAC/B,GAAU,YAAY,CAuMxB;IAlHE;;;;kBAAwB;IAoH3B;;;;;;;;OAQG;IACH,wBAHW,MAAM,QAyEhB;IA/DC,0CAME;IAIF,2CAYE;IACF,mCAIE;IAsCJ;;;;;;OAMG;IACH;;;;MAqBC;IAED;;;;;;;;;;;;;OAaG;IACH,wBANW,YAAY,gBACZ,YAAY,YACZ,MAAM,GACJ,YAAY,CAmExB;IAED;;;;OAIG;IACH,4EAeC;IAED;;;;;;;;OAQG;IACH,2BAJW,MAAM,YACN,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;OAOG;IACH,mBAHW,UAAU,QAKpB;IAED;;;;OAIG;IACH,6BAIC;IAED;;;;;OAKG;IACH,wBAFW,MAAM,QAchB;IAED;;OAEG;IACH;;;;;OAKG;IACH,kBAHW,UAAU,QAKpB;IAED;;OAEG;IACH,gBAIC;CACD;6BAzkB4B,2BAA2B"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/video/webgpu/texture/store.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;GAgBG;AACH;IACC;;OAEG;IACH,sBAFW,OAAO,uBAAuB,EAAE,OAAO,EAoBjD;IAhBA,kDAAwB;IACxB,8BAA6B;IAC7B,sCAAsC;IACtC,UADW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CACT;IAKzB,yBAMC;IAIF;;;;;;;OAOG;IACH,mBANW,MAAM,UACN,MAAM,sBACJ,UAAU,CAmCtB;IAED;;;;;;;;;;OAUG;IACH,oBANW,MAAM,YAEd;QAA0B,KAAK;QACN,MAAM;KAC/B,GAAU,YAAY,CAuMxB;IAjHE;;;;kBAAwB;IAmH3B;;;;;;;;;OASG;IACH,wBAJW,MAAM,QA0EhB;IA/DC,0CAME;IAIF,2CAYE;IACF,mCAIE;IAsCJ;;;;;;;OAOG;IACH;;;;MAqBC;IAED;;;;;;;;;;;;;;OAcG;IACH,wBAPW,YAAY,gBACZ,YAAY,YACZ,MAAM,GACJ,YAAY,CAoExB;IAED;;;;;OAKG;IACH,4EAeC;IAED;;;;;;;;OAQG;IACH,2BAJW,MAAM,YACN,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;OAQG;IACH,mBAJW,UAAU,QAMpB;IAED;;;;OAIG;IACH,6BAIC;IAED;;;;;OAKG;IACH,wBAFW,MAAM,QAchB;IAED;;OAEG;IACH;;;;;;OAMG;IACH,kBAJW,UAAU,QAMpB;IAED;;OAEG;IACH,gBAIC;CACD;6BApmB4B,2BAA2B"}

package/build/video/webgpu/webgpu_renderer.d.ts

@@ -30,14 +30,12 @@ export default class WebGPURenderer extends Renderer {
     readonly adapter: GPUAdapter | undefined;
     /**
      * The WebGPU device, set once {@link WebGPURenderer#init} resolves.
-     * @name device
      * @type {GPUDevice|undefined}
      * @readonly
      */
     readonly device: GPUDevice | undefined;
     /**
      * The WebGPU canvas context
-     * @name context
      * @type {GPUCanvasContext}
      */
     context: GPUCanvasContext;
@@ -50,37 +48,6 @@ export default class WebGPURenderer extends Renderer {
     readonly preferredFormat: string | undefined;
     cache: TextureCache;
     currentTransform: Matrix3d;
-    /**
-     * Advanced-blend state — the WebGPU twin of the WebGL bracket, and
-     * deliberately the same shape. The six CSS modes fixed-function
-     * cannot express are composited by capturing the destination,
-     * rendering the draw to an offscreen target, then blitting that
-     * through {@link BlendEffect}. All lazily created.
-     *
-     * `_advancedBlendBusy` is a DEPTH, not a flag: the bracket nests
-     * inside itself (the composite blit re-enters `setBatcher`).
-     *
-     * One documented difference from WebGL: masks need no handling here.
-     * `beginPass` attaches the shared depth/stencil texture whatever the
-     * current target is, so an armed mask clips the offscreen draw
-     * directly — where the GL backend has to disable the test (its
-     * offscreen FBO owns a separate, zeroed stencil) and let the
-     * composite carry the clip instead. Same result, different route.
-     * @ignore
-     */
-    _advancedBlendEffect: BlendEffect | undefined;
-    /** @ignore */
-    _advancedBlendCapture: any;
-    /** @ignore */
-    _advancedBlendTarget: WebGPURenderTarget | undefined;
-    /** @ignore */
-    _advancedBlendOpen: boolean;
-    /** @ignore */
-    _advancedBlendBusy: number;
-    /** @ignore */
-    _advancedBlendParent: WebGPURenderTarget | null;
-    /** @ignore */
-    _advancedBlendWarned: Set<any>;
     onGameReset: () => void;
     onCanvasResize: () => void;
     GPUVendor: string | undefined;
@@ -133,8 +100,6 @@ export default class WebGPURenderer extends Renderer {
             height: number;
         } | undefined;
     }): Texture2d | null;
-    /** @ignore */
-    _toFrameTexture(options?: {}): any;
     /**
      * Draw a pooled render target through an effect's pipeline as a
      * screen-space quad — the compositing primitive of the post-effect
@@ -151,35 +116,6 @@ export default class WebGPURenderer extends Renderer {
      * @override
      */
     override blitEffect(source: import("../rendertarget/webgpurendertarget.js").default, x: number, y: number, width: number, height: number, effect: ShaderEffect, keepBlend?: boolean): void;
-    /**
-     * Say once, per excluded path and mode, that an advanced blend mode is
-     * falling back to `"normal"`. A silent data-dependent fallback is exactly
-     * what the advanced-blend work exists to remove, so the exclusions are
-     * loud.
-     * @param {string} what - the excluded path, named for the message
-     * @ignore
-     */
-    _warnAdvancedBlendFallback(what: string): void;
-    /**
-     * Close a pending advanced-blend bracket, if one is open and we are not
-     * already inside the bracket machinery.
-     * @ignore
-     */
-    _drainAdvancedBlend(): void;
-    /**
-     * Open an advanced-blend bracket: capture the destination, then redirect
-     * this draw into an offscreen target.
-     * @returns {boolean} false when the effect could not be realized, in which
-     * case the draw proceeds unbracketed (plain source-over)
-     * @ignore
-     */
-    _openAdvancedBlend(): boolean;
-    /**
-     * Close an advanced-blend bracket: drain the offscreen, retarget to the
-     * parent, and composite through {@link BlendEffect}.
-     * @ignore
-     */
-    _closeAdvancedBlend(): void;
     /**
      * Clear the current clip region with the given color — a full-viewport
      * triangle clipped by the active scissor, drawn with blending replaced
@@ -231,30 +167,6 @@ export default class WebGPURenderer extends Renderer {
      * @returns {WebGPUBatcher} the now-active batcher
      */
     setBatcher(name?: string): WebGPUBatcher;
-    /**
-     * Draw a textured triangle mesh — the mesh-path contract of the base
-     * renderer, on this backend's pipeline-state model. Unlike GL there is
-     * no device state to toggle: depth testing (write + LEQUAL) and the
-     * per-mesh face culling are axes of the pipeline the mesh batcher
-     * looks up per flush, and the once-per-target depth clear is the
-     * pass's `depthLoadOp` (armed by `clear()`/`setRenderTarget`).
-     * @param {object} mesh - a Mesh object with vertices, uvs, indices, and texture properties
-     * @param {Matrix3d} [modelMatrix] - the mesh's model matrix. When given,
-     *   the mesh is drawn from persistent model-space geometry and placed
-     *   entirely by uniforms; when omitted, its vertices are taken as
-     *   already positioned and accumulated through the batcher (the
-     *   2D-camera path).
-     * @override
-     */
-    /**
-     * Draw one ground shadow per instance of an `InstancedMesh` (#1515), in a
-     * single recorded call over the mesh's own instance buffer.
-     * @param {InstancedMesh} mesh - the mesh casting the shadows
-     * @param {Matrix3d} shadowMatrix - the group matrix flattened onto the ground
-     * @param {object} quad - the shared shadow quad
-     * @ignore
-     */
-    drawInstancedShadow(mesh: InstancedMesh, shadowMatrix: Matrix3d, quad: object): void;
     drawMesh(mesh: any, modelMatrix: any): void;
     /**
      * Release any retained geometry held for the given mesh (called from
@@ -290,7 +202,8 @@ export default class WebGPURenderer extends Renderer {
     getGlobalAlpha(): number;
     /**
      * set the current blend mode for this renderer. <br>
-     * Every renderer supports the full set: <br>
+     * Both GPU renderers support the full set — the Canvas fallback supports
+     * every mode below except `"none"`: <br>
      * - "normal" : draws new content on top of the existing content <br>
      * <img src="../images/normal-blendmode.png" width="180"/> <br>
      * - "add", "additive", or "lighter" : color values are added together <br>

package/build/video/webgpu/webgpu_renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webgpu_renderer.d.ts","sourceRoot":"","sources":["../../../src/video/webgpu/webgpu_renderer.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"webgpu_renderer.d.ts","sourceRoot":"","sources":["../../../src/video/webgpu/webgpu_renderer.js"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "melonjs",
-	"version": "20.2.0",
+	"version": "20.4.0",
 	"description": "melonJS Game Engine",
 	"homepage": "http://www.melonjs.org/",
 	"type": "module",
@@ -50,16 +50,12 @@
 	},
 	"files": [
 		"build",
-		"package.json",
+		"skills",
 		"README.md",
-		"CHANGELOG"
+		"CHANGELOG",
+		"package.json"
 	],
-	"dependencies": {
-		"core-js": "^3.48.0",
-		"howler": "2.2.4"
-	},
 	"devDependencies": {
-		"@types/howler": "^2.2.13",
 		"@types/node": "^25.6.0",
 		"concurrently": "^9.2.1",
 		"del-cli": "^7.0.0",
@@ -81,12 +77,13 @@
 		"build": "pnpm lint && tsx scripts/build.js && pnpm types",
 		"dist": "pnpm clean && pnpm lint && pnpm vitest run && pnpm build && pnpm doc && cp ../../README.md .",
 		"dist:publish": "pnpm clean && pnpm lint && pnpm build && pnpm doc && cp ../../README.md .",
-		"doc": "tsx scripts/check-doc-readme.ts && typedoc src/index.ts --tsconfig tsconfig.build.json --readme ../../DOC_README.md --hideGenerator --name 'melonJS' --navigation.includeCategories true --categorizeByGroup false",
-		"doc:watch": "typedoc src/index.ts --tsconfig tsconfig.build.json --readme ../../DOC_README.md --hideGenerator --name 'melonJS' --navigation.includeCategories true --categorizeByGroup false --watch --skipErrorChecking --preserveWatchOutput --logLevel Error",
+		"doc": "tsx scripts/check-doc-readme.ts && pnpm doc:css && typedoc && tsx scripts/generate-llms-txt.ts",
+		"doc:watch": "typedoc --watch --skipErrorChecking --preserveWatchOutput --logLevel Error",
 		"serve": "serve docs",
 		"prepublishOnly": "pnpm dist:publish",
 		"clean": "tsx scripts/clean.ts",
 		"types": "tsc --project tsconfig.build.json && tsx scripts/strip-internal.ts",
-		"test:types": "tsc"
+		"test:types": "tsc",
+		"doc:css": "cat scripts/docs/brand.css scripts/docs/copy-page.css > scripts/docs/.docs.css"
 	}
 }

package/skills/AGENTS.md

@@ -0,0 +1,67 @@
+# melonJS — agent instructions
+
+> **This is a template for a game that *uses* melonJS, not instructions for
+> working on the engine itself.** Copy it to your own project root:
+>
+> ```bash
+> cp node_modules/melonjs/skills/AGENTS.md ./AGENTS.md
+> ```
+>
+> Already have an `AGENTS.md`? Paste the sections below into it. Codex, Cursor,
+> Gemini CLI and anything else following the `AGENTS.md` convention will read it
+> from your project root. Claude Code users should install the plugin instead —
+> `/plugin marketplace add melonjs/melonJS` — which registers the same guidance
+> as 23 routed skills.
+
+This project uses **melonJS 20.x**, an open-source HTML5 game engine covering
+2D, 2.5D and 3D, running on WebGPU, WebGL 2 or Canvas with automatic fallback.
+
+## Read these before writing engine code
+
+Task-oriented guides ship with the package at `node_modules/melonjs/skills/`,
+one directory per subsystem, each ending with a symptom → cause table.
+
+**Start at `node_modules/melonjs/skills/melonjs/SKILL.md`** — it routes to the
+right one for the task. Do not read all of them; read the router, then the one
+or two it points at.
+
+For anything the guides do not cover, fetch
+<https://melonjs.github.io/melonJS/llms.txt> — an index of every exported class,
+function and type with a one-line summary and a link to its reference page,
+regenerated on every docs build. Deprecated entries are marked. Do not infer an
+API from the shape of the engine; look it up.
+
+## Three rules that produce code which runs and is wrong
+
+1. **`await app.init()` is mandatory** since 20.0. The `Application` constructor
+   builds the world but no renderer, so `addChild` silently succeeds while
+   `new Sprite(...)` throws a `TypeError` that names neither the class nor 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 by
+   `autoDepth`; setting it after does not resort.
+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` — attaching a `Body`
+   sets it for you.
+
+## Most melonJS bugs are silent, not fatal
+
+The engine warns and degrades rather than throwing. A shader effect on the
+Canvas fallback, a `Camera3d` without a GPU backend, a pooled object whose
+`onResetEvent` forgets a property — all render *something*. When output looks
+wrong rather than crashing, check the console for a one-shot warning and consult
+the relevant skill's symptom table before debugging the game logic.
+
+## Prefer built-in features
+
+Before hand-rolling: `ParticleEmitter`, `Trail`, `Tween`, the built-in
+`ShaderEffect` presets, `Light2d` / `Light3d`, `UIBaseElement` /
+`UITextButton`, `NineSliceSprite`, `TextureAtlas`, `BitmapText`,
+`CanvasRenderTarget` for bake-once drawing, `viewport.shake` / `fadeIn` /
+`fadeOut`, and `save` for persistence.
+
+Companion packages cover the rest: `@melonjs/planck-adapter` and
+`@melonjs/matter-adapter` (physics), `@melonjs/spine-plugin` (skeletal
+animation), `@melonjs/tiled-inflate-plugin` (**required** for compressed Tiled
+maps), `@melonjs/debug-plugin`, `@melonjs/capacitor-plugin`.

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`, 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-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.