unity-performance — Claude Code skill: Unity profiling and batching
unity-performance — a skill for tracking down Unity stutter and low FPS: what to open in the Profiler, how to cut draw calls, where garbage collection causes spikes.
MIT 103 installs ★ 66 updated 2026-06-18
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a claude-codeWhat unity-performance does
The skill walks the profiling loop: build with Autoconnect Profiler on, capture on the target device, decide whether the frame is CPU-bound, GPU-bound or memory-bound, then dig into that one system. Editor numbers are misleading because the Editor eats frame time itself, so profile on the hardware you ship to.
Anti-pattern tables for Update come next: string concatenation, a fresh List<T> every frame, LINQ in hot paths, GetComponent<T>() without a cache. There's a ready ObjectPool<T> on a Queue<T> with prewarm, meant for bullets, particles, enemies and UI items. Rendering has its own section: static and dynamic batching, GPU instancing, the SRP Batcher, texture atlases, LOD groups and baked occlusion culling.
Memory is grouped by symptom: bloated textures, scenes that keep references alive, Addressables handles never released, meshes with Read/Write left on. A compression matrix maps formats to targets: BC7 for PC and console, ASTC 6x6 for Android and iOS, ETC2 or DXT for WebGL. Max texture size, the skill advises, should be the smallest that works: 512 for UI icons, 1024 for props, 2048 for large assets.
What it helps with
- Work out whether the frame is CPU-bound or GPU-bound
- Remove per-frame allocations that trigger GC spikes
- Cut draw calls with batching and texture atlases
- Hunt a memory leak with Memory Profiler snapshots
- Pick the right texture compression for each target
Example prompts for the agent
- The game stutters on Android — capture a frame in the Unity Profiler and tell me if it's CPU or GPU
- Rewrite the bullet spawner with an object pool so it stops allocating every frame
- Check my texture import settings and suggest compression for iOS
How to install unity-performance
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a claude-code2Manually: put the files in place
~/.claude/skills/unity-performance/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/unity-performance/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a codex2Manually: put the files in place
.agents/skills/unity-performance/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a cursor2Manually: put the files in place
.cursor/skills/unity-performance/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install JosiahSiegel/claude-plugin-marketplace plugins/unity-master/skills/unity-performance2Manually: put the files in place
.github/skills/unity-performance/SKILL.md1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a gemini-cli2Platform CLI
gemini skills install https://github.com/JosiahSiegel/claude-plugin-marketplace --path plugins/unity-master/skills/unity-performanceManually: put the files in place
.devin/skills/unity-performance/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about unity-performance
How do I install unity-performance in Claude Code?
Run npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a claude-code. The skill ends up in ~/.claude/skills/unity-performance/SKILL.md.
What does unity-performance do?
It helps sort out low FPS and stutter in Unity: which profiling tools to open, how to bring draw calls down, where frame allocations come from, and how to trim memory and build size.
Which other editors can install it?
Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode are covered too, each with its own install command and skill path.
Source text
SKILL.md · MIT
---
name: unity-performance
description: |
Unity performance optimization for slow games, stutters, and FPS drops.
PROACTIVELY activate for: (1) game is slow, stuttering, or has FPS drops, (2) Unity Profiler analysis, (3) Frame Debugger and draw-call investigation, (4) batching (static, dynamic, GPU instancing, SRP Batcher), (5) object pooling to reduce GC pressure, (6) garbage collection spikes and allocation hot paths, (7) memory leaks and Memory Profiler usage, (8) LOD and occlusion culling, (9) texture compression and mipmap settings, (10) build size reduction.
Provides: profiling workflow, batching patterns, object-pool implementations, GC reduction techniques, LOD/culling setup, and texture-compression matrix.
---
# Unity Performance Optimization
## Overview
Systematic approach to profiling and optimizing Unity games. Covers profiling tools, CPU/GPU optimization, memory management, rendering optimization, and platform-specific considerations.
## Profiling Tools
| Tool | What It Shows | When to Use |
|------|--------------|-------------|
| **Unity Profiler** | CPU, GPU, memory, audio, physics per frame | First stop for any perf issue |
| **Frame Debugger** | Draw call breakdown, shader/material state | Rendering bottlenecks |
| **Memory Profiler** | Heap snapshots, texture/mesh memory | Memory leaks, bloat |
| **Profile Analyzer** | Compare captures, statistical analysis | Before/after optimization |
| **Physics Debugger** | Collider visualization, contact points | Physics performance |
### Profiler Workflow
1. Build with Development Build + Autoconnect Profiler enabled
2. Profile on target device (not in Editor -- Editor overhead distorts results)
3. Identify the bottleneck category: CPU-bound, GPU-bound, or memory pressure
4. Drill into the specific system causing the issue
5. Optimize, re-profile, and compare
### Reading the Profiler
```text
If frame time > 16.6ms (60 FPS target):
CPU timeline > GPU timeline -> CPU-bound
GPU timeline > CPU timeline -> GPU-bound
GC.Alloc column shows per-frame allocations -> GC pressure
```
Look for spikes (single bad frames) vs. sustained high times (baseline too heavy).
## CPU Optimization
### Reduce Per-Frame Allocations (GC)
| Anti-Pattern | Fix |
|-------------|-----|
| `string + string` in Update | Use `StringBuilder` or cache |
| `new List<T>()` every frame | Allocate once, `Clear()` and reuse |
| LINQ in hot paths | Replace with manual loops |
| `GetComponent<T>()` per frame | Cache in Awake/Start |
| `GameObject.Find()` per frame | Cache reference or use events |
| `foreach` on non-generic collections | Use `for` loop or generic collections |
| `SendMessage()` / `BroadcastMessage()` | Use direct calls, events, or interfaces |
| Boxing value types | Use generic collections, avoid `object` casts |
### Object Pooling
```csharp
public class ObjectPool<T> where T : Component
{
readonly Queue<T> _pool = new();
readonly T _prefab;
readonly Transform _parent;
public ObjectPool(T prefab, int preWarm, Transform parent = null)
{
_prefab = prefab;
_parent = parent;
for (int i = 0; i < preWarm; i++)
_pool.Enqueue(CreateInstance());
}
public T Get(Vector3 position, Quaternion rotation)
{
var obj = _pool.Count > 0 ? _pool.Dequeue() : CreateInstance();
obj.transform.SetPositionAndRotation(position, rotation);
obj.gameObject.SetActive(true);
return obj;
}
public void Return(T obj)
{
obj.gameObject.SetActive(false);
_pool.Enqueue(obj);
}
T CreateInstance()
{
var obj = Object.Instantiate(_prefab, _parent);
obj.gameObject.SetActive(false);
return obj;
}
}
```
Pool bullets, particles, enemies, UI elements -- anything instantiated/destroyed frequently. Unity 2021+ also has `UnityEngine.Pool.ObjectPool<T>` built-in.
### Update Optimization
| Technique | Description |
|-----------|-------------|
| Stagger updates | Don't update all AI every frame; use tick groups |
| Distance-based LOD | Reduce update frequency for distant objects |
| Event-driven | Replace polling with events where possible |
| Disable unused scripts | `enabled = false` on off-screen components |
| Use `InvokeRepeating` | For periodic checks (cheaper than coroutine yielding) |
## GPU / Rendering Optimization
### Draw Call Reduction
| Technique | How | Savings |
|-----------|-----|---------|
| **Static Batching** | Mark non-moving objects as Static | Combines meshes at build time |
| **Dynamic Batching** | Automatic for small meshes (<300 verts) | URP/Built-in only |
| **GPU Instancing** | Enable on materials for repeated objects | Trees, grass, rocks |
| **SRP Batcher** | Enabled by default in URP/HDRP | Reduces SetPass calls |
| **Texture Atlasing** | Combine textures into atlas | Fewer material switches |
| **Mesh Combining** | `CombineMeshes()` at runtime | Custom batching |
### LOD (Level of Detail)
```text
LOD Group Setup:
LOD 0 (0-30%): Full-detail mesh (5000 tris)
LOD 1 (30-60%): Medium mesh (2000 tris)
LOD 2 (60-90%): Low mesh (500 tris)
Culled (90%+): Not rendered
```
Use LOD for meshes, but also reduce script complexity, particle counts, and physics at distance.
### Occlusion Culling
Bake occlusion data for indoor/complex scenes. Mark large static occluders (walls, floors). Configure cell size based on scene scale. Use the Occlusion Culling window to visualize and test.
### Shader Optimization
| Issue | Solution |
|-------|----------|
| Complex fragment shaders | Reduce texture samples, simplify math |
| Overdraw | Minimize transparent objects, use opaque when possible |
| Too many variants | Strip unused shader variants in build settings |
| Expensive post-processing | Disable effects on mobile, use cheaper alternatives |
## Memory Management
### Common Memory Issues
| Issue | Symptom | Fix |
|-------|---------|-----|
| Texture bloat | High memory, long loads | Compress textures, reduce max size per platform |
| Unloaded scenes holding refs | Memory climbs over time | Use `Resources.UnloadUnusedAssets()` after scene transitions |
| Addressables not released | Bundles stay in memory | Call `Addressables.Release(handle)` |
| Audio clips uncompressed | Huge memory footprint | Use compressed in memory for music, decompress on load for SFX |
| Mesh read/write enabled | Double memory per mesh | Disable Read/Write if not needed at runtime |
### Texture Compression Per Platform
| Platform | Format | Notes |
|----------|--------|-------|
| PC/Console | BC7 (DXT) | Best quality/size ratio |
| Android | ASTC 6x6 | Universal, scalable quality |
| iOS | ASTC 6x6 | Same as Android |
| WebGL | ETC2 / DXT | Depends on target GPU |
Use "Override for [Platform]" in texture import settings. Set max texture size to the minimum needed (512 for UI icons, 1024 for props, 2048 for hero assets).
## Platform-Specific Considerations
| Platform | Key Constraints |
|----------|----------------|
| **Mobile** | Thermal throttling, limited memory, battery drain, fill-rate limited |
| **WebGL** | No threads (pre-Unity 6), large download size, no compute shaders |
| **Console** | Certification requirements, fixed hardware, memory budgets |
| **VR/XR** | 72-90 FPS minimum, stereo rendering cost, motion sickness from drops |
## Addressables and Asset Loading
Use Addressables for async asset loading to avoid load-time hitches:
```csharp
// Preload during loading screen
var handle = Addressables.LoadAssetAsync<GameObject>("enemy_boss");
await handle;
// Release when done
Addressables.Release(handle);
```
Use Addressable groups to control bundle granularity. Mark infrequently used assets as remote/on-demand. Profile bundle memory with the Addressables Event Viewer.
## Quick Optimization Checklist
- [ ] Profile on target device, not in Editor
- [ ] Zero per-frame GC allocations in gameplay code
- [ ] Object pooling for all frequently spawned objects
- [ ] Static batching enabled for non-moving objects
- [ ] LOD groups on all 3D models visible at varying distances
- [ ] Textures compressed per platform with appropriate max sizes
- [ ] Disable Read/Write on meshes and textures not modified at runtime
- [ ] Audio clips use appropriate compression settings
- [ ] Occlusion culling baked for indoor/complex scenes
- [ ] Shader variants stripped in build settings
## Additional Resources
### Reference Files
- **`references/profiling-deep-dive.md`** -- Advanced Profiler usage, memory profiler snapshots, frame-by-frame analysis, custom profiler markers, automated performance testing, build size analysis, ECS/DOTS performance patterns
© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace