Custom Gauntlet Controllers in Packaged Builds

Captures run through a Gauntlet controller, UPerfGuardGauntletController, which drives the load-map to warmup to capture to finish state machine. The stock controller handles almost every project, so reach for a subclass only when you need launch-time setup that has to happen before the scenario map loads — for example creating a savegame, signing into an online backend, or putting the game into a particular state.

The base class exposes its lifecycle phases as virtual and its state as protected, so you override one phase without reimplementing the rest. For one-time launch setup, override OnControllerStartup(), which runs exactly once when the engine is ready, before the startup delay and before the map loads.

The natural move is to drop the subclass into your main game module. That compiles in the editor and in Development, then fails the moment you build Shipping. Here is why.

UPerfGuardGauntletController lives in PerfGuard's PerfGuardTests module, which is typed DeveloperTool. Unreal includes DeveloperTool modules in Editor, DebugGame, and Development builds, and excludes them from Test and Shipping — the Gauntlet harness is test infrastructure and should never ship inside a retail game. Your game (runtime) module is compiled for Shipping, so if it references the controller it has to depend on a module that is not there. What happens next depends on how PerfGuard is installed:

• Installed to the engine (precompiled): there is no Shipping binary for PerfGuardTests, so the link fails with "UPerfGuardGauntletController is not available in Shipping". This is the error most people hit.
• Compiled from source in your project: it does build, but it force-compiles the entire test harness into your shipping executable, which you do not want.

Put the subclass in its own module and type that module DeveloperTool. Unreal then includes it exactly where the base class exists and drops it from Test and Shipping as a unit:

Source/
  MyGame/                  Type: Runtime       (your existing game module)
  MyGameGauntlet/          Type: DeveloperTool  (new)
    MyGameGauntlet.Build.cs
    Private/MyGameGauntletModule.cpp
    Private/MyPerfController.cpp
    Public/MyPerfController.h

The module's .Build.cs depends on PerfGuardRuntime (scenario types), PerfGuardTests (the controller base class), and Gauntlet:

using UnrealBuildTool;

public class MyGameGauntlet : ModuleRules
{
    public MyGameGauntlet(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        PublicDependencyModuleNames.AddRange(new string[]
        {
            "Core", "CoreUObject", "Engine",
            "PerfGuardRuntime",   // scenario types
            "PerfGuardTests",     // UPerfGuardGauntletController base class
            "Gauntlet"            // UGauntletTestController
        });
    }
}

A one-line module bootstrap:

#include "Modules/ModuleManager.h"

IMPLEMENT_MODULE(FDefaultModuleImpl, MyGameGauntlet);

And the controller subclass itself:

#pragma once
#include "CoreMinimal.h"
#include "PerfGuardGauntletController.h"
#include "MyPerfController.generated.h"

UCLASS()
class UMyPerfController : public UPerfGuardGauntletController
{
    GENERATED_BODY()
protected:
    // Called once when the engine is ready, before the startup delay and map load.
    virtual void OnControllerStartup() override;
};

#include "MyPerfController.h"

void UMyPerfController::OnControllerStartup()
{
    Super::OnControllerStartup();
    // Launch-time setup: create a savegame, sign in, configure game state.
}

Add the module to your .uproject with "Type": "DeveloperTool", so it follows the same include and exclude rules as PerfGuardTests:

"Modules": [
    { "Name": "MyGame",         "Type": "Runtime",       "LoadingPhase": "Default" },
    { "Name": "MyGameGauntlet", "Type": "DeveloperTool", "LoadingPhase": "Default" }
]

Select the controller by class name, without the leading U (Gauntlet maps -gauntlet=<Name> to the U-prefixed class). Any of three places works:

• Project Settings: Plugins > PerfGuard > Gauntlet > Gauntlet Controller Class.
• CLI: --controller MyPerfController on run / run-scenario.
• suite.json: "controller": "MyPerfController".

perfguard run-scenario DemoScene --project ./MyGame.uproject \
    --controller MyPerfController

{
  "scenarios": [ { "name": "DemoScene" } ],
  "controller": "MyPerfController"
}

With the subclass in a DeveloperTool module, the project compiles in every configuration the engine supports. The controller itself is present only where developer tools are enabled:

Because the controller is present in Editor, DebugGame, and Development, you have two paths that work on a stock engine for QA and CI:

• The editor in game mode — UnrealEditor MyGame.uproject -game -gauntlet=MyPerfController .... This is exactly what perfguard run-scenario and the editor's "Run Standalone" button launch. Developer tools are always on in an editor target, and a build machine can drive it headlessly.
• A packaged Development build — it includes the controller with no target-rules changes, and is much closer to retail performance than the editor.

For the same guidance in the plugin's shipped documentation, see Docs/ScenarioAuthoring.md — "Packaging the controller for all build configurations".