Replay System Tutorial

Before you begin, make sure you have the following:

PerfGuard plugin installed in your UE5 project. If you haven't set it up yet, see the Quick Start tutorial first.

A map with gameplay content — something with AI, physics, or streaming that you want to benchmark. You can also use the bundled demo scene at Content/Demo/Levels/DemoScene.

Basic PIE familiarity — you should know how to start Play-In-Editor and use the console (~ key).

Right-click in the Content Browser, then select PerfGuard → Performance Scenario. Name it something descriptive like PS_CombatReplay.

Open the scenario asset and configure these settings:

Scenario Name: CombatReplay (or any name you prefer)
Capture Source: Replay — this tells PerfGuard to play back a recorded demo instead of a Level Sequence
Map Asset: Select your gameplay map
Warmup Frames: 120 — replay scenarios need more warmup for streaming and initialization
Stat Configs: Add FrameTime, GPUTime, GameThreadTime, and DrawCalls

You have two options for recording gameplay.

Option A: In-Editor Recorder (Recommended)

Open your replay scenario in the Details panel. The Replay Configuration section appears automatically when Capture Source is set to Replay. Click Play (PIE) to start Play-In-Editor, then click Record New... in the Replay Configuration section.

Play through your scenario — fight enemies, trigger physics, run through streaming zones. When you're done, click Stop Recording. The replay file is automatically selected in the dropdown, and the duration is auto-detected.

Option B: Console Commands

If you prefer manual control, start PIE and open the console (~ key):

// Start recording
demorec MyCombatReplay

// Play through your scenario, then stop
demostop

The replay is saved to Saved/Demos/MyCombatReplay.replay. Back in the scenario Details panel, click Refresh in the Replay Configuration dropdown and select your file.

After recording, the Replay Configuration section shows metadata for your selected file:

File size — a healthy replay is typically 1–50 MB depending on duration and complexity.
Last modified date — replays older than 30 days may not be compatible with engine updates.
Duration — auto-detected from the replay header when available.

Click the Validate Scenario button in the Actions section to run replay-specific checks: replay file exists and is non-empty, capture duration is set, warmup frames are adequate (120+ recommended), and determinism settings are configured.

Click Run Standalone in the Actions section of the scenario Details panel. This launches a separate process (not PIE) that loads the map, starts replay playback, warms up for the configured number of frames, captures CSV performance data, and saves results to Saved/PerfGuard/Results/.

You can also run from the CLI:

perfguard run suite.json

Or directly with Gauntlet:

UnrealEditor MyProject.uproject -game \
    -gauntlet=PerfGuardGauntletController \
    -scenario=CombatReplay \
    -csvprofile -RenderOffScreen -unattended -log

UnrealEditor.exe MyProject.uproject -game ^
    -gauntlet=PerfGuardGauntletController ^
    -scenario=CombatReplay ^
    -csvprofile -RenderOffScreen -unattended -log

Once you have a clean capture, save it as the performance baseline for future comparisons:

perfguard baseline record CombatReplay --auto-csv

After making gameplay or rendering changes, run the capture again (Step 5) and then compare against the baseline:

perfguard baseline compare CombatReplay --auto-csv

Generate the HTML report from your results:

perfguard report Saved/PerfGuard/Results/

The HTML report includes several replay-specific features:

Capture Source Badge — an orange "Replay" badge next to the scenario name, so you can instantly distinguish replay captures from Level Sequence captures.

Single-Run Warning — if you only ran once, the report recommends running 3+ times for reliable regression detection.

High CoV Warning — if the coefficient of variation exceeds 5%, the report flags it and explains that this is expected with replay captures due to non-deterministic physics, AI, and streaming.

Replay Metadata — the report's metadata section shows the replay file name and capture source for traceability.

Replay captures have inherent variance that Level Sequence captures do not. Understanding the sources helps you set appropriate thresholds and interpret results correctly.

The replay system is fully exposed to Blueprint via the PerfGuard Subsystem (access via Get Game Instance → Get Subsystem → PerfGuard Subsystem). These functions let you build custom replay workflows entirely in Blueprint:

StartReplayPlayback(ReplayFilePath, World)   // Start replay playback
StopReplayPlayback()                            // Stop replay playback
IsReplayPlaying()                               // Check if a replay is currently playing
GetReplayDuration(ReplayFilePath)              // Get duration in seconds
GetDefaultReplayDir()                           // Get configured replay directory path

Replay scenarios work with all CI systems just like Level Sequence scenarios. The key difference is using wider thresholds to account for replay variance.

In your suite.json, replay scenarios look like any other — the scenario asset itself defines the capture source:

{
  "scenarios": [
    {
      "name": "CombatReplay",
      "csv": "Saved/Profiling/CSV/",
      "thresholds": {
        "FrameTime": {"max_regression_percent": 10.0},
        "GPUTime": {"max_regression_percent": 10.0}
      }
    }
  ]
}

Note the wider thresholds (10% vs the typical 5%) to account for replay variance.

Your CI workflow runs the same command regardless of capture source:

- name: Run replay benchmark
  run: |
    perfguard run suite.json --mode compare --budget 30fps

For more details on CI pipeline configuration including Jenkins, GitLab, and BuildGraph, see the CI Setup tutorial.