Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill unity-performance -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/unity-performance/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/unity-performance/

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

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set96

The whole set →
unity-ui-development unity-ui-development guides Unity interface creation across UGUI and UI Toolkit. Provides recipes for UXML structure, USS styling, RectTransform anchors, and runtime data binding. CX Codex +1 107installs viral-video-platform-algorithms The viral-video-platform-algorithms Claude Code skill explains TikTok, YouTube, Instagram, and Facebook algorithms. It activates for platform strategy, video reach, hashtags, and posting schedules. CX Codex +1 106installs azure-ml-foundry-workspace azure-ml-foundry-workspace guides Azure Machine Learning and Azure AI Foundry setup, from workspace networking to compute and model endpoints. Use it to plan configuration or investigate deployment logs. CX Codex +1 105installs ffmpeg-animation-timing-reference The ffmpeg-animation-timing-reference Claude Code skill explains timing units in FFmpeg and ASS/SSA subtitles. It helps select animation, transition, and caption durations and check audio-video sync. CX Codex +1 104installs unity-networking The unity-networking Claude Code skill supports multiplayer networking work in Unity. It activates for framework setup, RPCs, synchronized state, lobbies, and server-authoritative designs. CX Codex +1 103installs unity-editor-tooling The unity-editor-tooling Claude Code skill covers Unity Editor extensions and build automation. It activates for custom inspectors, editor windows, importers, and Unity CI/CD tasks. CX Codex +1 102installs dax-mastery The dax-mastery Claude Code skill assists with DAX in Power BI semantic models. It activates for measures, calculated columns, evaluation contexts, time intelligence, and formula tuning. CX Codex +1 101installs python-opencv The python-opencv Claude Code skill supports Python computer-vision work with OpenCV. It activates for image and video processing, color conversion, and contour detection. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open