melonjs-renderer-backends

1# Renderer backends and graceful degradation
2 
3> `video.AUTO` picks a backend at **runtime**. The same code runs on a different
4> renderer depending on the machine, and several subsystems degrade to nothing
5> rather than erroring. This is the root cause of most "works on my machine"
6> reports.
7 
8## The ladder
9 
10`video.AUTO` (the default) tries **WebGPU → WebGL 2 → Canvas** and uses the first
11that initialises.
12 
13```js
14const app = new Application(800, 600, {
15    parent: "screen",
16    renderer: video.AUTO,     // or video.WEBGPU / video.WEBGL / video.CANVAS
17});
18await app.init();
19```
20 
21WebGL 1 is not in the ladder — 20.x made WebGL 2 the baseline, and pinning
22`video.WEBGL` **rejects** on a WebGL-1-only device rather than degrading.
23 
24## What each backend can do
25 
26| | WebGPU | WebGL 2 | Canvas |
27|---|---|---|---|
28| sprites, tilemaps, text | ✅ | ✅ | ✅ |
29| blend modes | ✅ | ✅ | ✅ except `"none"` |
30| shaders and post effects | ✅ | ✅ | ❌ inert |
31| `Light2d` glow (`drawLight`) | ✅ | ✅ | ✅ cached radial gradient |
32| normal-map lighting, `Light3d` | ✅ | ✅ | ❌ inert |
33| `Mesh` | ✅ | ✅ | ⚠️ CPU-projected, no depth |
34| `Camera3d` / depth sorting | ✅ | ✅ | ❌ warns, renders wrong |
35| `InstancedMesh` | ✅ | ✅ | ⚠️ one draw per instance |
36| GPU tilemap rendering | ✅ | ✅ | ❌ per-tile CPU path |
37 
38The Canvas column is the problem: none of it throws. Each of those paths warns
39once and then degrades or no-ops, so the game runs and looks wrong.
40…