Unity Performance skill for Codex

Done well means: every change is justified by a capture from a development build on the target device, the frame budget is stated in milliseconds, the bottleneck (CPU main thread, render thread, GPU, memory) is named before anything is changed, and the after-capture proves the gain.

Budgets

Target	Frame budget	Practical headroom
30 FPS mobile	33.3 ms	Aim for ~22 ms to avoid thermal throttling
60 FPS	16.6 ms	~13 ms
90 FPS VR	11.1 ms	~9 ms, hard requirement
120 FPS	8.3 ms	~7 ms

Steady-state GC allocation per frame should be 0 B in gameplay. Mobile phones throttle under sustained load, so a 10-minute soak test matters more than a 10-second peak.

Workflow

- [ ] 1. Read AGENTS.md, ProjectVersion.txt, render pipeline asset (URP/HDRP/Built-in)
- [ ] 2. Build a Development Build with Autoconnect Profiler on the target device
- [ ] 3. Capture 300+ frames of the bad case; note the frame-time spike pattern
- [ ] 4. Classify: CPU main, CPU render thread, GPU, or GC/memory (table below)
- [ ] 5. Drill into the top 3 markers only; form one hypothesis per change
- [ ] 6. Make one change, recapture under the same conditions, compare
- [ ] 7. Record before/after numbers in the hand-off

Editor profiling lies: the editor adds its own overhead, runs with domain checks, and uses desktop GPUs. Use it for allocation hunting and hierarchy shape, never for final numbers.

Classify the bottleneck

Profiler shows	Bound by	First tools
PlayerLoop large, scripts dominate	CPU main thread (scripts)	Profiler Hierarchy, Deep Profile on a small repro only
Gfx.WaitForPresentOnGfxThread large on main thread	GPU or render thread	GPU profiler module, Frame Debugger, platform GPU tools
Physics.Simulate / FixedUpdate.PhysicsFixedUpdate large	Physics	Physics Debugger, collider counts, fixed timestep
GC.Collect spikes, GC Alloc column nonzero	Managed allocations	Hierarchy sorted by GC Alloc, Memory Profiler
Canvas.BuildBatch, Canvas.SendWillRenderCanvases	uGUI rebuilds	Split canvases
Loading.ReadObject, Instantiate spikes	Asset loading / spawning	Pooling, async loading, Addressables

Check the frame interval too: if WaitForTargetFPS is large, the game is already fast and capped by Application.targetFrameRate or VSync.

Measure your own code

using Unity.Profiling;

public sealed class EnemyDirector : MonoBehaviour
{
    static readonly ProfilerMarker s_Think = new("EnemyDirector.Think");

    void Update()
    {
        using (s_Think.Auto())
        {
            ThinkAll();
        }
    }
}

Markers show up in the Profiler and in builds with the Profiler attached. For on-device overlays use ProfilerRecorder.StartNew(ProfilerCategory.Render, "Draw Calls Count") or "Main Thread" and read LastValue.

CPU: scripts and GC

• Replace per-object Update on hundreds of objects with one manager that iterates an array. Each Update call crosses from native to managed code.
• Allocation sources to eliminate in hot paths: new List<T>() per frame, LINQ, string concatenation and ToString() for UI, boxing via object parameters or enum keys in Dictionary without a comparer, closures captured in lambdas, GetComponents<T>() without a list argument, foreach over non-struct enumerators, params arrays.
• Physics queries: use the non-allocating overloads (Physics.RaycastNonAlloc, Physics.OverlapSphereNonAlloc) with a preallocated buffer, and filter with a LayerMask.
• Pool anything spawned more than a few times a second:

using UnityEngine.Pool;

ObjectPool<Projectile> pool;

void Awake() => pool = new ObjectPool<Projectile>(
    createFunc: () => Instantiate(prefab),
    actionOnGet: p => p.gameObject.SetActive(true),
    actionOnRelease: p => p.gameObject.SetActive(false),
    actionOnDestroy: p => Destroy(p.gameObject),
    collectionCheck: false, defaultCapacity: 64, maxSize: 256);

