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.

Preferred (onyx MCP):

onyx_clear_console
onyx_play
# user reproduces the slowdown for 5–10 seconds
onyx_get_diagnostics
onyx_get_console               # check for warnings (e.g. "shader compilation hot-path")
onyx_stop

onyx_get_diagnostics returns the aggregate metrics. Note (write down before fixing anything):

• Average FPS during the slow section
• Frame time (ms) — anything over 16.67 ms = below 60 fps
• Draw calls per frame
• Active physics bodies
• Active GPUParticles instances
• Script time vs. physics time vs. render time

Fallback (no MCP): ask the user to enable Godot's built-in monitor (Debug → Monitor or in-game with Performance.get_monitor) and paste numbers. At minimum: FPS, frame time, draw calls, physics active objects.