Graphics Performance Tuning

Common Fixes

• High frame p95: reduce post preset, shadow count, live particles, or terrain chunk density.
• Too many draw calls: use repeated static props that can instance, reduce material variants, and avoid transparent/faded objects in large repeated sets.
• Texture pressure: ensure KTX2 variants exist, lower max texture size, and reuse materials.
• Particle pressure: use additive mode when sorting is not needed, lower per-emitter cap, and atlas textures.
• Terrain pressure: increase chunk size, reduce segments per chunk, and tune LOD distances.
• Water pressure: keep reflective water surfaces few and use cheap reflection (probe/environment map) for background water. True planar reflections are an unsupported-typed provider today, so reflective water resolves through the SSR/probe/environment fallback rather than a dedicated planar pass.
• Decal pressure: atlas decals and keep projection boxes tight.

Quality Clamps

Quality clamps are not hidden. The profiler reports clamp reasons such as software renderer, fallback adapter, low texture limit, post-processing unsupported, advanced PBR unsupported, compressed textures unsupported, or adaptive DPR/shadow/post/feature clamps.

Use Locked mode when you need exact visual inspection and are willing to accept lower frame rate. Use Adaptive for normal deployments where quality may step down under sustained load. Use Always-Optimistic for high-end targets where the runtime should recover toward the authored tier after temporary load clears.

The performance overlay shows live FPS, p95 frame time, backend, current tier, adaptive state, draw calls, culling counts, upload counters, and warmup state. It is the first place to confirm whether a visual difference is authored, device-clamped, or adaptive.

Publish Gates

Production publish can block renderable assets that are missing render-cost metadata, runtime variants, required LODs, or compressed texture variants above the resolution threshold. Preview and dev warn instead of blocking. Admin overrides require a reason.

Browser QA

Renderer QA baselines live in docs/render-qa/baselines. The runner executes visual and performance scenarios through /render-qa on both backends where available. Use the renderer moat demo only as a stress reference; tune normal gameplay scenes against their own profiler samples.

Apex Addendum

For larger scenes, use docs/creator/graphics/apex-renderer-performance.md.

Key rules:

• Empty and simple scenes should report trivial or standard; if they report heavy, check the profiler reason.
• Budget warnings protect collaborators. A rejected entity/light/prefab mutation is a project safety cap, not a local rendering bug.
• Use streaming radius, LODs, compressed textures, and imposters before increasing global quality.
• Many authored lights are acceptable only when the visible/overlapping set stays bounded. WebGPU uses clustered Forward+; WebGL uses a sorted/capped fallback.
• Distant crowd imposters are not full skinned actors. Use them intentionally for crowd scale.