unity-profiling
Measure frame time, hitches and GC with ProfilerRecorder counters; before/after numbers.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- unity-profiling
- description
- Measure frame time, hitches and GC with ProfilerRecorder counters; before/after numbers.
02 资源文件 20
- 参考文档reference/compare.md6.4 KB
- 参考文档reference/counters.md7.2 KB
- 参考文档reference/frame-hygiene.md3.8 KB
- 参考文档reference/frame-windows.md8.0 KB
- 参考文档reference/gc-per-phase.md3.2 KB
- 参考文档reference/perf-tests.md11.1 KB
- 参考文档reference/raw-capture.md5.8 KB
- 参考文档reference/runtime-asset-leaks.md2.4 KB
- 参考文档reference/where-the-time-goes.md7.6 KB
- 参考文档reference/work-counters.md6.1 KB
- 其他resources/CounterCatalog.cs6.7 KB
- 其他resources/FrameSampler.cs30.2 KB
- 其他resources/GcAllocProbe.cs6.2 KB
- 其他resources/GcAllocProbeOpener.cs529 B
- 其他resources/OwnedAssets.cs2.2 KB
- 其他resources/ProfilerRawCapture.cs10.6 KB
- 其他resources/WorkCounters.cs6.8 KB
- 脚本scripts/compare_windows.py18.6 KB
- 其他templates/AssetLeakSoakTest.cs5.0 KB
- 其他templates/PerfRegressionTest.cs15.1 KB
03 SKILL.md 正文
unity-profiling — measure the work, then compare the table
"It feels smoother now" survives exactly until someone else plays it. A frame time on its own is barely better: one number, from one moment, on one machine, with nothing to hold it against.
Load what the situation needs
| The situation | Read |
|---|---|
| Starting from nothing; "how many draw calls is this"; "which counters exist on my version"; a counter reads zero | reference/counters.md |
| "The frame rate drops when…" — taking the measurement: warm-up, window size, run modes, the log line and the JSONL schema | reference/frame-windows.md |
| "It hitches when the third pickup spawns" — hitches around spawning, streaming or pooling; a system that builds the same thing twice | reference/work-counters.md |
| "did my change actually help"; building the before/after table; a comparison that refuses | reference/compare.md |
| A window in hand and no cause yet: first-appearance hitch, GC, synchronous loads, distant geometry | reference/where-the-time-goes.md |
| No counter names the cost and you need the marker inside the frame | reference/raw-capture.md |
| A frame-time budget that a test fails on, every run, against this machine's recorded baseline | reference/perf-tests.md · templates/PerfRegressionTest.cs |
"is it the GC" and whose: allocation calls per Update and LateUpdate phase; GetAllocatedBytesForCurrentThread reads 0 |
reference/gc-per-phase.md · resources/GcAllocProbe.cs |
| Memory grows by a step each time a screen or match is rebuilt; runtime materials and meshes | reference/runtime-asset-leaks.md · resources/OwnedAssets.cs · templates/AssetLeakSoakTest.cs |
| A frame time read on a shared machine; post-processing cost; CPU or GPU in the Editor | reference/frame-hygiene.md |
Files and instruments
Files to copy into Assets/ — namespace UnityDev.Perf, Runtime, no package required:
resources/CounterCatalog.cs, resources/FrameSampler.cs, resources/WorkCounters.cs,
resources/ProfilerRawCapture.cs, plus resources/GcAllocProbe.cs with GcAllocProbeOpener.cs
for allocation by phase and resources/OwnedAssets.cs for runtime-asset ownership (that one is
gameplay code). The rest are instrumentation, not gameplay; keep them behind a
development-build check before shipping.
What settles a performance question is a window — a fixed number of frames of a named situation, summarised into one row — taken twice, with one thing changed in between.
A driven run is not a hardware benchmark.
batchmode-nographics,editor-windowedand a player build are three different instruments. Each is internally consistent and none of their numbers mean anything against another's. Every window records which instrument produced it, and the comparison script refuses to subtract across them. And a human playing the actual build still decides shader compilation, GPU upload and whether the thing feels good — measurement narrows the question, it does not answer it.
The loop
1 · List the counters this build exposes. Never recall them. Names differ by render pipeline,
graphics backend, platform and version, and a wrong name produces a recorder that reads 0 —
indistinguishable from "this build draws nothing". resources/CounterCatalog.cs, then
reference/counters.md.
2 · Sample a window. 90 frames after 30 warm-up frames, sampled in LateUpdate at the end of
the execution order with a Stopwatch as the clock. Out comes one greppable [PERF] line and one
JSONL record. resources/FrameSampler.cs, then reference/frame-windows.md.
3 · Change exactly one thing. Two changes in one window cannot be attributed, and the wrong one gets kept.
4 · Re-run the same situation and compare. Same seed, same instrument, three windows a side.
scripts/compare_windows.py, then reference/compare.md.
One turn of the loop
The complaint is "it hitches when the third pickup spawns in the hazard lane". Booted into that situation with a fixed seed, one window says:
[PERF] window=hazard-lane mode=editor-windowed frames=90 ft_med=8.31 ft_p95=12.90 ft_max=41.2
hitches=2 draw_med=412 tris_med=51200 gc_sum=184320 disc[pickup-pool]=214 missing=1 zero=0
Read it in that order. The median is fine, so the game is not uniformly heavy; ft_p95 at 12.90
against a median of 8.31 is unevenness. Draw calls and triangles are the same as the run before,
so it is not a rendering cost at all. The last number is the finding: the pickup pool threw away
214 units of work during those ninety frames while completing seventeen. The lane selector is
flipping across a 1.3-unit lane boundary and cancelling the set it was building each time.
A 0.2-unit dead band on that boundary, then the same window again: discarded 214 → 7, ft_p95
12.90 → 9.10 ms, hitches 2 → 0, triangles unchanged. One parameter, two numbers that moved
together, and a table that says why.
Where the time goes
A router, read against a window you already have. Depth for the first four rows is in
reference/where-the-time-goes.md; the rest belong to the skill that owns the subsystem.
| The window says | Go to |
|---|---|
One large ft_max the first time something appears, never again |
first-appearance section, then unity-render-urp |
Memory/GC Allocated In Frame has a non-zero median; spikes on a period |
GC section, then unity-game-ui for per-frame string building |
| A spike lined up with a jump in a completed-work counter | synchronous-loads section, then unity-audio when it is a clip |
| Triangles high while looking at distance, draw calls ordinary | distant-geometry section, then unity-scene-optimisation |
| Discarded work climbing while scheduled climbs | reference/work-counters.md |
| Draw calls and SetPass calls high, triangles ordinary | unity-scene-optimisation · unity-sprite-atlas for 2D · unity-game-ui for canvases |
| GPU frame time much larger than the CPU times | unity-scene-optimisation · unity-render-urp for post-processing |
| Shadow caster count high | unity-lighting |
| Pixel art shimmering as well as slow | unity-2d-pixel-perfect |
| Slow only in the browser | unity-web-release |
| Slow only on the device, fine in the editor | unity-device-testing, after a development-player window taken on it |
| Frame time is fine and it still feels wrong | unity-play-harness |
Discipline
- List, never recall. Counter names are defined by the build, not by your memory of them. One catalogue call is cheaper than one wrong name, and a wrong name reports zero rather than failing.
- A counter that reads zero on every frame of a window is an absence, not a measurement of
nothing. The window separates the two:
missing[]is "not exposed on this build",zeroAll[]is "exposed and flat". Report both; never quietly average a zero into a result. - A quiet machine, or do not measure. Another Editor or a Blender job turned 1.6–2.4 ms into
4–10 ms in one project; check the process list first (
reference/frame-hygiene.md). - Same situation, same instrument, or do not compare. Different run mode, graphics device, screen size, vsync or warm-up makes two numbers that subtract cleanly and mean nothing.
- Median and worst, never just worst — one spike and a constant vibration are different faults — with p95 between them to say where the bad frames start.
- Warm up 30 frames by default. The first frames after entering a situation measure starting,
not playing. Set warm-up to 0 deliberately when a first-appearance hitch is the subject, and
put a
-coldsuffix on that window's label so nobody compares it against a warmed one. - Three windows a side before believing a 10% change. Below that, one window each way is a coin toss, and the comparison script will tell you when the spread makes the change unreadable.
- Delete the JSONL before every run. It is appended to. A stale window compared against a fresh one is the quietest wrong answer this skill can produce.
- Print the numbers the judgement rests on. "The hitch is gone" ages badly; "discarded 214 → 7, p95 12.90 → 9.10 ms" keeps saying the same thing after the next change.
- Check whether the candidate is faster because it does less. Fewer things built is not the same as things built more cheaply. Read the scheduled and completed counters before celebrating.
- Every report names its run mode and what it did not cover. A report that omits the instrument invites the reader to assume it was the shipped game.
Scope — what this skill does NOT do
| Not here | Go to |
|---|---|
| Booting into a moment, a readable state line, a feel complaint with nothing to measure | unity-play-harness |
| Driving Unity, exit codes, screenshots, proving a harness told the truth | unity-debug |
| Installing editors, licences, CI invocation | unity-cli |
| Atlasing sprites, decimating meshes | unity-sprite-atlas · unity-3d-models |
| Configuring post-processing and renderer features | unity-render-urp |
| Browser download size, headers and memory ceilings | unity-web-release |
| Building, signing and reading a device artifact back | unity-android-release |
| Stutters on the device, runs fine in the Editor — a window taken on the phone | unity-device-testing |
| Audio memory, load types and mixer cost | unity-audio |
| Deciding what the budget should be | unity-game-brief |
| Where a character's frame windows fall: the budget ladder, the import check | game-character-pipeline |
04 同仓库更多 Skills
unity-web-release
Ship a WebGL/WebGPU build: shrink the download, Brotli server headers, Safari and iPhone memory.
unity-vivox
Vivox voice and text chat: channels, positional voice, mute and push-to-talk, mic permission.
unity-urp-migration
Migrate a Built-in project to URP, or fix a half-moved one: pink materials, PPv2, old shaders.
unity-ui-ugui
Canvas UI (uGUI): CanvasScaler, RectTransform anchors, Layout Groups, ScrollView, UI built from C#.
unity-ui-toolkit
UI Toolkit (UXML, USS, UIDocument): flex layout, binding, custom elements, editor windows.
unity-ugs
Unity Gaming Services API: which package, init and sign-in order, Cloud Save, Cloud Code, Remote Config.