tune-performance

/tune-performance — Profile, Diagnose, Fix

Overview

Performance tuning without measurement is gambling. This skill enforces a measure-first loop: read diagnostics, identify the dominant cost (rendering / physics / scripting / startup), drill into the specific pattern, propose one fix, verify the metric moved. No shotgun optimization.

Core principle: the engine's diagnostics tell you which subsystem is bleeding. Don't optimize a different subsystem.

Steps

1. Get the user's symptom precisely

What's slow? Pick the closest: framerate drops in scene X / startup is long / freezes for a moment / runs fine on my machine but bad on hardware Y.

Wait. The answer narrows the fix domain by 5x:

Symptom	Likely subsystem
Framerate drops as more enemies spawn	Scripting (_process per-instance) or physics
Framerate is fine standing still, drops looking at level X	Rendering (overdraw, draw calls, lights)
Stutter every N seconds	GC pause, autoload loop, or async load
Long startup	Asset import, autoload _ready work, shader compilation
Runs fine on dev machine, bad on user machine	Resolution, GPU features (compute, GI), shadow quality

2. Take a baseline measurement

Don't guess. Read the engine's actual numbers.

summer_get_diagnostics is NOT a profiler. It returns counts of console errors, debugger errors, debugger warnings and script errors — nothing else. It carries no FPS, no frame time, no draw calls, no body counts. Never quote a performance number you claim came from it.

Preferred (Summer MCP): measure inside a verification probe. RunVerification spawns a hidden, disposable game instance with a real renderer, runs your GDScript probe, and dies without touching the user's editor. Performance.get_monitor(...) inside that probe returns the real numbers.

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

extends SummerProbeBase
func _ready() -> void:
    await super._ready()
    await get_tree().process_frame
    await get_tree().create_timer(3.0).timeout    # let it settle, then sample
    report("fps", Performance.get_monitor(Performance.TIME_FPS))
    report("process_ms", Performance.get_monitor(Performance.TIME_PROCESS) * 1000.0)
    report("physics_ms", Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS) * 1000.0)
    report("draw_calls", Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME))
    report("objects", Performance.get_monitor(Performance.RENDER_TOTAL_OBJECTS_IN_FRAME))
    report("primitives", Performance.get_monitor(Performance.RENDER_TOTAL_PRIMITIVES_IN_FRAME))
    report("video_mem", Performance.get_monitor(Performance.RENDER_VIDEO_MEM_USED))
    report("bodies_3d", Performance.get_monitor(Performance.PHYSICS_3D_ACTIVE_OBJECTS))
    report("bodies_2d", Performance.get_monitor(Performance.PHYSICS_2D_ACTIVE_OBJECTS))
    report("objects_total", Performance.get_monitor(Performance.OBJECT_COUNT))
    save_frame("baseline")
    finish()