К основному содержанию
скилл CX Codex

scenario-unity-performance — скилл для Claude Code: FPS

Скилл scenario-unity-performance разбирает просадки FPS, фризы и перегрузку CPU или GPU в Unity 6.3. Он помогает измерить причину и проверить исправление на игроке.

MIT 600 установок ★ 3 964 обновлён 2026-10-23

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add scenario-labs/skills --skill scenario-unity-performance -a claude-code
Открыть на GitHub

Что делает scenario-unity-performance

Скилл ведёт диагностику производительности Unity 6.3 от базовой метрики до проверки фикса. Он помогает определить ограничивающий поток, сравнить время кадров, найти GC-сборки, компиляцию шейдеров, физические пики и проблемы с памятью. Для рендера учитываются draw calls, SetPass, SRP Batcher, GPU Resident Drawer, LOD и динамическое разрешение.

В рабочем процессе используются ut_perf.profile, PerfRendering.Audit, build_player, run_player, capture_player, analyze_capture, metal_trace и проверки аллокаций. Результат подтверждается цифрами из development player, а не только в Editor. Для работы нужен scenario-unity-expert, поэтому без него рабочий процесс будет неполным. Целевой набор в описании: Unity 6000.3.21f1, URP 17.3 и macOS Apple Silicon.

Какие задачи решает

  • найти CPU- или GPU-ограничение по профилю
  • разобрать пики GC, компиляцию шейдеров и фризы
  • проверить draw calls, SetPass и покрытие GPU Resident Drawer
  • сравнить производительность Editor и development player
  • оценить память, VRAM и размер IL2CPP-сборки

Примеры запросов агенту

  • Проверь, почему в Unity 6.3 падает FPS, и назови ограничивающий поток по числам из профиля.
  • Сними базовый профиль для сцены, найди пики GC и сравни результат после исправления в development player.
  • Проверь draw calls, SetPass и покрытие GPU Resident Drawer для URP-проекта.

Как установить scenario-unity-performance

1Через Skills CLI (Vercel)

npx skills add scenario-labs/skills --skill scenario-unity-performance -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/scenario-unity-performance/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о scenario-unity-performance

Как установить scenario-unity-performance в Claude Code?

Выполните npx skills add scenario-labs/skills --skill scenario-unity-performance -a claude-code, затем проверьте файл ~/.claude/skills/scenario-unity-performance/SKILL.md.

Что делает scenario-unity-performance?

Скилл помогает измерять производительность Unity, классифицировать CPU- и GPU-ограничения, находить причины фризов и подтверждать исправления числами из player.

Что нужно для работы scenario-unity-performance?

Нужен скилл scenario-unity-expert. В описании также задан целевой набор Unity 6000.3.21f1, URP 17.3 и macOS Apple Silicon.

Исходный текст

SKILL.md · MIT
---
name: scenario-unity-performance
description: "Use when a Unity 6.3 game is slow or stutters: low fps, frame spikes, hitches when entering areas or on first effects, GC spikes, too many draw calls or SetPass calls, CPU vs GPU bound questions, Profiler, Profile Analyzer, Memory Profiler, Frame Debugger or Project Auditor work, GPU Resident Drawer or SRP Batcher setup, LOD and Mesh LOD, shader warm-up and variants, memory or VRAM budgets, IL2CPP and build size, or proving a fix with numbers from a player."
license: MIT
---

# Unity performance (performance engineer)

Expert performance work is a measurement discipline: a budget in milliseconds, the bounding thread
named before any change, the biggest measured cost fixed first, structure before tuning, and every
fix proven with before/after numbers from a development player. An agent does all of it headless:
`AgentProfile` in Editor Play mode to iterate, `PerfProbe` in a batch-mode player for verdicts,
`PerfCapture` to attribute costs from a Profiler capture, `metal_trace` for GPU time, `PerfBuild`
for size. Target: Unity 6000.3.21f1, URP 17.3, macOS Apple Silicon. If a sibling skill named here is
missing from your available skills, load it with `skill_get` (Scenario MCP) or ask the user to
install it (https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas
and flag the gap.

**REQUIRED BACKGROUND:** scenario-unity-expert (channels, review loop, 6.3 traps, `ut_*` toolkit).

## Stance (the expert delta)

1. **Name the bound before touching anything.** "If you speed up the GPU when your profile looks
   like this it's not going to run any faster" (Peter Hall, Unity Profiler team, _cV1B2hqXGI
   [00:05:50]). Observed: removing 1.36 MB of garbage per frame did not move a frame bound by 5,946
   SetPass calls. GPU bound needs GPU timing; the Frame Debugger has none (Hall [frame 00:09:18]).
2. **Players decide, the Editor iterates.** The authority is a development build on the lowest
   target device (profiling e-book p. 18). GRD: 4.4x in a 2M-instance stress test, 2.07x in the
   Editor but 1.45x standalone in a real game (Oc6T4hh5gaI [frame 00:12:41]); here the Editor swung
   1.5x to 3.0x, players 1.9x to 2.8x on a stress fixture. Forecast about 1.5x.
3. **GC.Alloc sample time is not the cost.** Unity records only timestamp and size (e-book p. 27):
   54,021 allocations shown as 1.01 ms caused 19.97 ms of `GC.Collect` (Hall [frame 00:21:52]).
   Observed: 27,000 allocations per frame displayed 0.8 to 1.1 ms; the allocating code cost 3.8 to
   5.4 ms. Count bytes and calls, measure collections, target 0 B per gameplay frame, and keep the
   probe itself allocation-free (git-amend ham_w48aRJ4 [00:11:30]).
4. **6.3 URP draw calls = SRP Batcher + GPU Resident Drawer; the 2024 advice is Built-in-only.**
   Material "Enable GPU Instancing" off, static batching off, no MaterialPropertyBlock (6.3 Manual
   table). GRD silently does nothing unless BatchRendererGroup Variants = Keep All and every
   renderer of the URP asset is Forward+ or Deferred+ (URP 17.3 source, observed). Then prove
   coverage: GRD draws are named "Hybrid Batch Group" in the Frame Debugger (GUI editor only), each
   other draw is a renderer that fell out (MPB, LPPV, realtime GI, non-DOTS shader, skinned; 6.3
   Manual); headless, check eligibility per renderer after `Start`.
5. **Data layout first; spreading work over frames hides cost.** 200,000 objects: MonoBehaviour
   Update 27 ms to 0.13 ms through manager, structs, Burst, SoA; "it's just spreading the work
   around" (Jason Booth, NAVbI1HIzCE [00:06:38]-[00:18:17]).
6. **Attribute every hitch before fixing it, with markers kept in code.** Streaming and spawn
   systems carry their own ProfilerMarkers and counters; Deep Profile only finds what fills a gap
   (Hall [00:18:39]-[00:19:12]). Compiles show as `Shader.CreateGPUProgram` (warm a traced
   GraphicsStateCollection during loading, Nicolas Borromeo CmD8MVGkDxQ [00:11:14]-[00:14:35]); here
   warm-up removed all 18 first-use compiles, yet the first frame stayed about 250 ms on `Mono.JIT`.
7. **Resident memory kills, untracked usually does not.** 0.75 GB untracked was 140 MB resident
   (Borromeo [00:32:22]); Editor memory is about 5x the player's (Uuzd39AjFWQ [00:10:03]). On a
   laptop, paging and VRAM overflow are stutter causes of their own.
8. **Counts are exact, times drift [added, observed].** On a shared machine (load average 50 to 210
   here), interleave A/B runs and require a consistent sign.

## Establish first

Target platforms and min-spec device per tier; frame budget (16.67 ms desktop, mobile x 0.65);
resolution and quality tier; what may change (code only, or art, design, feel); a repeatable
benchmark, time-based when judging streaming (a fixed step per frame reaches boundaries sooner after
a speed-up) [added]; scripting backend and build type; the machine actually measured (discrete GPU,
on power; probe JSON `device`) [added]. Defaults: PC-tier URP asset, 60 fps, 1920x1080, development
Mono player for iteration, IL2CPP release for size.

