Ue Game Features

UE Game Features and Modular Gameplay

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

Game Features (Beta in 5.8) packages gameplay as self-contained plugins under Plugins/GameFeatures/. UGameFeaturesSubsystem (a UEngineSubsystem) drives each plugin through a state machine; a UGameFeatureData primary data asset inside the plugin holds an instanced list of UGameFeatureAction objects that run at registration, load, activation and deactivation. Modular Gameplay (Beta in 5.8) supplies UGameFrameworkComponentManager (a UGameInstanceSubsystem) that injects components into opted-in actors, plus the UGameFrameworkComponent bases and the init-state system that orders initialization across independently loaded features. Build.cs modules: GameFeatures and ModularGameplay. The GameFeatures module already depends publicly on ModularGameplay and DataRegistry, so code that only consumes actions needs GameFeatures alone.

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

Plugin Layout and Descriptor

A Game Feature plugin is an ordinary plugin that lives under <Project>/Plugins/GameFeatures/ or under <AdditionalPluginDirectory>/GameFeatures/. That location is what makes it a Game Feature plugin — UGameFeaturesSubsystemSettings::IsValidGameFeaturePlugin matches the descriptor path against those folders. There is no plugin-level "Type" key in the .uplugin schema.

Plugins/GameFeatures/
├── MyFeature/
│   ├── MyFeature.uplugin
│   ├── Content/MyFeature.uasset        (UGameFeatureData, named after the plugin)
│   └── Source/MyFeatureRuntime/
└── MyFeatureRules/
    ├── MyFeatureRules.uplugin
    └── Content/MyFeatureRules.uasset

{
	"FileVersion": 3,
	"Version": 1,
	"VersionName": "1.0",
	"FriendlyName": "My Feature",
	"Description": "Adds my gameplay feature",
	"Category": "Game Features",
	"CreatedBy": "",
	"CanContainContent": true,
	"ExplicitlyLoaded": true,
	"BuiltInInitialFeatureState": "Active",
	"Modules": [
		{ "Name": "MyFeatureRuntime", "Type": "Runtime", "LoadingPhase": "Default" }
	],
	"Plugins": [
		{ "Name": "GameFeatures", "Enabled": true },
		{ "Name": "ModularGameplay", "Enabled": true }
	]
}

A content-only feature plugin omits Modules entirely. Adding a module means adding a Build.cs; see ue-module-build-system.

UGameFeatureData

UGameFeatureData : UPrimaryDataAsset is the asset the subsystem loads for the plugin. Its two authored properties are protected; read them through accessors:

const TArray<UGameFeatureAction*>& FeatureActions = FeatureData->GetActions();
const TArray<FPrimaryAssetTypeInfo>& ScanTypes = FeatureData->GetPrimaryAssetTypesToScan();

Actions is an Instanced array of UGameFeatureAction subclasses created inline in the asset. PrimaryAssetTypesToScan tells the Asset Manager which primary asset types inside the plugin to scan when the feature registers; see ue-data-assets-tables.

Subclass UGameFeatureData only to change GetPrimaryAssetTypesToScan or, in the editor, GetDisallowedActions.

Plugin States and the Subsystem

Destination states are fully ordered; transition and error states sit between them. EGameFeaturePluginState is a plain enum generated from the GAME_FEATURE_PLUGIN_STATE_LIST macro.

Transition states that show up in logs and in GetPluginState results include CheckingStatus, Downloading, Mounting, Registering, Loading, ActivatingDependencies, Activating, Deactivating, Unloading, Unregistering, Unmounting, Releasing, Uninstalling, plus the matching Error* states.

Two other enums: EGameFeatureTargetState (Installed, Registered, Loaded, Active) is what you pass to ChangeGameFeatureTargetState; EBuiltInAutoState (Invalid, Installed, Registered, Loaded, Active) is what BuiltInInitialFeatureState parses into.

Driving a plugin from code

#include "GameFeaturesSubsystem.h"

void UMyFeatureManager::EnableMyFeature()
{
    UGameFeaturesSubsystem& GFS = UGameFeaturesSubsystem::Get();

    FString PluginURL;
    if (!GFS.GetPluginURLByName(TEXT("MyFeature"), PluginURL))
    {
        UE_LOG(LogMyGame, Error, TEXT("MyFeature is not a discovered game feature plugin"));
        return;
    }

    GFS.LoadAndActivateGameFeaturePlugin(PluginURL,
        FGameFeaturePluginLoadComplete::CreateUObject(this, &UMyFeatureManager::HandleFeatureLoaded));
}

