melonjs 20.1.1 → 20.3.0

package/skills/melonjs-plugins/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: melonjs-plugins
+description: "Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered."
+license: MIT
+---
+
+# Plugins and adapters
+
+## Two different mechanisms
+
+This trips people up, so it is worth stating first:
+
+| | how it is installed |
+|---|---|
+| **Plugins** | `plugin.register(Class, name?, ...args)` — after `await app.init()` |
+| **Physics adapters** | an `Application` **setting** (`physic:`), before `init()` |
+
+```js
+// the adapter is chosen at construction …
+const app = new Application(800, 600, {
+    parent: "screen",
+    physic: new PlanckAdapter({ gravity, pixelsPerMeter }),
+});
+
+// … the plugin is registered once the renderer exists
+await app.init();
+plugin.register(DebugPanelPlugin, "debugPanel");
+```
+
+## `register` in detail
+
+```js
+plugin.register(PluginClass, "name", ...constructorArgs);
+plugin.cache.name;              // the instance
+plugin.get(PluginClass);        // by class — or by registered name string
+```
+
+- **The name is optional** — it falls back to the class name.
+- **The registry is global, not per-application.** It is a module-level object,
+  so registering the same name twice throws `plugin <name> already registered`.
+  A plugin *instance* does hold an `app` reference, but it defaults to `game` —
+  **whichever Application most recently finished `init()`**, since that is where
+  `game` is assigned. On a multi-application page, pass the app explicitly
+  through the constructor args:
+  `plugin.register(DebugPanelPlugin, "debugPanel", input.KEY.S, myApp)`.
+- **`BasePlugin.version` is a floor, not an identity.** It declares the
+  *minimum melonJS version the plugin needs*, and `register` throws
+  `Plugin version mismatch, expected: <floor>, got: <engine>` when the running
+  engine is older. That gate is the real enforcement — a peer-dependency range
+  only warns at install time, and not at all for CDN or pre-bundled use. If you
+  see that error, upgrade the engine or pin an older plugin. The check runs
+  *after* the instance is constructed, so a plugin whose constructor has side
+  effects will already have run them when it throws.
+
+Register after `await app.init()`: a plugin binds to an Application and reads
+renderer and frame state that does not exist before init.
+
+## The official plugins
+
+### `@melonjs/debug-plugin`
+
+An in-game panel — frame time, draw and object counts — plus toggles for
+hitbox/bounding-box overlays, velocity vectors and quadtree visualisation. The
+first thing to reach for when something is slow or a collision is not landing
+where you expect.
+
+```js
+import { DebugPanelPlugin } from "@melonjs/debug-plugin";
+plugin.register(DebugPanelPlugin, "debugPanel");   // default toggle key: S
+```
+
+### `@melonjs/tiled-inflate-plugin`
+
+**Required**, not optional, for Tiled maps using gzip, zlib or zstd layer
+compression. It installs the inflate hook `TMXUtils` calls; without it a
+compressed `.tmx` fails to parse — a map that opens fine in Tiled and refuses to
+load in melonJS is nearly always this.
+
+```js
+import { TiledInflatePlugin } from "@melonjs/tiled-inflate-plugin";
+plugin.register(TiledInflatePlugin);
+```
+
+### `@melonjs/spine-plugin`
+
+Spine 4.x skeletal animation as a melonJS renderable, on all three backends.
+This is the answer for deforming animated characters — glTF import does not read
+vertex skinning. It also registers a Tiled object class, so Spine skeletons can
+be placed from a map.
+
+### `@melonjs/capacitor-plugin`
+
+Bridges Capacitor's native lifecycle and hardware-back events into the engine:
+
+```js
+import { CapacitorPlugin } from "@melonjs/capacitor-plugin";
+plugin.register(CapacitorPlugin, "capacitor", options);
+// plugin.cache.capacitor.teardown()  — detach every listener
+```
+
+It also exports helpers usable on their own: `onBackButton`, `bindStageBack`,
+`lockOrientation` / `unlockOrientation`, `hideSplash`. See `melonjs-deployment`
+for the wider packaging picture.
+
+## Physics adapters
+
+`@melonjs/planck-adapter` and `@melonjs/matter-adapter` swap the physics world
+wholesale. Pick **one** per game. The portable surface — the declarative
+`renderable.bodyDef`, `world.adapter.queryAABB(rect)` and
+`world.adapter.raycast(from, to)` — works unchanged across the built-in world and
+both adapters, so entity code does not have to branch.
+
+Two queries are **not** portable: `querySphere` and `raycast3d` exist only on the
+built-in adapter (planck and matter are 2D-only and deliberately omit them).
+`queryAABB` is the one region query every adapter must implement, so call the
+others optionally — `app.world.adapter.querySphere?.(center, radius)`. For rays
+there is a real flag: `app.world.adapter.capabilities.raycasts3d`.
+
+Behaviour genuinely differs: velocity units, force magnitudes and where a body's
+position is measured from all change. See `melonjs-physics`.
+
+## Writing your own
+
+There is **no `init()` lifecycle hook** — the constructor is where setup goes,
+and `register` instantiates it for you.
+
+```js
+import { plugin, event } from "melonjs";
+
+class MyPlugin extends plugin.BasePlugin {
+    constructor(app = undefined) {
+        super(app);              // stores it as this.app
+        this.version = "20.0.0"; // MINIMUM engine version this needs
+        event.on(event.GAME_UPDATE, () => { /* … */ });
+    }
+}
+
+plugin.register(MyPlugin, "myPlugin");
+```
+
+`this.version` defaults to the running engine version, which means it always
+passes — set it deliberately to the oldest version you actually support.
+
+To wrap an existing engine method, `plugin.patch` keeps the original reachable
+as `this._patched()`:
+
+```js
+plugin.patch(app, "update", function (time) {
+    const result = this._patched(time);
+    return result;
+});
+```
+
+`patch` takes a class *or* an instance: given a constructor it patches the
+prototype (that is how the debug plugin decorates `Renderable.postDraw`), given a
+plain object it patches that object. `this._patched` is only bound for the
+synchronous duration of your replacement — it is set before the call and nulled
+straight after — so call it inline, never after an `await`.
+
+```js
+plugin.patch(Renderable, "postDraw", function (renderer) {
+    this._patched(renderer);
+    // draw an overlay on top of every renderable
+});
+```
+
+A plugin is the right shape when you need to augment engine classes or hook the
+engine lifecycle globally. For anything that is just game code, a `Renderable`
+or a `Stage` is simpler and easier to test.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| `plugin <name> already registered` | the registry is global; registered twice, often across hot reloads |
+| `Plugin version mismatch` | the plugin's `version` floor is above the running engine |
+| `Plugin should extend the BasePlugin Class !` | the class does not extend `plugin.BasePlugin` |
+| the panel reports another app's numbers | `app` defaulted to `game`, the last Application to finish `init()` |
+| `world.adapter.querySphere is not a function` | built-in adapter only; planck and matter are 2D-only |
+| a Tiled map opens in Tiled but not melonJS | compressed layers, tiled-inflate plugin missing |
+| plugin setup never runs | setup written in an `init()` method — there is no such hook |
+| `plugin.register` for an adapter does nothing | adapters are a construction setting, not a plugin |
+| physics behaves differently after adding an adapter | expected — units and force scales differ; re-tune |
+
+## Related skills
+
+- `melonjs-physics` — the adapters and their behavioural differences
+- `melonjs-tilemaps` — where the inflate plugin becomes mandatory
+- `melonjs-performance` — using the debug panel to measure
+- `melonjs-deployment` — Capacitor and native packaging
+- `melonjs-3d-assets` — why skeletal characters go through Spine

