diagnosing-perf-regressions

Diagnosing Performance Regressions

Overview

There is a difference between "this game is slow" and "this game got slow." This skill is for the second one.

Core principle: A regression has a cause. The cause is a specific change. Bisect to find the change, then root-cause from there.

This skill is not general performance tuning. If the game has always run at 30fps and you want to push it to 60, that is summer:tune-performance (the domain skill for budget-driven optimization). This skill is the diagnostic — what broke, where, when.

When To Use

• "It used to run at 60fps, now it's at 30."
• "Load time was 3s yesterday, now it's 15s."
• "Frame stutters started after I added X."
• "Build went from buttery to choppy and I don't know why."

When NOT To Use

• "The game has always been slow, help me speed it up." → summer:tune-performance.
• "I want to know if my game is fast enough to ship." → summer:tune-performance.
• "The game crashes." → summer:debug.

The Iron Law

NO PERF FIX WITHOUT A KNOWN-GOOD vs KNOWN-BAD MEASUREMENT

You cannot fix a regression you have not measured. Eyeballing "feels laggy" is not a measurement. Get a number for the good state and a number for the bad state before touching code.

The Loop

  Measure now → Find last good → Bisect changes → Match to a cliff → A/B fix → Re-measure

1. Measure now

Measure in a RunVerification probe, not by eye. It spawns a hidden, disposable game instance with a real renderer, so Performance.get_monitor(...) returns the game's actual numbers and the user's editor session is untouched.

summer_batch ops:[{"op":"RunVerification","probe_source":"<probe>","max_seconds":20}]

extends SummerProbeBase
func _ready() -> void:
    await super._ready()
    await get_tree().process_frame
    var samples: Array = []
    for i in 30:                                  # ~5 s at 60 fps, sampled over time
        await get_tree().create_timer(0.16).timeout
        samples.append(Performance.get_monitor(Performance.TIME_FPS))
    report("fps_samples", samples)                # spike pattern lives here
    report("draw_calls", Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME))
    report("bodies_3d", Performance.get_monitor(Performance.PHYSICS_3D_ACTIVE_OBJECTS))
    report("objects", Performance.get_monitor(Performance.RENDER_TOTAL_OBJECTS_IN_FRAME))
    dump_tree()
    finish()