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 platform-cert-overview-reference test-category taxonomy) 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 platform-cert-overview-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

Open the Profiler via Window > Analysis > Profiler (Ctrl+7) and enable the CPU Usage, GPU Usage, and Memory modules for a frame-time pass. Save the capture as a .data file (Profiler toolbar > Save) and retain it alongside any Profile Analyzer .pdata export - the .pdata file does not embed the original profile frames. Module-by-module capture detail, GPU-module platform constraints, and Profile Analyzer setup are in references/unity-profiler.md.

Step 2: Unity - Analyze with Profile Analyzer

Profile Analyzer compares two captures side by side, which the standard Profiler cannot. Open it via Window > Analysis > Profile Analyzer, then run the 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.

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).

Measure.Method (Edit Mode or Play Mode)

[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.

Measure.Frames (Play Mode)

[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.

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:

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.

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):

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. Run in a non-debug build for accurate results.

Step 5: Unreal - Deep analysis with Unreal Insights

When stat triage is not enough, capture a full trace with Unreal Insights. Launch it from the Editor's Trace/Insights Status Bar Widget or the prebuilt Engine\Binaries\[Platform]\UnrealInsights.exe binary, then work the CPU/GPU/Memory/Networking trace channels in the Timing Insights and Memory Insights views. The trace channels, the live Session Browser, and the two primary views are detailed in references/unreal-insights.md.

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 (see references/unity-profiler.md). 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. 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).

Step 7: CI regression gate

Unity

Run Performance Testing package tests in a headless Unity batch session:

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.

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).
• Unity Memory module detailed object statistics are unavailable in release builds (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).
• 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.