package/skills/melonjs-renderables/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: melonjs-renderables
+description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, and z-ordering. Triggers on: Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating."
+license: MIT
+---
+
+# Renderables, input and effects
+
+> Subclassing `Renderable`, custom drawing, receiving pointer events, and
+> applying post effects — with the traps that produce silently wrong output
+> rather than an error.
+
+Everything here is a **silent failure**: the code runs, nothing throws, and the
+result is wrong. Those are the cases worth memorising, because nothing in the
+type signatures warns you.
+
+## 1. A custom `draw()` must position itself from `this.pos`
+
+The renderer is **not** pre-translated to the renderable's position when `draw()`
+is called. `Container.draw` translates by the *container's* own `pos` and then
+calls `child.preDraw` / `draw` / `postDraw`; `preDraw` never translates by the
+child's `pos`. Read `this.pos` and draw relative to it.
+
+```js
+class Marker extends Renderable {
+    draw(renderer) {
+        // ✗ draws at the parent container's origin, not at the marker
+        renderer.fillRect(0, 0, this.width, this.height);
+
+        // ✓
+        renderer.fillRect(this.pos.x, this.pos.y, this.width, this.height);
+    }
+}
+```
+
+The symptom is an object that renders correctly at position (0, 0) and appears
+stuck at the top-left as soon as you move it.
+
+**Zero the anchor in custom-draw renderables.** `preDraw` does not translate to
+`pos`, but it *does* apply the anchor offset `(-width * anchorPoint.x,
+-height * anchorPoint.y)`. With the default centred anchor, drawing at
+`this.pos` therefore lands half a size off:
+
+```js
+constructor(x, y, w, h) {
+    super(x, y, w, h);
+    this.anchorPoint.set(0, 0);   // ← or every custom draw is offset by -w/2, -h/2
+}
+```
+
+## 2. `isKinematic` must be `false` to receive input or collisions
+
+`Renderable.isKinematic` **defaults to `true`**, which means *"physics collision
+and input events will not impact this renderable"*. A kinematic renderable is
+skipped by the pointer-event dispatcher entirely.
+
+```js
+class Button extends Renderable {
+    constructor(x, y) {
+        super(x, y, 100, 40);
+        this.isKinematic = false;          // ← required, or clicks never arrive
+        input.registerPointerEvent("pointerdown", this, () => { /* … */ });
+    }
+}
+```
+
+The symptom is a handler that is registered, looks correct, and never fires.
+
+Note that `Container`, `Camera2d`, `Draggable`, `DropTarget` and the `UI*`
+elements set it to `false` for you, and so does the `Body` constructor on its
+owner (which covers `Entity` and anything you give a body to) — so a plain
+`Renderable` or `Sprite` subclass with no body is the case that catches people.
+
+The same flag has a second, less obvious effect: it is also the opt-in to the
+world **broadphase**. The quadtree/octree insert skips any child with
+`isKinematic === true`, so body-less objects you want `adapter.queryAABB` /
+`querySphere` to find need `isKinematic = false` as well. The builtin
+narrowphase likewise requires *both* partners to be non-kinematic.
+
+## 3. Draw order: only `addChild(child, z)` works
+
+There are three separate traps here and they compound.
+
+```js
+world.addChild(sprite, 10);   // ✓ the only reliable form
+```
+
+1. **`renderable.z` does not exist.** There is no `z` accessor anywhere on
+   `Renderable` (nor on `Rect`/`Polygon` above it) — only `depth`, which proxies
+   `pos.z`, and the container's default `sortOn: "z"` comparator reads `pos.z`.
+   Writing `sprite.z = 100` creates an inert property that nothing reads.
+   Several shipped examples still contain `this.z = Number.POSITIVE_INFINITY`;
+   those HUDs draw on top only because they happen to be added last. (A `z` key
+   in a `Sprite`/`ImageLayer` *settings* object is a different thing and is real
+   — it assigns `pos.z` in the constructor — but trap 2 then overwrites it.)
+2. **Setting `depth` *before* `addChild` is overwritten.** With `autoDepth` on
+   (the default), `addChild` without an explicit `z` assigns
+   `child.pos.z = children.length` after the push, discarding whatever you set.
+3. **Setting `depth` *after* `addChild` does not reorder.** Containers sort when
+   a child is added (`autoSort`, deferred to the next tick), not when `pos.z`
+   changes. If you must change it later, call `container.sort()` yourself.
+
+The exception: under `Camera3d` the world's `sortOn` is `"depth"`, and the
+camera calls `container.sortNow(true)` every frame. Note that mode does **not**
+sort by `pos.z` as a layer index — it sorts by squared distance from the camera
+in world space (nearest first in the array, painted far→near). So changing
+`depth` does reorder there, but as a position change, not as a layer number.
+
+```js
+// ✗ overwritten by autoDepth
+sprite.depth = 10;
+world.addChild(sprite);
+
+// ✗ no resort happens (except under Camera3d)
+world.addChild(sprite);
+sprite.depth = 10;
+
+// ✓
+world.addChild(sprite, 10);
+```
+
+## 4. `removePostEffect()` destroys the effect
+
+To disable an effect temporarily, toggle it. Removing it frees its GPU
+resources and leaves you holding a dead object.
+
+```js
+// ✗ effect is destroyed; re-adding it will not work
+sprite.removePostEffect(effect);
+
+// ✓
+effect.enabled = false;
+```
+
+Exception worth knowing: an effect with `effect.shared === true` opts out of
+auto-destroy, because it is reused across renderables.
+
+Use `addPostEffect()` / `getPostEffect()` / `removePostEffect()`. Assigning
+`renderable.shader = …` is deprecated since 19.2.0.
+
+Post effects need a programmable pipeline. A `ShaderEffect` constructed against
+the Canvas renderer (`renderer.shaderLanguage === null`) logs a warning, stays
+at `enabled === false` and no-ops every method rather than throwing — and
+`beginPostEffect` filters disabled effects out. Since `video.AUTO` picks the
+backend at runtime, an effect that works on your machine may do nothing on
+another.
+
+## 5. `Vector3d.set(x, y)` silently zeroes `z`
+
+```js
+v.set(10, 20);        // z becomes 0, not "unchanged"
+v.set(10, 20, v.z);   // keep it
+```
+
+`pos` is an `ObservableVector3d`, whose `set(x = 0, y = 0, z = 0)` does the same
+— so `this.pos.set(x, y)` wipes the object's depth.
+
+## Update and draw
+
+```js
+class Enemy extends Renderable {
+    update(dt) {
+        this.pos.x += this.speed * (dt / 1000);
+        return true;                       // ← true means "redraw me"
+    }
+    draw(renderer) { /* … */ }
+}
+```
+
+`update()` returns a boolean meaning *"this object changed and needs
+redrawing"*. The parent accumulates it into the container's `isDirty`, and the
+application skips the whole draw pass while nothing is dirty — so returning
+nothing (falsy) can leave the scene frozen even though state is updating. The
+base implementation returns `this.isDirty`, so `return super.update(dt)` is the
+other correct ending.
+
+`update()` is only called when `obj.inViewport === true` or
+`obj.alwaysUpdate === true`. An off-screen object with the default
+`alwaysUpdate = false` does not tick at all.
+
+## Anchors and floating
+
+- `anchorPoint` defaults to centre `(0.5, 0.5)` on `Renderable`, but `Container`
+  forces `(0, 0)`. Mixing them up shifts children by half their size.
+- `floating = true` pins a renderable to the screen rather than the world, which
+  is what you want for HUD elements. It opts the object out of camera transforms
+  and out of ancestor position accumulation.
+
+## Prefer built-in features
+
+Before writing custom `draw()` code, check whether the engine already covers it —
+`ParticleEmitter`, `Tween`, the `ShaderEffect` presets, `UISpriteElement` and
+`UITextButton`, the physics adapters, and the Tiled tilemap renderers all exist.
+Hand-rolled equivalents miss the batching and the multi-backend support.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| object draws at its parent's origin, ignores its position | `draw()` not reading `this.pos` |
+| pointer handler registered but never fires | `isKinematic` left at its `true` default |
+| wrong draw order | anything other than `addChild(child, z)` — see section 3 |
+| effect cannot be re-enabled after removal | `removePostEffect()` destroyed it |
+| effect silently does nothing | running on the Canvas renderer |
+| object appears frozen while its state changes | `update()` not returning `true` |
+| off-screen object never ticks | `update()` is gated on `inViewport` — set `alwaysUpdate = true` |
+| custom draw offset by half the size | centred `anchorPoint` default not zeroed |
+| spatial query never finds an object | `isKinematic` left `true` — not in the broadphase |
+| `z` unexpectedly 0 after a `set` | `Vector3d.set(x, y)` defaults `z` to 0 |
+
+## Related skills
+
+- `melonjs-getting-started` — Application lifecycle and the scene graph
+- `melonjs-20-migration` — the deprecated `shader` property and other pre-20 APIs

