Skip to main content
compatibility-renderer-traps is a skill from the Summer skill library: a guide your AI agent reads when the task matches, so it builds the good version on the first try. Make a Forward+ game look right on the Compatibility renderer: instance uniforms, MultiMesh, vertex colors.

​
When your agent uses it

  • A game must run on phones or weak GPUs that may use the Compatibility or Mobile renderer
  • Objects render black, pale or stop animating on one renderer but not another
  • Writing shaders for many instances (crops, foliage, tiles) that must work everywhere

​
Install

summer setup installs every skill for your agent. To add only this one:
Swap claude-code for your agent, such as codex or cursor. See Skills for every option.

​
The skill

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):

​
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.
  • web-compatibility-look: Make a browser game look high-end in the Compatibility renderer (WebGL 2): what works, recipes, speed.
  • 3d-lighting: Light a 3D scene: sun, omni and spot lights, WorldEnvironment, sky, shadows and ambient.
  • bounded-engine-runs: Run Summer headless or offscreen safely: time limits, one engine per project, import passes, crash checks.
Source: library/skills/compatibility-renderer-traps/SKILL.md, rendered from summer-engine@4.3.0 on npm.