diagnosing-perf-regressions

Measure the current FPS with a probe, identify the last known-good commit in git history, then bisect the commits between them while re-measuring. Match the symptom to common causes like physics body count, shader compilation, draw calls, or transparent overdraw.

Run git log between the last good commit and HEAD, group commits into suspects such as asset imports, new shaders, or scene additions, then check out midpoints and measure FPS at each step. Revert one suspect at a time and re-measure to confirm the cause.

Use regression diagnosis when the game previously ran well and got worse after changes, since a specific commit caused it. Use general performance tuning when the game has always been slow and there is no known-good baseline to compare against.

First-use stutters that disappear afterward typically indicate shader compilation stalls, common when a new shader or unique material is not pre-warmed. This pattern appears in shipped builds but often not in the editor.

No. The editor runs @tool scripts, debug overlays, and a different render pipeline, so its FPS is misleading. Measure in a RunVerification probe or a built binary, and never profile with --headless since draw calls read zero without a renderer.

Start the engine with the summer run command to restore the probe route. Alternatively, invoke the Summer binary directly with the --summer-verify flags to run a probe without the editor, then read the results from the output JSON file.