tune-performance

Profile Godot game performance and fix rendering, physics, and scripting hotspots with measured before/after metrics.

66|4|Updated Feb 26, 2026
One-click install
npx skills add https://github.com/SummerEngine/summer --skill tune-performance-summerengine
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tune-performance
Source: https://github.com/SummerEngine/summer/tree/main/library/skills/tune-performance
Command: npx skills add https://github.com/SummerEngine/summer --skill tune-performance-summerengine

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Games that drop frames, stutter, or start slowly are hard to fix without measurement, and guessing at optimizations wastes effort on the wrong subsystem. This Skill enforces a measure-first loop: capture baseline metrics inside a real renderer, identify the dominant cost, apply one targeted fix, and verify the metric actually moved. ## Core Features & Use Cases - Baseline measurement via verification probes: Runs a disposable instrumented game instance using Performance.get_monitor to capture FPS, frame time, draw calls, physics body counts, and memory before changing anything. - Hotspot decision tree: Routes symptoms to the right subsystem — rendering (draw calls, overdraw, lights, shadows), physics (rigid bodies, concave shapes, tick rate), GDScript (_process loops, per-frame allocations), jitter (shader compile, GC), or startup (autoloads, imports). - One-fix-at-a-time verification: Proposes a single fix with an expected metric movement, applies it after user approval, then re-runs the identical probe to confirm the improvement. - Use Case: A game's framerate drops when enemies spawn. The Skill measures 14.2 ms render time from 240 individual foliage MeshInstance3D nodes, replaces them with one MultiMeshInstance3D, and re-measures to confirm render time dropped to 4.1 ms. ## Quick Start Ask the agent to profile why your game is slow and fix the biggest performance hotspot with before and after measurements.

Frequently Asked Questions about tune-performance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I profile a slow Godot game to find the bottleneck?

Run a verification probe that samples Performance.get_monitor metrics like FPS, frame time, draw calls, and active physics bodies after letting the game settle for a few seconds. Compare the numbers against a decision tree to identify whether rendering, physics, or scripting dominates the frame budget.

How to fix low FPS caused by too many draw calls in Godot?

Replace repeated MeshInstance3D nodes with a single MultiMeshInstance3D, which renders thousands of copies in one draw call. Also check for overdraw from stacked transparent materials and reduce real-time light counts by baking static lighting with LightmapGI.

Why does my Godot game stutter even though average FPS is fine?

Frame time spikes usually come from shader compilation, garbage collection from per-frame allocations, or unfinished async resource loads. Precompile shaders during loading, pre-allocate arrays outside _process, and ensure ResourceLoader.load_threaded_request completes before use.

Can I profile Godot performance in headless mode?

No. A headless instance has no renderer, so draw call and object count monitors read zero and the FPS figure is a meaningless uncapped loop rate. Use a windowed-offscreen verification instance so the rendering metrics reflect real GPU work.

What are the most common GDScript performance mistakes?

The top issues are calling get_nodes_in_group every frame instead of caching in _ready, running AI logic at 60 Hz instead of a 10 Hz timer, and using distance_to instead of distance_squared_to in hot loops. Per-frame work in _process is the number one GDScript cost.

When should I use convex instead of concave collision shapes?

Always use convex or compound primitive shapes (sphere, capsule, box) on dynamic rigid bodies, since concave collision costs 5 to 20 times more in the physics solver. Reserve concave shapes for static level geometry only.