gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/performance-optimization
performance-optimization
VerifiedFinds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (`unity-build-size`), physics jitter (`physics-tuning`) or network lag (`roblox-networking`, `godot-multiplayer`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.3 KB |
| references/profiling-and-budgets.md | markdown | 7.7 KB |
references/profiling-and-budgets.md
View on GitHub# Profiling and budgets
Targets Godot 4.7, Unity 6.3 LTS and Unreal 5.8.
Contents:
1. CPU-vs-GPU triage
2. Per-engine profiler quick start (Godot, Unity, Unreal, external tools)
3. Pooling manager
4. Batching and instancing rules
5. Allocation and GC guidance
6. Do-less techniques
7. Asset budgets and mobile thermals
## 1. CPU-vs-GPU triage (decide before you fix)
```text
1. Read total frame time vs your budget (16.67 ms @60).
2. Compare CPU-frame time and GPU-frame time:
GPU >> CPU → GPU-bound → overdraw, shader cost, resolution, lights/shadows.
CPU >> GPU → CPU-bound → inspect main AND render threads: scripts, physics, pathfinding,
allocations/GC, draw submission and render-state changes.
Both high / alternating → find the per-frame spike in the timeline (one function/system).
3. Within the bound side, sort costs descending and attack the top one only.
4. Re-measure. If it didn't move the frame time, you fixed the wrong thing — revert and re-triage.
```
Optimize the measured bottleneck. Reducing draw calls or state changes can lower CPU rendering
cost when submission is limiting the frame, even if the GPU has spare capacity. Batching and
instancing also have costs, so compare main-thread, render-thread and GPU time before and after
the change. Faster scripts alone usually won't help a frame limited by GPU work.
## 2. Per-engine profiler quick start
**Godot 4.7**
- Editor: **Debugger ▸ Profiler** (per-function script + physics time, frame time), **Debugger ▸
Visual Profiler** (CPU and GPU time spent on rendering — the Profiler tab does not show GPU cost),
and the **Monitors** tab (FPS, draw calls, video/static memory, object/node counts).
- Code: `Performance.get_monitor(Performance.TIME_PROCESS)` (the slowest process frame of the
last second, in **seconds**, refreshed once a second), `Performance.TIME_PHYSICS_PROCESS`,
`Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME`, `Performance.RENDER_TOTAL_PRIMITIVES_IN_FRAME`,
`Performance.MEMORY_STATIC`, and the `PIPELINE_COMPILATIONS_*` monitors (4.4+) for shader
hitches: a jump in the Surface or Draw counts outside a loading screen is a first-play stutter.
- Visual debugging: 3D viewport **View Information / View Frame Time** overlays.
- Native-code traces: an engine built from source with `scons profiler=tracy` (or `perfetto`,
`instruments`) streams engine zones to that profiler.
**Unity 6.3 LTS**
- **Profiler** window: CPU Usage, GPU Usage, Rendering, Memory modules. Use **Deep Profile**
sparingly (high overhead, skews numbers).
- **Frame Debugger** to step draw calls and see what breaks batching (SetPass calls, batches).
- Code: `ProfilerRecorder` on the built-in counters `"CPU Main Thread Frame Time"`,
`"GPU Frame Time"` (release players need **Frame Timing Stats** enabled) and
`"GC Allocated In Frame"` (development players only) for an in-build HUD/CSV;
`FrameTimingManager` for CPU/GPU frame times.
- **Profile a Development build on device** (`Autoconnect Profiler`), not just the editor.
- **Project Auditor** (`com.unity.project-auditor` package) statically flags costly code and
settings before you profile.
**Unreal 5.8**
- Console: `stat unit` (Frame / Game / Draw / RHIT / GPU ms — Game is the game thread, Draw the
render thread, both CPU), `stat fps`, `stat scenerendering` (draw calls, primitives),
`stat game`, `stat gpu`, `stat hitches` (logs frames over `t.HitchFrameTimeThreshold`).
- **Unreal Insights** for full timeline traces; `ProfileGPU` (Ctrl+Shift+,) for a GPU breakdown.
**External tools (engine-agnostic)**
- **RenderDoc**: GPU frame capture for Vulkan, D3D11/12 and OpenGL/ES on
Windows, Linux and Android; no Metal. On Apple platforms use the Xcode Metal debugger and
Instruments; on Windows D3D12, PIX.
- **Tracy**: instrumented CPU/GPU timeline for native code; keep the
client library and the viewer on the same release, because the network protocol can change.
## 3. Pooling manager (generic)
```text
class Pool<T>:
free: list
create_fn, reset_fn
prewarm(n): for n → free.push(create_fn()) # allocate up front, off the hot path
acquire(): t = free.pop() or create_fn(); activate(t); return t
release(t): reset_fn(t); deactivate(t); free.push(t) # never destroy; recycle
```
Pool anything spawned frequently and briefly: bullets, shells, particles, damage numbers,
enemies in waves, audio one-shots. Pre-warm at load to avoid first-use hitches. Cap the pool and
decide an overflow policy (grow, or recycle the oldest).
## 4. Batching & instancing rules
- **What breaks a batch:** a different material, texture, or render state between objects. Share
materials and **atlas** textures so runs of objects submit as one draw call.
- **Identical meshes, many instances** → GPU instancing: Unity (enable *GPU Instancing* on the
material — but under URP/HDRP an SRP Batcher-compatible shader is drawn by the SRP Batcher
instead; for large counts enable the **GPU Resident Drawer**, which needs the Forward+ path and
a compute-capable graphics API other than OpenGL ES) / Godot `MultiMesh` +
`MultiMeshInstance2D/3D` / Unreal Instanced Static Mesh or Hierarchical ISM.
- **Static geometry** → static batching (Unity), mark static; bake where possible. Unity's
dynamic batching is no longer recommended outside low-end devices: its CPU cost can exceed the
draw calls it saves.
- **2D** → texture atlases + a shared material batch sprites; avoid per-sprite materials.
- **UI** → minimize canvas rebuilds (Unity: split static/dynamic canvases); a changing element
shouldn't dirty the whole canvas.
- **Lights/shadows** → bake static lighting; cap real-time shadow casters; cull small shadows.
## 5. Allocation / GC guidance
- **C# (Unity):** no per-frame `new`, no LINQ in `Update`, avoid boxing (e.g. `enum` as dictionary
key), use `NonAlloc` physics queries, reuse `List`/arrays (`Clear()` not realloc), prefer
structs for small hot data, cache `GetComponent`/`Find` results. The goal is **0 B GC.Alloc per
frame** in steady state.
- **GDScript (Godot):** don't build new `Array`/`Dictionary` each `_process`; reuse; prefer typed
arrays; avoid heavy work in `_process` that belongs on a timer/signal.
- **General:** strings are a classic hidden allocator (concatenation, formatting) — build them
rarely, cache results.
## 6. Do-less techniques (algorithmic wins)
- **Run less often:** update AI/HUD/expensive checks on a timer or every N frames, not every
frame; stagger across frames (time-slicing).
- **Spatial partition:** grid/quadtree/octree so queries touch nearby objects only, not all N.
- **LOD & culling:** lower detail at distance; frustum/occlusion culling; despawn off-screen
far entities.
- **Cache results:** memoize pathfinding, line-of-sight, and derived data; invalidate on change.
- **Defer/Amortize:** spread procedural generation and loading across frames to avoid spikes.
## 7. Asset budgets (prevent regressions at the source)
| Asset | Typical desktop budget | Mobile budget | Notes |
|-------|------------------------|---------------|-------|
| Texture max size | 2048–4096 | 1024–2048 | use mipmaps; compress (BCn / ASTC) |
| Character triangles | 30k–80k | 5k–20k | LODs for distance |
| Draw calls / frame | low thousands | a few hundred | the count that matters most on mobile |
| Real-time lights | a few | 1–2 + baked | bake the rest |
| Audio | streamed music, short SFX in memory | same | don't decompress everything at load |
Mobile adds **thermal throttling**: a game that hits 60 FPS for two minutes and then drops is
overheating. Keep headroom, cap the frame rate and reduce sustained GPU load. The agent cannot
feel a device heat up, so ask the user to play 15 minutes on the target phone and report the
frame time (or FPS counter) in the first and last minute.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |