Quick Start: Your First Performance Test

PerfGuard can be installed from the FAB marketplace or by copying the plugin directly into your project. For manual installation, clone or extract the plugin into your project's Plugins/ directory.

# Option A: Copy plugin folder
cp -r PerfGuard/ YourProject/Plugins/PerfGuard/

# Option B: Symlink (useful during development)
ln -s /path/to/PerfGuard YourProject/Plugins/PerfGuard

:: Option A: Copy plugin folder
xcopy /E /I PerfGuard\ YourProject\Plugins\PerfGuard\

:: Option B: Symlink (useful during development)
mklink /D "YourProject\Plugins\PerfGuard" "C:\path\to\PerfGuard"

After copying, regenerate your project files so UnrealBuildTool picks up the new plugin module.

Open your project in Unreal Editor and navigate to Edit → Plugins. Search for "PerfGuard" and enable it. The editor will prompt you to restart — go ahead and restart.

Performance scenarios use Level Sequences to drive a deterministic camera path through your scene. This ensures you're testing the same visual workload every time.

In the editor, go to Cinematics → Add Level Sequence, then add a CineCamera Actor and keyframe a path that covers the heaviest areas of your map.

Right-click in the Content Browser and select PerfGuard → Performance Scenario. This creates a new UPerfScenario data asset that tells PerfGuard what map to load, which sequence to play, and which stats to capture.

Open your new PerfScenario asset and fill in the core properties:

• Map — the level to load for this test
• Level Sequence — the camera flythrough you created
• Tracked Stats — which CSV profiler columns to monitor (FrameTime, GPUTime, DrawCalls, etc.)
• Warmup Frames — frames to skip at the start (shader compilation, asset streaming)

PerfGuard's analysis tooling runs as a Python CLI. You need Python 3.11 or later.

cd Plugins/PerfGuard/Tools
python3 -m pip install -r requirements.txt

# Verify the CLI is working
python3 perfguard_cli.py --help

cd Plugins\PerfGuard\Tools
python -m pip install -r requirements.txt

:: Verify the CLI is working
python perfguard_cli.py --help

Launch the engine in headless game mode with the Gauntlet controller. This loads your scenario, plays the sequence, captures CSV profiler data, and exits automatically.

UnrealEditor YourProject.uproject \
    -game \
    -gauntlet=PerfGuardGauntletController \
    -scenario=MyScenario \
    -csvprofile \
    -RenderOffScreen \
    -unattended \
    -log

UnrealEditor-Cmd.exe YourProject.uproject ^
    -game ^
    -gauntlet=PerfGuardGauntletController ^
    -scenario=MyScenario ^
    -csvprofile ^
    -unattended ^
    -log

The CSV output lands in Saved/Profiling/CSV/. The controller logs progress under the LogPerfGuard category.

Once you have CSV data from a known-good build, record it as your baseline. This is the reference point all future runs will be compared against.

python3 perfguard_cli.py baseline record MyScenario \
    --csv Saved/Profiling/CSV/Profile_2026.01.15-10.30.00.csv \
    --platform Win64 \
    --warmup 60

python perfguard_cli.py baseline record MyScenario ^
    --csv Saved\Profiling\CSV\Profile_2026.01.15-10.30.00.csv ^
    --platform Win64 ^
    --warmup 60

This parses the CSV, trims warmup frames, removes outliers, and saves a .json baseline file to the baselines directory.

After making code or content changes, run the scenario again and compare the new CSV against your recorded baseline.

python3 perfguard_cli.py baseline compare MyScenario \
    --csv Saved/Profiling/CSV/Profile_2026.01.16-14.22.00.csv \
    --threshold-percent 5.0 \
    --budget 60fps

python perfguard_cli.py baseline compare MyScenario ^
    --csv Saved\Profiling\CSV\Profile_2026.01.16-14.22.00.csv ^
    --threshold-percent 5.0 ^
    --budget 60fps

The CLI exits with code 0 if all stats are within threshold, or 1 if any regression is detected. This exit code is what CI pipelines use for pass/fail gating.

Generate a self-contained HTML report with charts, tables, and diagnostics that you can share with your team or attach to a pull request.

python3 perfguard_cli.py report results/ \
    --output report.html

python perfguard_cli.py report results\ ^
    --output report.html

Open report.html in any browser. The report is fully self-contained with no external dependencies — Chart.js is embedded inline.