void UMyFeatureManager::HandleFeatureLoaded(const UE::GameFeatures::FResult& Result)
{
    if (Result.HasError())
    {
        UE_LOG(LogMyGame, Error, TEXT("MyFeature failed: %s"), *Result.GetError());
    }
}

GetPluginURLByName(FStringView PluginName, FString& OutPluginURL) is the safe way to build a URL for a built-in plugin. The static builders UGameFeaturesSubsystem::GetPluginURL_FileProtocol(PluginDescriptorPath) and GetPluginURL_InstallBundleProtocol(PluginName, BundleName) produce file: and installbundle: URLs (EGameFeaturePluginProtocol::File, ::InstallBundle).

Every completion delegate above is an alias of FGameFeaturePluginChangeStateComplete, i.e. DECLARE_DELEGATE_OneParam(..., const UE::GameFeatures::FResult&). Overloads taking TConstArrayView<FString> PluginURLs report through FMultipleGameFeaturePluginsLoaded, a TDelegate<void(const TMap<FString, UE::GameFeatures::FResult>&)>.

Queries: GetPluginState(URL), IsGameFeaturePluginActive(URL, bCheckForActivating), IsGameFeaturePluginActiveByName(PluginName, bCheckForActivating), IsGameFeaturePluginRegistered(URL, bCheckForRegistering), IsGameFeaturePluginLoaded(URL), IsGameFeaturePluginInErrorState(URL), GetActivePluginNames().

Console commands for testing (GameFeaturesSubsystem.cpp:583-661, take a plugin name or URL): ListGameFeaturePlugins [-activeonly] [-csv], LoadGameFeaturePlugin, DeactivateGameFeaturePlugin, UnloadGameFeaturePlugin, ReleaseGameFeaturePlugin, CancelGameFeaturePlugin, TerminateGameFeaturePlugin. The LoadGameFeaturePlugin console command calls LoadAndActivateGameFeaturePlugin and is ECVF_Cheat, unlike the C++ function of the same name, which only reaches Loaded.

Writing a UGameFeatureAction

UGameFeatureAction is UCLASS(MinimalAPI, DefaultToInstanced, EditInlineNew, Abstract) deriving from UObject. DefaultToInstanced and EditInlineNew are what let instances be created inline in the Actions array. The overridable virtuals, verbatim:

virtual void OnGameFeatureRegistering() {}
virtual void OnGameFeatureUnregistering() {}
virtual void OnGameFeatureLoading() {}
virtual void OnGameFeatureUnloading() {}
virtual void OnGameFeatureActivating(FGameFeatureActivatingContext& Context);
virtual void OnGameFeatureActivating() {}
virtual void OnGameFeatureActivated() {}
virtual void OnGameFeatureDeactivating(FGameFeatureDeactivatingContext& Context) {}

Override the context version of OnGameFeatureActivating; the base implementation of that one calls the no-arg version, so overriding both runs your code twice. IsDataValid is a UObject override, not a UGameFeatureAction member, and is editor-only.

// MyGameFeatureAction_GrantTag.h
#pragma once

#include "GameFeatureAction.h"
#include "GameplayTagContainer.h"
#include "MyGameFeatureAction_GrantTag.generated.h"

struct FGameFeatureActivatingContext;
struct FGameFeatureDeactivatingContext;
struct FWorldContext;

UCLASS(meta = (DisplayName = "My Grant Tag"))
class MYGAME_API UMyGameFeatureAction_GrantTag : public UGameFeatureAction
{
    GENERATED_BODY()

public:
    virtual void OnGameFeatureActivating(FGameFeatureActivatingContext& Context) override;
    virtual void OnGameFeatureDeactivating(FGameFeatureDeactivatingContext& Context) override;

#if WITH_EDITOR
    virtual EDataValidationResult IsDataValid(class FDataValidationContext& Context) const override;
#endif

    UPROPERTY(EditAnywhere, Category = "Tags")
    FGameplayTag TagToGrant;

private:
    void ApplyToWorld(const FWorldContext& WorldContext);
};

An action instance is shared by every world the feature applies to, so never keep per-world state in a bare member. Filter worlds with the context and key state by FObjectKey:

void UMyGameFeatureAction_GrantTag::OnGameFeatureActivating(FGameFeatureActivatingContext& Context)
{
    for (const FWorldContext& WorldContext : GEngine->GetWorldContexts())
    {
        if (Context.ShouldApplyToWorldContext(WorldContext))
        {
            ApplyToWorld(WorldContext);
        }
    }
}