## Workflow

1. **Budget and benchmark.** GATE: a baseline CSV.
2. **Iterate in the Editor.** `ut_perf.profile` (render=False isolates scripts), `ab_profile` for
   time deltas. GATE: numbers labeled "Editor, iteration".
3. **Static baseline.** `PerfRendering.Audit` (batching, GRD eligibility per renderer, graphics jobs
   per platform, Build Profile, stack traces, upload buffer, culling), `lint_scripts`, Project
   Auditor (`project_auditor`, Major first, `triage_auditor` keeps per-frame lines),
   `PerfAudit.AudioImport`, `bundle_duplicates`. GATE: findings triaged by call frequency.
4. **Measure the player.** `build_player(development=True)`,
   `run_player(..., shot=png, markers=[...])`. GATE: `draw_calls` > 0, PNG opened, `budget_check`.
5. **Classify the bound.** Capture wait markers (`capture_player`, `analyze_capture`), longest vs
   median frame. GPU: `metal_trace` + `metal_gpu_frames` (GPU busy and per-pass ms; Rendering
   Debugger Display Stats in the GUI), then the pixel-bound test (4K vs 1080p, render scale). GATE:
   bound named with a number.
6. **Attribute.** `attribute_spikes` (your markers, GC.Collect, compiles, MeshCollider cooking,
   synchronous reads, physics steps), `physics_catchup`, `memory_budget`, `density_check`,
   allocations per block (`AllocScope`, `Is.Not.AllocatingGCMemory()`), GRD coverage
   (`PerfFrameDebug.Capture` or the window). GATE: top three costs named, no unexplained spike.
7. **Fix one thing at a time, structure first.** Scripts: allocations, managers, then Burst. Render
   CPU: Material Variants, SRP Batcher shaders, `EnableGpuResidentDrawer`, one camera, Split
   graphics jobs on DX12/Vulkan. GPU: dynamic resolution or STP, depth priming and less
   transparency, LOD where triangles are pixel-sized, post-processing on a fixed slice; shadows with
   scenario-unity-rendering-lighting. Hitches: async loads, prewarmed pools, PSO warm-up in loading,
   baked MeshColliders, audio load types, no duplicated bundle dependencies. GATE: `compare_line`
   shows the target down, nothing else up, image parity.
8. **Ship config.** IL2CPP release, stripping and code generation chosen, variants stripped against
   the used set (P15), flags through `BuildPlayerOptions` (platform profiles share settings). GATE:
   build succeeded, size explained, smoke run clean.
9. **Guard.** Allocation tests and Performance Testing sample groups per commit, lint on changed
   scripts. GATE: tests pass.

## Numbers