package/skills/melonjs-renderer-backends/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: melonjs-renderer-backends
+description: "Use this skill when a feature works on one machine and not another, when choosing or pinning a renderer, or when writing code that must degrade gracefully. Covers the WebGPU to WebGL 2 to Canvas fallback ladder, what each backend supports, capability detection, and the subsystems that warn once and then stop working on Canvas. Triggers on: video.AUTO, video.WEBGPU, video.WEBGL, video.CANVAS, renderer.type, supportsDepthBuffer, shaderLanguage, WebGPU, WebGL2, Canvas fallback, context loss, backend, works on my machine."
+license: MIT
+---
+
+# Renderer backends and graceful degradation
+
+> `video.AUTO` picks a backend at **runtime**. The same code runs on a different
+> renderer depending on the machine, and several subsystems degrade to nothing
+> rather than erroring. This is the root cause of most "works on my machine"
+> reports.
+
+## The ladder
+
+`video.AUTO` (the default) tries **WebGPU → WebGL 2 → Canvas** and uses the first
+that initialises.
+
+```js
+const app = new Application(800, 600, {
+    parent: "screen",
+    renderer: video.AUTO,     // or video.WEBGPU / video.WEBGL / video.CANVAS
+});
+await app.init();
+```
+
+WebGL 1 is not in the ladder — 20.x made WebGL 2 the baseline, and pinning
+`video.WEBGL` **rejects** on a WebGL-1-only device rather than degrading.
+
+## What each backend can do
+
+| | WebGPU | WebGL 2 | Canvas |
+|---|---|---|---|
+| sprites, tilemaps, text | ✅ | ✅ | ✅ |
+| blend modes | ✅ | ✅ | ✅ except `"none"` |
+| shaders and post effects | ✅ | ✅ | ❌ inert |
+| `Light2d` glow (`drawLight`) | ✅ | ✅ | ✅ cached radial gradient |
+| normal-map lighting, `Light3d` | ✅ | ✅ | ❌ inert |
+| `Mesh` | ✅ | ✅ | ⚠️ CPU-projected, no depth |
+| `Camera3d` / depth sorting | ✅ | ✅ | ❌ warns, renders wrong |
+| `InstancedMesh` | ✅ | ✅ | ⚠️ one draw per instance |
+| GPU tilemap rendering | ✅ | ✅ | ❌ per-tile CPU path |
+
+The Canvas column is the problem: none of it throws. Each of those paths warns
+once and then degrades or no-ops, so the game runs and looks wrong.
+
+Two Canvas rows are worth spelling out because they are easy to misread as total
+failures. A `Light2d` still *draws* — the Canvas renderer bakes a radial gradient
+per light and blits it — what disappears is per-pixel normal-map shading, which
+warns once (`Light2d normal-map lighting requires the WebGL renderer`) and then
+renders sprites unlit. A `Mesh` still draws too, sorted with the painter's
+algorithm and no depth buffer, so convex models look right and anything
+self-overlapping does not. `"none"` (replace, alpha included) is the one blend
+mode Canvas cannot express — there is no `globalCompositeOperation` that
+disables blending for the drawn area alone — so it resolves to `"normal"`, and
+`setBlendMode` reports that back.
+
+## Detecting what you have
+
+```js
+app.renderer.type;                    // "WebGPU" | "WebGL2" | "CANVAS"
+app.renderer.supportsDepthBuffer;     // the practical "is this a GPU backend" test
+app.renderer.shaderLanguage;          // "wgsl" | "glsl" | null (null on Canvas)
+```
+
+There are narrower flags for the features that do not travel together:
+`supportsShaderTileLayers`, `supportsRetainedMesh` and `supportsInstancing` —
+all three `false` on Canvas, `true` on both GPU backends. Prefer a capability
+flag over comparing `type` against a string; `type` is an identity check for
+code coupled to one backend's machinery.
+
+For a scene that genuinely requires a GPU backend, fail loudly rather than
+rendering something broken:
+
+```js
+await app.init();
+if (!app.renderer.supportsDepthBuffer) {
+    throw new Error("this game needs WebGL 2 or WebGPU");
+}
+```
+
+## Writing code that degrades well
+
+**Decorative effects** — let them no-op. A missing vignette is fine.
+
+**Load-bearing effects** — guard the carrier. If a shader draws your content
+rather than decorating it, the carrier renderable shows through raw when the
+effect is disabled: a 1×1 white texture stretched to fill a quad renders as a
+white box exactly where the effect should have been.
+
+```js
+if (effect.enabled) {
+    // draw the carrier the shader consumes
+}
+```
+
+**Dual-language shaders** — a `ShaderEffect` compiles the body matching
+`renderer.shaderLanguage`. With no matching body — a GLSL-only effect on WebGPU,
+any effect on Canvas — the constructor warns once, leaves `enabled === false`,
+and every method becomes a no-op. Pass `{ glsl, wgsl }` rather than a bare
+string, or gate on `renderer.shaderLanguage`.
+
+## Pinning a backend
+
+Pin only with a reason. `video.WEBGL` costs you the WebGPU path *and* the Canvas
+fallback, so a WebGL-1-only device gets nothing at all.
+
+Legitimate reasons: reproducing a backend-specific bug, a benchmark, or a known
+driver issue in the field.
+
+For one-off testing you do not need to touch the settings at all: the URI
+fragments `#webgpu`, `#webgl` (or `#webgl2`) and `#canvas` override the
+`renderer` setting for that run, and behave exactly like passing the matching
+constant — `#webgl` on a WebGL-1-only device rejects rather than falling back.
+
+## Context loss
+
+A GPU context can be lost at any time — tab backgrounding, driver reset, memory
+pressure. melonJS handles restoration on both GPU backends: WebGL recompiles
+every live `GLShader` and replays its uniform snapshot, WebGPU renegotiates a
+device and rebuilds its batchers, and both then emit
+`event.ONCONTEXT_RESTORED` (the paired loss event is `event.ONCONTEXT_LOST`).
+
+What you must handle is your own GPU-side state. If you cached a raw texture or
+program handle, re-acquire it on restore rather than holding the stale one:
+
+```js
+import { event } from "melonjs";
+
+event.on(event.ONCONTEXT_RESTORED, (renderer) => {
+    // re-acquire anything you were holding by raw handle
+});
+```
+
+## Practical differences
+
+- **Frame capture orientation differs**: row 0 of a `toFrameTexture()` capture is
+  the bottom of the frame under WebGL and the *top* under WebGPU, so a GLSL body
+  that flips with `1.0 - uv.y` must not do so in its WGSL twin. The WebGPU
+  capture also preserves alpha, where the WebGL one captures into an opaque RGB
+  texture.
+- **The advanced blend modes cost far more than they look.** `overlay`,
+  `difference`, `hard-light`, `soft-light`, `color-dodge`, `color-burn`,
+  `darken` and `lighten` cannot be expressed as fixed-function blending, so on
+  both GPU backends each such draw is bracketed individually: capture the
+  destination, redraw offscreen, composite through `BlendEffect`. Fine for
+  accents, ruinous for hundreds of objects. `normal`, `additive`, `multiply`,
+  `screen` and `exclusion` are ordinary fixed-function state and cost nothing
+  extra.
+- **3D meshes do not honour blend modes.** The mesh pass draws with its own
+  depth/blend state; asking for one of the advanced modes logs a one-time
+  `blend mode "…" is not supported for 3D meshes` warning and falls back to
+  `"normal"`. Gradient fills warn the same way.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| effect works locally, not for a user | they got the Canvas fallback, or a different GPU backend |
+| sprites render unlit though lights are in the scene | Canvas fallback — normal-map shading is inert (check the console) |
+| mesh looks inside-out where it overlaps itself | Canvas fallback — painter's algorithm, no depth buffer |
+| shader works on one machine only | GLSL-only effect, AUTO chose WebGPU elsewhere — the console carries the warning |
+| a solid box where an effect should be | carrier drawn while the effect is disabled |
+| nothing renders at all on an old device | `video.WEBGL` pinned; WebGL 1 is rejected, not downgraded |
+| ported shader is vertically flipped | the WebGL capture is bottom-up, the WebGPU one top-down |
+| a blended mode is ignored on a mesh | meshes fall back to `"normal"`; look for the one-time warning |
+| textures vanish after the tab is restored | cached raw GPU handles not re-acquired on context restore |
+
+## Related skills
+
+- `melonjs-getting-started` — renderer selection in the Application settings
+- `melonjs-effects-and-shaders` — dual-language shaders and the Canvas no-op
+- `melonjs-3d` — the tier that requires a GPU backend outright