melonjs-renderer-backends
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.
melonjs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-renderer-backends技能说明
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.AUTOpicks 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.
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 a GPU backend), the first time
a normal-mapped sprite is drawn under a light, 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
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:
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.
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:
import { event } from "melonjs";
event.on(event.ONCONTEXT_RESTORED, (renderer) => {
// re-acquire anything you were holding by raw handle
});
Test on the backend your users get, not the one your harness picks
video.AUTO prefers WebGPU where it exists. Headless Chromium usually has no
GPU adapter and falls back to WebGL, so an automated suite can pass every r