| Value                                                                          | Relative to                                                                      | Source                       |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------- |
| 16.67 / 33.33 ms; x 0.65 mobile                                                | frame budget at 60 / 30 fps; thermal headroom                                    | profiling e-book p. 9, 36    |
| 0 B                                                                            | managed allocation per gameplay frame                                            | 6.3 Manual; e-book p. 66     |
| up to about 1 ms                                                               | per-frame cost of incremental GC write barriers                                  | e-book p. 69                 |
| 4.4x / 2.07x / 1.45x                                                           | GRD gain: 2M-instance stress / game in Editor / same game standalone             | Oc6T4hh5gaI [frame 00:12:41] |
| 217 / 199 / 176 / 161 fps                                                      | DX12 Split / Legacy / plain DX12 / Native graphics jobs                          | Oc6T4hh5gaI [frame 00:03:52] |
| 256 vertices                                                                   | below it GPU instancing is inefficient: combine instead                          | 6.3 Manual                   |
| about 250 ms                                                                   | one PSO creation stall                                                           | Oc6T4hh5gaI [frame 00:04:48] |
| 4 pixel invocations                                                            | per one-pixel triangle (2x2 quads); gate 1 triangle per rendered pixel [added]   | CmD8MVGkDxQ [00:27:26]       |
| 48.55 of 80 ms                                                                 | per-frame Debug.Log in a development frame                                       | xjsqv8nj0cw [00:10:23]       |
| < 200 / > 400 KB                                                               | audio: Decompress On Load / Streaming                                            | console e-book p. 104-105    |
| up to 1 ms                                                                     | CPU per extra active camera on mobile                                            | console e-book p. 89         |
| up to 10 s                                                                     | startup added by Autoconnect Profiler                                            | e-book p. 47                 |
| 50% / 70% / 80% of RAM                                                         | memory budget: 2 GB phones / general / dedicated devices                         | Hall; Unity tutorial; e-book |
| 5,946 to 33 SetPass; 58-60 to 5.2-6.2 ms                                       | 3,000 spheres, MPB tint to 8 Material Variants, dev player                       | observed                     |
| 18 to 0                                                                        | first-use `Shader.CreateGPUProgram` after warming 10 PSOs (3.6 ms at load)       | observed                     |
| 177.9 / 110.5 / 116.3 MB                                                       | macOS app: IL2CPP Minimal + speed / IL2CPP High + size / Mono                    | observed                     |
| 14.75 M to 0.26 M triangles (7.1 to 0.12 per pixel)                            | 400 dense meshes after Mesh LOD, draw calls unchanged                            | observed                     |
| 57.1 ms frame = `Spawn.Burst` 26.9 ms + 4 compiles; next frame 3 physics steps | burst of 3,000 Instantiate read through its own marker                           | observed                     |
| 48-80 ms vs 0 ms                                                               | MeshCollider cooking at spawn vs `Physics.BakeMesh` in a job at load (40 meshes) | observed                     |
| 33 us vs 2.6-3.9 us                                                            | per `Debug.Log`, stack traces ScriptOnly vs None (dev player)                    | observed                     |
| 2.5 vs 5.8 ms; 1.2x at 4x pixels                                               | GPU busy vs CPU main (Metal System Trace); 4K vs 1080p: not pixel bound          | observed                     |
| 1,944 to 1,002 KB                                                              | two bundles sharing a texture: implicit copies vs a shared bundle                | observed                     |

## Quality gates

- **Measurable:** player `budget_check` pass (p95 under budget, no gameplay hitch); `gc_check` pass
  in the player; `attribute_spikes` unexplained = 0; `physics_steps` at most 1 outside a forced
  spike; `memory_budget` pass; `density_check` pass; `PerfRendering.Audit` counts.error == 0 and
  every GRD fallout explained; 0 `Shader.CreateGPUProgram` after loading; no new Major Project
  Auditor issue in your code; IL2CPP build within budget.
- **Visual:** the player's last frame (`-perfShot`) and Editor captures from the same bookmarks
  before and after, `ut_review.compare`, contact sheet opened; no blank, uniform or magenta frame.

## Common mistakes

| Mistake                                                | What it looks like                                      | Fix                                                                   |
| ------------------------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------- |
| Optimizing the side that is not bound                  | fewer allocations, same frame time                      | classify first (wait markers, GPU busy, SetPass)                      |
| Trusting Editor numbers or one run                     | "3x faster" gone in the player                          | player CSV; `ab_profile` with consistent sign                         |
| Benchmarking a batch-mode player that renders nothing  | 0.3 ms frames, 0 draw calls                             | PerfProbe submit + `-perfShot`                                        |
| GRD on, nothing changes                                | draw calls unchanged                                    | Keep All, Forward+/Deferred+, static batching off, fallouts fixed     |
| MaterialPropertyBlock for per-object color             | SetPass = draw calls; `StdRender.ApplyShader` dominates | Material Variants; `unity_RendererUserValue` with GRD                 |
| Reading GC.Alloc ms as the cost                        | "allocations cost 0.5 ms"                               | count and bytes, `GC.Collect` ms, A/B                                 |
| A monitor that formats strings each frame              | GC column never 0                                       | preallocated buffers, write once (PerfProbe)                          |
| Closure in a rarely taken branch                       | allocations with the feature off                        | move captured locals into the branch                                  |
| Deep Profile to find a spike                           | inflated small functions                                | markers and counters kept in code, `-perfMarkers`                     |
| GPU tuned from the Frame Debugger                      | guessed timings                                         | `metal_trace` (PIX, Nsight on Windows)                                |
| Fixed render scale on a laptop                         | fine cold, hitches when hot or loaded                   | dynamic resolution; STP at a fixed scale only for a fixed pixel bound |
| Warm-up assumed to fix a first-frame hitch             | still 250 ms                                            | capture: JIT means IL2CPP, loading means async                        |
| Frame-spreading as the fix                             | lower peak, same total                                  | measure unamortized first, fix structure                              |
| MeshCollider added at runtime                          | spawn spike, `Physics.BakePhysXCollisionMeshData`       | `Physics.BakeMesh` in a job, Prebake Collision Meshes                 |
| Development flag set through `EditorUserBuildSettings` | every platform profile changed                          | `BuildPlayerOptions` or a build profile asset                         |
| Sizing from BuildReport `totalSize`                    | 1.9 GB for a 178 MB app                                 | shipped folder on disk                                                |
| `InstantiateAsync` as a hitch fix                      | 17 to 83 ms frame later                                 | pool and prewarm behind a transition                                  |
| Benchmarking the first launch of a new build           | 212 vs 22 ms                                            | discard the first launch                                              |

