- name
SKILL.md
O arquivo da skill permanece no repositório do publicador.
Cole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderer-backends -a cursor -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderer-backends -a claude-code -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderer-backends -a codex -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderer-backends -a grok -yEnvie a mensagem copiada em um chat do Grok Bot. O Bot busca este SKILL.md no GitHub e o adiciona às skills que todos os seus Bots compartilham.
Install this skill: https://github.com/melonjs/melonJS/tree/HEAD/packages/melonjs/skills/melonjs-renderer-backendsDo publicador
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.
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.
A GPU backend also counts as unavailable when the browser says it would run
far slower than native — a software rasterizer, a blocklisted driver. The
failIfMajorPerformanceCaveat setting (true by default, stricter than
WebGL's own default) refuses such a context, and the WebGPU backend refuses a
software adapter the same way: under AUTO that machine gets Canvas, and
under video.WEBGL or video.WEBGPU init() rejects. Set it false to accept
the slow context instead.
The Canvas column is the problem: none of it throws. Most of those paths warn
once and then degrade or no-op, and some (the pixelate transition, hdr) do
so without a word, 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 under a 2D camera still draws too, textured,
sorted with the painter's algorithm and no depth buffer, so convex models look
right and a self-overlapping one can draw a few triangles over the wrong ones.
That is a last resort so a game does not go blank, not a target: anything
built on meshes should run on WebGPU or WebGL 2. "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.
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. supportsHDR and
supportsHDROutput say what the hdr and hdrOutput settings were actually
granted, which can be less than was asked. 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");
}
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.
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.
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
});
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 run
while the WebGPU path is broken — the two differ in real, throwing ways (see
below). Pin the backend explicitly when it matters: renderer: video.WEBGPU,
or the #webgpu / #webgl URI fragment on a page you can open by hand.
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.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.OperationError: GPUQueue.copyExternalImageToTexture: External image state is not valid, from a stack that reads drawImage → addQuad → getBinding. WebGL
uploads the same source without complaint, so this is a class of bug that
cannot appear on one backend and stops the game dead on the other. Check
any canvas the game sizes from content that can be empty before it is drawn.
An empty or whitespace-only Text did this before 20.11; its glyph canvas
is now at least 32 pixels on each side.blend mode "…" is not supported for 3D meshes warning and falls back to
"normal". Gradient fills warn the same way.melonjs-getting-started — renderer selection in the Application settingsmelonjs-effects-and-shaders — dual-language shaders and the Canvas no-opmelonjs-3d — the tier that requires a GPU backend outrightUse 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 fallb
---name: melonjs-renderer-backendsdescription: Use this skill when a feature works on one machine and not another, when choosing or pinning a renderer, or…---# packages/melonjs/skills/melonjs-renderer-backends/SKILL.mdVisão geral
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, failIfMajorPerformanceCaveat, software rendering, supportsHDR, hdrOutput, context loss, backend, works on my machine.
Perguntas frequentes
Baixe packages/melonjs/skills/melonjs-renderer-backends/SKILL.md do publicador ou copie o caminho e abra o repositório. O PlugMCP lista a skill e não hospeda o arquivo.
O publicador o mantém em https://github.com/melonjs/melonJS.
Claude, Cursor, Codex e Grok Build conseguem ler um SKILL.md que você adiciona a partir do repositório do publicador. O Grok Bot o instala quando você envia em um chat o link da pasta da skill no GitHub.