FGameFeatureActivatingContext and FGameFeatureDeactivatingContext both derive from FGameFeatureStateChangeContext, which supplies ShouldApplyToWorldContext(const FWorldContext&), ShouldApplyUsingOtherContext(const FGameFeatureStateChangeContext&) and SetRequiredWorldContextHandle(FName).

Deactivation that needs async work must hold the state machine open. FGameFeatureDeactivatingContext::PauseDeactivationUntilComplete(FString InPauserTag) returns an FSimpleDelegate you must execute on the game thread, on every path:

void UMyGameFeatureAction_GrantTag::OnGameFeatureDeactivating(FGameFeatureDeactivatingContext& Context)
{
    FSimpleDelegate Resume = Context.PauseDeactivationUntilComplete(TEXT("MyGrantTag_Cleanup"));
    StartAsyncCleanup(Resume);   // must call Resume.ExecuteIfBound() when finished
}

Full templates, including world tracking and the RAII handle patterns, are in references/game-feature-patterns.md.

Engine-Provided Actions

UGameFeatureAction_AddComponents is the one most features need. It holds TArray<FGameFeatureComponentEntry> ComponentList, and each FGameFeatureComponentEntry carries TSoftClassPtr<AActor> ActorClass (meta=(AllowAbstract="True")), TSoftClassPtr<UActorComponent> ComponentClass, the bitfields uint8 bClientComponent:1 and uint8 bServerComponent:1, and uint8 AdditionFlags (meta=(Bitmask, BitmaskEnum="/Script/ModularGameplay.EGameFrameworkAddComponentFlags")).

Set both bClientComponent and bServerComponent for components needed everywhere, server-only for authoritative gameplay logic, client-only for cosmetics. The action keeps a TSharedPtr<FComponentRequestHandle> per game instance and drops them on deactivation, which removes the injected components.

Component Injection

UGameFrameworkComponentManager is a UGameInstanceSubsystem. Get it from an actor:

#include "Components/GameFrameworkComponentManager.h"

UGameFrameworkComponentManager* CompMgr = UGameFrameworkComponentManager::GetForActor(MyActor);

GetForActor(const AActor* Actor, bool bOnlyGameWorlds = true) returns null outside game worlds. GetGameInstance()->GetSubsystem<UGameFrameworkComponentManager>() also works where a game instance is in hand.

Receivers

An actor receives injected components only after it registers itself:

void AMyCharacter::BeginPlay()
{
    Super::BeginPlay();
    UGameFrameworkComponentManager::AddGameFrameworkComponentReceiver(this);
}

void AMyCharacter::EndPlay(const EEndPlayReason::Type EndPlayReason)
{
    UGameFrameworkComponentManager::RemoveGameFrameworkComponentReceiver(this);
    Super::EndPlay(EndPlayReason);
}

The static helpers resolve the manager for the actor and forward to AddReceiver(AActor* Receiver, bool bAddOnlyInGameWorlds = true) and RemoveReceiver(AActor* Receiver), which you can also call directly on the manager.

Requests and extension handlers

TSharedPtr<FComponentRequestHandle> RequestHandle = CompMgr->AddComponentRequest(
    TSoftClassPtr<AActor>(AMyCharacter::StaticClass()),
    UMyHealthComponent::StaticClass(),
    EGameFrameworkAddComponentFlags::AddUnique);

FComponentRequestHandle is RAII: keep it alive for as long as the injection should last, and destroy it to remove the request and the components it created. It also exposes IsValid(), which returns false once the owning manager is gone.

Extension handlers observe receivers instead of adding components. The delegate is declared inside the manager as DECLARE_DELEGATE_TwoParams(FExtensionHandlerDelegate, AActor*, FName):

ExtensionHandle = CompMgr->AddExtensionHandler(
    TSoftClassPtr<AActor>(AMyCharacter::StaticClass()),
    UGameFrameworkComponentManager::FExtensionHandlerDelegate::CreateUObject(
        this, &UMyFeatureManager::HandleActorExtension));

void UMyFeatureManager::HandleActorExtension(AActor* Actor, FName EventName)
{
    if (EventName == UGameFrameworkComponentManager::NAME_GameActorReady)
    {
        // Actor has finished its default initialization
    }
}

The five static FName event constants are NAME_ReceiverAdded, NAME_ReceiverRemoved, NAME_ExtensionAdded, NAME_ExtensionRemoved and NAME_GameActorReady. Send your own with CompMgr->SendExtensionEvent(Receiver, EventName, bOnlyInGameWorlds) or the static UGameFrameworkComponentManager::SendGameFrameworkComponentExtensionEvent(Receiver, EventName, bOnlyInGameWorlds).