Compatibility Renderer Traps

Forward+ and Compatibility without surprises

Games built on Forward+ can end up on the Compatibility renderer (OpenGL): phones where Metal/Vulkan is unavailable, weak GPUs, or a project that picks it for battery. The failures are silent: no error, just black fruit, pale colors, or objects that stop animating after the first few hundred. Each trap below comes with its fix and the reason.

1. Know which renderer you actually got

• Phones use rendering/renderer/rendering_method.mobile, which defaults to mobile, not Forward+. Set it explicitly.
• A device can fall back to another renderer when it lacks a capability. Trust the renderer name printed at startup (or RenderingServer.get_current_rendering_method()), not the project setting.
• Preview Compatibility on your computer: <summer> --path . --rendering-method gl_compatibility.

2. The traps

Everything the player must see (ripe crop, enemy, pickup) must stay readable without glow, SSR, volumetric fog or other Forward+-only effects: use shape, color and icons too.

The helper (standard sRGB curve):

glslCopy code
vec3 to_linear(vec3 c) {
	return mix(pow((c + vec3(0.055)) * (1.0 / 1.055), vec3(2.4)), c * (1.0 / 12.92), lessThan(c, vec3(0.04045)));
}

3. Keep one shader path

Write shaders in plain spatial math: vertex-color ramps, simple rim terms, no custom light() unless you test it on both renderers. One path for both renderers means one set of bugs and no drift.

4. Verify, don't assume

1. Render the same scene on Forward+ and gl_compatibility offscreen: <summer> --audio-driver Dummy --summer-offscreen --path . --resolution 1600x900 -s res://tools/capture.gd -- --out=<dir> (add --rendering-method gl_compatibility for the second run).
2. Read both images side by side, and include a stress shot with many instances (the 256 limit only shows at scale).
3. Grep the log for SCRIPT ERROR, SHADER ERROR and ERROR:. A shader that fails to compile still lets the capture exit 0 and draws the object untextured, so a missing grep hides the failure.
4. If later captures repeat the same frame, the offscreen run froze (it happens when another engine renders at the same time). Check with md5 -r *.png and rerun alone.

Common mistakes

• Checking only the project setting and calling it "Forward+ on phones".
• Using instance uniform for per-plant or per-tile state.
• Reading COLOR from a MultiMesh without instance colors.
• Testing Compatibility with ten objects when the game shows five hundred.
• Budgeting one run per fix: every look change needs two captures (one per renderer). Plan runs in pairs.

See also

• web-compatibility-look (a finished look when the game only runs on Compatibility, as on the web)
• 3d-lighting (lighting profiles)
• bounded-engine-runs (safe offscreen capture runs)

From a shell

No Summer MCP tools in this session? Run each one as a command; when summer --version is missing or below 4.0, use npx -y summer-engine@latest in place of summer. Fields are flags in kebab-case (--scene-path res://main.tscn) or one --input '<json>', and summer ops describe <op> prints the exact input. The summer-cli skill has the rest.