game-perf-profiling · git:20260724.d4db756 · 2026-07-24 · sha256 4e60683b707c51c4
game-perf-profiling git:20260724.d4db756A
Immutable. This exact content never changes and is served at /api/v1/blob/4e60683b707c51c4.
---
name: game-perf-profiling
description: "Profiles game builds against frame-time, memory, GPU draw-call, and GC-spike budgets using Unity Profiler + Profile Analyzer + Performance Testing package and Unreal Insights + stat commands. Establishes pass/fail thresholds (16.6 ms at 60 fps, 33.3 ms at 30 fps), writes automated performance regression tests that run in CI, and emits a structured budget report per SKU. Use when a title must hit a declared frame-time or memory budget before a milestone gate or platform-cert submission, or when a recent change needs a performance regression check."
metadata:
keywords: "game-performance, frame-time, profiling, unity-profiler, profile-analyzer, performance-testing, unreal-insights, gc-spike, draw-calls, overdraw, ci-regression"
---
# game-perf-profiling
## Overview
Game performance QA verifies that a build meets its declared budgets across
every target SKU before milestone sign-off or platform-cert submission.
The performance category (category 4 in the
game-test-categories-reference)
covers frame-time, memory, GPU, thermal, and battery axes. This skill covers
the two dominant engine stacks: Unity and Unreal Engine.
**Frame-time budget anchors** (from
game-test-categories-reference):
| Target frame rate | Frame-time budget |
|---|---|
| 60 fps | 16.67 ms per frame |
| 30 fps | 33.33 ms per frame |
Measuring averages is an anti-pattern: spikes hide in averages and cause
cert failures. Measure p99 (99th-percentile frame time) and sustained-window
maximums.
## Step 1: Unity - Capture with the Profiler
The Unity Profiler is a performance analysis tool that collects CPU, GPU,
and memory data either in the Editor or from a connected target device
([docs.unity3d.com/Manual/Profiler.html](https://docs.unity3d.com/Manual/Profiler.html)).
Open it via **Window > Analysis > Profiler** (or `Ctrl+7`). Key modules to
enable for a frame-time pass:
- **CPU Usage** - game thread, render thread, and job-system costs per frame.
- **GPU Usage** - available on Windows DirectX 11/12 and Linux OpenGL;
breaks down time into Opaque, Transparent, Shadows/Depth, Deferred, and
PostProcess passes with DrawCalls counts and GPU ms per entry
([docs.unity3d.com/Manual/ProfilerGPU.html](https://docs.unity3d.com/Manual/ProfilerGPU.html)).
Note: GPU profiling is unavailable when Graphics Jobs are enabled in
Player Settings; disable them before a profiling session
([docs.unity3d.com/Manual/ProfilerGPU.html](https://docs.unity3d.com/Manual/ProfilerGPU.html)).
- **Memory** - tracks managed heap, GC allocations per frame in bytes, and
reserved vs. in-use breakdowns for textures, meshes, materials, and
animation clips
([docs.unity3d.com/Manual/ProfilerMemory.html](https://docs.unity3d.com/Manual/ProfilerMemory.html)).
For standalone builds, use **Deep Profiling** or custom `ProfilerMarker`
instrumentation to capture application-specific events without the full
overhead of deep profiling
([docs.unity3d.com/Manual/Profiler.html](https://docs.unity3d.com/Manual/Profiler.html)).
Save the capture as a `.data` file (Profiler toolbar > Save). Retain this
alongside any Profile Analyzer `.pdata` export: the `.pdata` file does not
embed the original profile frames
([docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html](https://docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html)).
## Step 2: Unity - Analyze with Profile Analyzer
Profile Analyzer (package `com.unity.performance.profile-analyzer`, Unity
2020.3+, install via Package Manager) aggregates and visualizes frame and
marker data from a set of Profiler frames, enabling side-by-side comparison
of two captures that the standard Profiler does not support
([docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html](https://docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html)).
Open it via **Window > Analysis > Profile Analyzer**.
Workflow for a regression check:
1. Load the **baseline** `.data` file as the left dataset.
2. Load the **candidate** `.data` file as the right dataset.
3. Compare median and p99 frame times per marker against the budget.
4. Flag any marker whose p99 exceeds the per-frame budget allocation.
The Analyzer attempts to navigate to matching markers in the Profiler when
you click a marker entry; you must make a selection in the Profiler
beforehand for navigation to work
([docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html](https://docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html)).
## Step 3: Unity - Automated regression with Performance Testing package
Add `"com.unity.test-framework.performance": "3.0.3"` to `Packages/manifest.json`
and reference `Unity.PerformanceTesting` in your assembly definition
([docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html](https://docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html)).
### Measure.Method (Edit Mode or Play Mode)
```csharp
[Test, Performance]
public void PathfindingCost_UnderBudget()
{
Measure.Method(() => pathfinder.FindPath(start, goal))
.WarmupCount(5)
.MeasurementCount(20)
.IterationsPerMeasurement(10)
.Run();
}
```
- `WarmupCount(n)`: executes the method n times before recording to remove
initialization overhead.
- `MeasurementCount(n)`: number of samples recorded; default is 7; 20+
improves stability.
- `IterationsPerMeasurement(n)`: repeats the code within each measurement to
extend execution time above the 1 ms sensitivity floor.
([docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html](https://docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html))
### Measure.Frames (Play Mode)
```csharp
[UnityTest, Performance]
public IEnumerator CombatScene_FrameTime_UnderBudget()
{
yield return Measure.Frames()
.WarmupCount(5)
.MeasurementCount(60)
.Run();
}
```
Target standard deviation below 5%; avoid measurements under 1 ms due to
environmental sensitivity
([docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html](https://docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html)).
Decorate tests `[Test, Performance]` for Edit Mode or `[UnityTest, Performance]`
for Play Mode coroutines. View results via **Window > Analysis > Performance
Test Report**.
### GC-spike detection
Enable the `ProfilerMarkers` method on `Measure.Method` to target
`GC.Alloc` markers specifically:
```csharp
Measure.Method(() => SpawnWave())
.ProfilerMarkers("GC.Alloc")
.MeasurementCount(20)
.Run();
```
A passing frame should produce 0 bytes of GC allocation in hot gameplay
paths. Any non-zero sample is a regression candidate.
Disable VSync in Project Settings and remove cameras not needed for the
measurement to keep results consistent between runs
([docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html](https://docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html)).
## Step 4: Unreal - Stat commands for first-pass triage
Unreal Engine stat commands are entered into the PIE console while the
game runs
([dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine)):
| Command | Shows |
|---|---|
| `stat fps` | Frames per second counter |
| `stat unit` | Frame, Game thread, Draw (render thread), GPU, RHIT, and DynRes times; recommended starting point |
| `stat gpu` | GPU statistics for the frame |
| `stat scenerendering` | General rendering statistics; entry point for rendering bottleneck triage |
| `stat game` | How long the various gameplay ticks are taking |
| `stat memory` | Memory usage by subsystem |
`stat unit` is the first command to run on any new build: it identifies
whether the bottleneck is game-thread, render-thread, or GPU, and measures
how long the video card takes to render the scene
([dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine)).
Run in a non-debug build for accurate results.
## Step 5: Unreal - Deep analysis with Unreal Insights
Unreal Insights is a telemetry capture and analysis suite that captures
events from a project at high data rates
([dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine)).
Launch from the Editor via the **Trace/Insights Status Bar Widget** in the
bottom toolbar, or from the prebuilt binary at
`Engine\Binaries\[Platform]\UnrealInsights.exe`
([dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine)).
Key trace channels:
| Channel | Captures |
|---|---|
| CPU | Thread-level timing per task and function |
| GPU | Per-frame GPU timing |
| Memory | Allocation, reallocation, and deallocation events |
| Networking | Network traffic for multiplayer titles |
| Slate | UMG/Slate widget update costs |
| Asset loading | Asset load time per type |
Live sessions appear in the Session Browser with a "LIVE" status indicator;
Insights supports simultaneous connection to multiple sessions and records
streams automatically for later replay
([dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine)).
Primary views:
- **Timing Insights**: CPU and GPU performance tracks with frames, filters,
timers, counters, and caller/callee information.
- **Memory Insights**: Reconstructs runtime memory usage patterns from
traced allocation events.
([dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine))
## Step 6: GPU draw-call and overdraw budgets
### Unity
The GPU Usage module's Hierarchy view shows DrawCalls count and GPU ms per
rendering pass
([docs.unity3d.com/Manual/ProfilerGPU.html](https://docs.unity3d.com/Manual/ProfilerGPU.html)).
Typical mobile budget: under 100 draw calls per frame; PC/console budget
is title-specific but PostProcess and Transparent passes are common
over-budget culprits.
Overdraw (multiple pixels written per screen pixel per frame) is visible
when Transparent pass GPU ms is disproportionate to scene complexity.
Reduce by: lowering particle counts, using depth pre-pass, culling
off-screen transparency.
### Unreal
Run `stat scenerendering` to surface general rendering statistics as the
entry point for rendering bottleneck identification
([dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine)).
Follow with `stat gpu` to get per-pass GPU time, then use the GPU Visualizer
(`ProfileGPU` console command) for a hierarchical breakdown of GPU passes
to isolate overdraw-heavy translucent passes
([dev.epicgames.com/documentation/en-us/unreal-engine/gpu-profiling-in-unreal-engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/gpu-profiling-in-unreal-engine)).
## Step 7: CI regression gate
### Unity
Run Performance Testing package tests in a headless Unity batch session:
```bash
unity -batchmode -runTests -testPlatform StandaloneWindows64 \
-testResults results.xml -projectPath .
```
Parse `results.xml`; fail the build if any `PerformanceMeasurement` sample
set has a median or p99 exceeding the declared threshold. A zero-tolerance
`GC.Alloc` assertion on hot paths is a recommended gate: one stray allocation
per frame compounds to hundreds of KB/s under sustained play.
For stable CI numbers: disable VSync, remove unused cameras, set a fixed
Quality level, and disable hardware reporting in Player Settings
([docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html](https://docs.unity3d.com/Packages/com.unity.test-framework.performance@3.0/manual/index.html)).
### Unreal
Unreal Automation System (see
unreal-automation-system) exposes a
`PerformanceCapture` test type. Combine with a CI step that launches Insights
in server mode, runs the target map for N frames, exports the trace, and
compares the exported GPU/CPU frame time histogram against stored baselines.
## Budget report template
Emit one row per profiled scenario per SKU:
| Scenario | SKU | Metric | Budget | Measured (p50) | Measured (p99) | Status |
|---|---|---|---|---|---|---|
| Combat encounter | PC High | Frame time | 16.67 ms | 11.2 ms | 18.4 ms | FAIL p99 |
| Combat encounter | PC High | GC alloc/frame | 0 B | 0 B | 128 B | FAIL p99 |
| Open-world traversal | PC High | Frame time | 16.67 ms | 13.1 ms | 15.9 ms | PASS |
A FAIL on p99 triggers a regression investigation before milestone sign-off.
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Averaging frame time across a level | Spikes hide in averages and cause cert failures | Use p99 and sustained-window maximums |
| Profiling with Graphics Jobs enabled in Unity | GPU module is disabled; no GPU data collected | Disable Graphics Jobs before capture |
| GC alloc tolerance in hot paths | Compounds to MB/s under sustained play | Assert 0 B per frame in CI on hot paths |
| Running perf tests in debug builds (Unreal) | Inaccurate results; use non-debug builds | Profile in Development or Shipping builds |
| Single-device perf sign-off | Low-end SKU (Series S, Switch handheld) is the binding constraint | Run budget checks on every SKU in the compatibility matrix |
## Limitations
- Unity GPU profiling: Vulkan (Android, Linux, Windows), Metal (iOS/macOS),
and WebGL are not supported; only DirectX 11/12 (Windows) and OpenGL
(Linux) work
([docs.unity3d.com/Manual/ProfilerGPU.html](https://docs.unity3d.com/Manual/ProfilerGPU.html)).
- Unity Memory module detailed object statistics are unavailable in release
builds
([docs.unity3d.com/Manual/ProfilerMemory.html](https://docs.unity3d.com/Manual/ProfilerMemory.html)).
- Profile Analyzer `.pdata` files do not embed original Profiler frames;
retain `.data` files alongside them
([docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html](https://docs.unity3d.com/Packages/com.unity.performance.profile-analyzer@1.2/manual/index.html)).
- Sony TRC and Nintendo Lotcheck thermal/battery performance gates are
NDA-gated; consult the developer portal for current requirement numbers.
Cited by stable ID "Sony TRC" and "Nintendo Lotcheck" per
`docs/PLUGIN_AUTHORING.md` Step 4 fallback.
- Godot engine performance tooling is out of scope; see
godot-gut-tests for that engine's test
framework.