## What not to change without sign-off

Game feel (fixed timestep, Maximum Allowed Timestep, animation timing, input, AI ticks); art
direction (texture sizes, lights, LOD thresholds, render scale) without before/after captures; the
pipeline, engine version or an ECS rewrite; incremental GC off unless gameplay allocates 0 B in the
player and an A/B shows the gain; `asyncUploadBufferSize` raised blindly (never returned, console
e-book p. 31); VSync off in release; the benchmark path between before and after.

## Handoffs

- **Receives:** the brief in numbers from scenario-unity-expert; systems code from
  scenario-unity-architecture and scenario-unity-gameplay; pipeline assets from
  scenario-unity-rendering-lighting; shaders from scenario-unity-shaders; effects from
  scenario-unity-vfx; UI from scenario-unity-ui; bundles and Addressables from
  scenario-unity-pipeline-automation.
- **Delivers:** the bound, attributed costs, before/after tables, CSVs, traces, PNGs: variant
  stripping to scenario-unity-shaders, lighting, shadow and post cuts to
  scenario-unity-rendering-lighting, overdraw budgets to scenario-unity-vfx and scenario-unity-ui,
  physics settings to scenario-unity-gameplay, duplicate fixes, CI perf tests and build profiles to
  scenario-unity-pipeline-automation, device and thermal validation to scenario-unity-mobile, Web
  limits to scenario-unity-web.

## Unity 6.3 notes

- SRP Batcher + GRD + GPU occlusion (the 17.3 URP asset holds the occlusion flag); dynamic batching
  deprecated in 6.5, obsolete in 6.6.
- Split graphics jobs is the default on DX12/Vulkan/consoles (Oc6T4hh5gaI [00:03:04]); the 6.3 URP
  template reads Windows on/Split, Android off/Native, Metal off/Native; per-platform getters are
  internal (observed).
- `GraphicsStateCollection` is experimental, traces only in development players; WebGPU tracing in
  6.4. `FrameDebuggerUtility` is internal.
- Profile Analyzer 1.4.0, Memory Profiler 1.1.12, Project Auditor 1.0.2 (built in from 6.4),
  Performance Testing 3.5.0 (core in 6.6) and Profiling Core 1.0.3 (needed for
  `ProfilerCounterValue`) are preinstalled packages added by name.
- Mesh LOD is 6.2+. `Physics.BakeMesh(int, bool)` is obsolete: pass `mesh.GetEntityId()`. 6.3 runs
  Boehm (non-generational); CoreCLR is future work.

## References

- [`references/procedures.md`](references/procedures.md): eighteen procedures with full calls, each
  with its live test and recorded result.
- [`references/expert-notes.md`](references/expert-notes.md): principles by expert with timestamps,
  disagreements and deciding conditions.
- [`references/critique.md`](references/critique.md): the rubric for judging a performance pass.
- [`references/gui-paths.md`](references/gui-paths.md): Profiler, Frame Debugger, Rendering
  Debugger, Project Auditor and settings paths.
