跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
视频与音频

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

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

WebGPUWebGL 2Canvas
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

阅读完整来源 ↗