• Incremental GC (Player Settings, on by default) spreads collections over frames; it does not remove the cost. Fix allocations first.
• Heavy data loops (thousands of agents, pathfinding batches) are candidates for the Job System plus Burst. Move only after profiling shows the loop dominates.

Rendering: draw calls and GPU

Situation	Approach
URP/HDRP, many objects sharing shaders	SRP Batcher (on by default); keep shaders compatible (Frame Debugger shows why a batch broke)
Unity 6 URP/HDRP with many static/repeated meshes	GPU Resident Drawer (requires Forward+ in URP)
Thousands of identical meshes	GPU instancing or Graphics.RenderMeshInstanced
Many small static props	Static batching (memory cost) or merging meshes offline
Overdraw from particles and transparent UI	Reduce layered transparency; check with Scene view Overdraw mode
Mobile GPU bound	Lower render scale in the URP asset, cut post effects, fewer real-time lights and shadow cascades

• MaterialPropertyBlock breaks SRP Batcher compatibility; in SRP projects prefer separate materials or per-instance data through instancing.
• Accessing renderer.material creates a material copy per object; use sharedMaterial when you mean the asset, and destroy copies you create.
• Use LOD Groups and occlusion culling for 3D scenes with depth; verify with the Frame Debugger that culled objects are not drawn.

Memory and assets (mobile especially)

• Textures: ASTC on iOS/Android, max size set per platform, mipmaps off for UI, Read/Write off unless code reads pixels (it doubles memory).
• Meshes: Read/Write off; enable mesh compression where artefacts are acceptable.
• Audio: long music as Streaming, short SFX as Decompress On Load, everything else Compressed In Memory.
• Take two Memory Profiler snapshots (menu, after one level) and diff them to find leaks: assets still referenced by static fields or event subscriptions.
• Resources.UnloadUnusedAssets() is slow and frees only unreferenced assets; it does not fix a leak.

UI (uGUI)

• Any change to a Graphic marks its whole Canvas dirty. Put frequently changing elements (timers, health bars) on their own nested Canvas.
• Disable Raycast Target on images and text that are not interactive.
• Hiding with CanvasGroup.alpha = 0 still costs; disable the Canvas component instead of the GameObject to avoid a rebuild on re-enable.

Physics

• Keep Fixed Timestep as large as feel allows (0.02 s default). Halving it doubles cost.
• Set Maximum Allowed Timestep to bound catch-up work after a hitch.
• Use the Layer Collision Matrix to remove pairs that never interact.
• Prefer primitive colliders; avoid non-convex MeshCollider on moving bodies.

Gotchas

• Deep Profile multiplies overhead and distorts the picture; use it only on a tiny repro.
• Debug.Log in builds allocates and writes to disk; strip with a conditional wrapper ([System.Diagnostics.Conditional("ENABLE_LOGS")]).
• VSync and targetFrameRate interact: on mobile targetFrameRate defaults to 30. Set it explicitly and check QualitySettings.vSyncCount.
• Shader variant compilation hitches the first time an effect appears. Warm up with a ShaderVariantCollection (or the Unity 6 PSO tracing tools) in the loading screen.
• A fix that wins 2 ms in the editor can be noise on device. Compare medians across 300 frames, not single frames.

Verification

• Same scene, same device, same camera path, same build type, before and after.
• Report median and 95th percentile frame time, GC Alloc per frame, draw calls / SetPass calls, and memory after the soak test.
• If the change did not move the target metric by more than run-to-run noise, revert it.

Hand-off template

**Device:** Pixel 7, development build, URP, 60 FPS target (16.6 ms)
**Bottleneck:** CPU main thread, EnemyDirector.Think 6.1 ms + GC.Collect spikes every ~2 s
**Changes:** pooled projectiles (ObjectPool, max 256); RaycastNonAlloc in targeting; HUD timer on own Canvas
**Result:** median 19.4 -> 12.8 ms, p95 31 -> 15.2 ms, GC Alloc 14.2 KB -> 0 B per frame
**Not addressed:** shader warm-up hitch on first explosion (needs ShaderVariantCollection)