Authoring Performance Scenarios

A UPerfScenario is a UPrimaryDataAsset that packages everything PerfGuard needs to run a single performance test: which map to load, which Level Sequence to play, which stats to record, and how to handle warmup.

The Gauntlet controller uses the Asset Registry to discover scenarios by name at runtime, so they can live anywhere in your content hierarchy. One scenario = one test. A typical project has 3–10 scenarios covering different maps or camera angles.

Every scenario needs a Level Sequence that drives a CineCamera Actor along a deterministic path. This is what makes your tests repeatable — the same pixels are rendered every run.

In the editor:

1. Go to Cinematics → Add Level Sequence and save it
2. In the Sequencer, click + Track → Actor to Sequencer → CineCamera Actor
3. Move the camera to your starting position and keyframe the Transform
4. Advance the timeline, reposition the camera, and add more keyframes
5. Repeat until you've covered the heaviest views in the map

Open your PerfScenario asset and set these core properties in the Details panel:

• Scenario Name — A unique identifier used by the CLI (e.g., MainMenu_Flythrough)
• Capture Source — Choose between Level Sequence (deterministic camera flythroughs), Replay (gameplay-driven scenarios with AI/physics), or Duration Only (static scene profiling from a fixed viewpoint)
• Map — Soft reference to the level asset to load
• Level Sequence — Soft reference to the camera sequence to play (Level Sequence mode)
• Replay File Path — Path to a .replay file in Saved/Demos/ (Replay mode)
• Capture Duration — How long to capture in seconds; 0 = use sequence/replay length
• bCaptureTrace — Record an Insights trace alongside CSV (default: true)

The Tracked Stats array determines which CSV profiler columns PerfGuard monitors. Common choices:

• FrameTime — Total frame time in ms (the primary metric)
• GameThreadTime — CPU game thread cost
• RenderThreadTime — CPU render thread cost
• GPUTime — GPU frame cost
• DrawCalls — Number of draw calls per frame
• TrianglesDrawn — Triangle count per frame

You can track any column present in the CSV profiler output. Start with the defaults and add more as you identify bottlenecks.

The first frames of any capture are polluted by shader compilation, texture streaming, and level loading hitches. The Warmup Frames setting tells PerfGuard how many initial frames to discard before measuring.

A typical value is 60 frames (about 1 second at 60fps). If your scene has heavy streaming (large open worlds), increase to 120–180.

perfguard baseline record MyScenario \
    --csv path/to/csv \
    --warmup 60  # Skip first 60 frames

PerfScenario assets support tags for grouping and filtering. Use them to categorize tests by area, priority, or purpose:

• gpu-heavy — Scenes that stress the GPU
• cpu-bound — Game thread bottleneck tests
• smoke — Fast sanity checks for every PR
• nightly — Comprehensive tests for nightly builds
• marketplace-demo — Scenarios for demo scenes

Tags can be used in suite configuration files to run subsets of your test suite in different CI contexts.

Adopt a consistent naming scheme so scenarios are self-documenting:

# Pattern: PS_{MapName}_{ViewDescription}
PS_MainMenu_FullRotation
PS_CityLevel_StreetFlythrough
PS_Arena_CombatOverview
PS_OpenWorld_LongDrive

• Prefix with PS_ so scenarios are easy to find in the Content Browser
• Include the map name for immediate context
• Describe what the camera does, not the test purpose
• Store all scenarios under Content/PerfGuard/Scenarios/

Before running headless Gauntlet captures, verify your scenario works in the editor. Open the PerfScenario asset and use the Preview functionality to play the sequence in-editor and confirm the camera path is correct.

Check for:

• Camera clips through geometry
• Sequence length is appropriate (10–30 seconds)
• The heaviest views are covered by the camera path
• No dependency on runtime gameplay state

PerfScenario assets have built-in editor tooling to speed up your workflow:

• Validate button — In the Details panel, click Validate to check for missing map or level sequence references before running a capture
• Run button — Launch a Gauntlet capture directly from the editor without switching to the command line
• Context menu — Right-click scenario assets in the Content Browser for quick actions

PerfGuard can record Unreal Insights traces alongside CSV profiler data, giving you GPU pass timings, RHI commands, and per-draw-call detail for deep investigation.

Enable it by setting the bCaptureTrace property on your PerfScenario asset to true. Trace data appears in the HTML report as GPU pass breakdown charts.

# Via CLI flag
perfguard run suite.json --no-trace

# Or set bCaptureTrace = false on the scenario asset