- [`references/sources.md`](references/sources.md): every source with credentials, URLs, best
  timestamps and revision history.
- [`scripts/ut_perf.py`](scripts/ut_perf.py) (runner side),
  [`scripts/AgentKit/Performance/*.cs`](scripts/AgentKit/Performance/) (Editor jobs),
  [`scripts/Runtime/Performance/*.cs`](scripts/Runtime/Performance/) (PerfProbe, AllocScope).

© scenario-labs · MIT · scenario-labs/skills

Похожие скиллы

Все скиллы по теме «Геймдев и 3D: Unity, Unreal, Godot, Blender» →
unity-performance JosiahSiegel Скилл unity-performance разбирает просадки FPS и фризы в Unity: что открыть в Profiler, как убрать лишние draw call и откуда берутся рывки на сборке мусора. CX Codex +1 103установок new-unity-project Unity-Technologies Скилл new-unity-project автоматизирует создание проекта в Unity: от концепта до инициализации git, пакетов и фоновой установки редактора. CX Codex +1 8 000установок unity-project-setup davila7 Команда unity-project-setup разворачивает шаблон игрового проекта Unity с папками Assets, URP, базовыми C#-скриптами и конфигурацией Git LFS прямо через диалог с Claude Code. CX Codex +1 303установок performance-optimization gamedev-skills Скилл performance-optimization для Claude Code находит причины низкой частоты кадров и рывков в Godot, Unity, Unreal и Roblox. Подключается для профилирования игры и выбора самой затратной проблемы. CX Codex +1 14 200установок unity Mindrally Скилл задаёт агенту правила игры в Unity: компонентная архитектура, ScriptableObjects, пулы объектов и работа с профайлером. CX Codex +1 967установок unity-developer rmyndharis Скилл unity-developer для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode — подключает экспертизу Unity 6 LTS: рендер-пайплайны, C# оптимизацию, кросс-платформенные сборки. CX Codex +1 3 000установок

Из того же набора172

Весь набор →
scenario-ad-variants Скилл scenario-ad-variants создаёт пачку независимых рекламных вариантов из исходного видео: меняет хуки, призывы к действию, плашки и титры в Scenario. CX Codex +1 610установок scenario-unity-vfx Скилл scenario-unity-vfx для создания и оптимизации реал-тайм эффектов в Unity 6.3: взрывы, огонь, шейдеры с LUT-рампами, мешевые эффекты с прокруткой текстур. Помогает держать бюджет частиц и заливки на мобильных устройствах. CX Codex +1 606установок scenario-unity-animation Скилл scenario-unity-animation для работы с анимацией персонажей и камерами в Unity 6.3. CX Codex +1 602установок scenario-unity-shaders Скилл scenario-unity-shaders для работы с шейдерами в Unity 6.3 URP: HLSL, Shader Graph, compute шейдеры, варианты и оптимизация. Помогает когда материал розовеет, эффект не работает или игра подтормаживает при первом появлении объекта. CX Codex +1 600установок scenario-unity-rendering-lighting Скилл scenario-unity-rendering-lighting помогает настроить URP, освещение и постобработку в Unity, а также разобрать проблемы со светом, тенями и производительностью. CX Codex +1 598установок scenario-chatgpt-pet-update Скилл scenario-chatgpt-pet-update обновляет спрайт-листы питомцев ChatGPT и Codex через Scenario: чинит анимации, меняет цвета и генерирует предпросмотр в GIF. CX Codex +1 592установок scenario-chatgpt-pet-create Скилл scenario-chatgpt-pet-create создаёт питомца для ChatGPT или Codex из текста и референсов: спрайт-листы, GIF и пакет pet.json. CX Codex +1 591установок scenario-unity-gameplay Скилл scenario-unity-gameplay для разработки и отладки игровых систем Unity: вражеский ИИ, NavMesh, физика снарядов, мультиплеер на Netcode, звук. Опирается на измеренные данные из выпущенных игр. CX Codex +1 591установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой