C++ API

Taken from the shipped public headers. Every symbol below exists in the plugin source; nothing is paraphrased into a name that does not compile.

Modules and headers

Module	Type	Public headers
WorldStateResetFrameworkRuntime	Runtime	WSRFTypes.h, WSRFStateComponent.h, WSRFWorldStateSubsystem.h, WSRFResettable.h, WSRFStateWriter.h, WSRFStateReader.h, WSRFPersistenceTypes.h, WSRFSnapshotMigrator.h, WSRFWorldManifest.h, WSRFGameplayTags.h, WorldStateResetFrameworkRuntime.h
WorldStateResetFrameworkDemo	Runtime	WSRFDemoActors.h, WorldStateResetFrameworkDemo.h
WorldStateResetFrameworkEditor	Editor	WSRFWorldStateInspector.h, WSRFEditorValidation.h, WSRFWorldManifestBuilder.h, WorldStateResetFrameworkEditor.h

The export macros are WORLDSTATERESETFRAMEWORKRUNTIME_API, WORLDSTATERESETFRAMEWORKDEMO_API and WORLDSTATERESETFRAMEWORKEDITOR_API.

Identity types

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFActorId
{
    FGuid Guid;

    bool IsValid() const;
    FString ToString() const;
};

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFContainerIdentity
{
    FGuid ContextGuid;              // invalid for the main world
    FName SourceLevelPackage = NAME_None;
    FName RuntimeLevelPackage = NAME_None;
    FName ContainerLabel = NAME_None;
    TArray<FName> DataLayers;

    bool IsMainContainer() const;
    FString ToString() const;
};

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFEffectiveActorId
{
    FWSRFActorId LocalId;
    FGuid ContainerGuid;

    bool IsValid() const;
    FGuid ToGuid() const;
    FString ToString() const;
};

Policy and request types

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFResetPolicy
{
    FGameplayTagContainer ResetTriggers;
    EWSRFPersistenceMode PersistenceMode = EWSRFPersistenceMode::Resettable;
    EWSRFRestoreStrategy RestoreStrategy = EWSRFRestoreStrategy::AutomaticThenInterface;
    EWSRFRuntimeActorBehavior RuntimeActorBehavior = EWSRFRuntimeActorBehavior::RemoveOnMatchingReset;
};

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFRegistrationOptions
{
    FWSRFActorId RequestedId;
    FGameplayTagContainer Regions;
    FWSRFResetPolicy Policy;
    EWSRFActorOrigin Origin = EWSRFActorOrigin::Auto;
    int32 ResetPriority = 0;
    bool bAllowTransientId = true;
};

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFResetRequest
{
    FGameplayTag Reason;
    FGameplayTag Region;
    TObjectPtr<UObject> Initiator = nullptr;
    FName Context = NAME_None;
    bool bIncludeChildRegions = true;
    FGuid ContainerContext;         // advanced: restrict to one container
};

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFResetReport
{
    FGuid OperationId;
    bool bWasQueued = false;        // the request entered the FIFO instead of executing immediately
    bool bWasExecuted = false;      // true only on the completed execution, not the queued placeholder
    int32 Scheduled = 0;
    int32 Restored = 0;
    int32 Respawned = 0;
    int32 Removed = 0;
    int32 Skipped = 0;
    int32 PendingRestore = 0;
    int32 Failed = 0;
    double DurationMilliseconds = 0.0;
    TArray<FString> Errors;

    bool WasSuccessful() const;     // bWasExecuted && Failed == 0
};

UWSRFWorldStateSubsystem

UCLASS()
class WORLDSTATERESETFRAMEWORKRUNTIME_API UWSRFWorldStateSubsystem : public UWorldSubsystem
{
public:
    FWSRFRegistrationResult RegisterActor(AActor* Actor, const FWSRFRegistrationOptions& Options);
    bool UnregisterActor(AActor* Actor, bool bForgetSnapshot = true);
    bool RecaptureInitialState(AActor* Actor);

    FWSRFResetReport RequestReset(const FWSRFResetRequest& Request);
    FWSRFResetReport ResetWorldRegion(FGameplayTag Region, FGameplayTag Reason,
        UObject* Initiator = nullptr, bool bIncludeChildRegions = true);
    FWSRFResetReport ResetWorldRegionInContext(FGameplayTag Region, FGameplayTag Reason,
        const AActor* ContextActor, UObject* Initiator = nullptr, bool bIncludeChildRegions = true);

    FWSRFPersistenceExportReport CapturePersistentWorldState(FWSRFWorldStateSnapshot& Snapshot,
        bool bMeasureSerializedSize = false);
    FWSRFPersistenceImportReport ApplyPersistentWorldState(const FWSRFWorldStateSnapshot& Snapshot);
    FWSRFPersistenceImportReport ApplyPersistentWorldStateWithMigrator(
        const FWSRFWorldStateSnapshot& Snapshot, UWSRFSnapshotMigrator* Migrator);

    bool IsActorRegistered(AActor* Actor) const;
    AActor* FindLoadedActor(FWSRFActorId ActorId) const;
    AActor* FindLoadedActorInContext(FWSRFActorId ActorId, const AActor* ContextActor) const;
    AActor* FindLoadedActorByEffectiveId(FWSRFEffectiveActorId EffectiveActorId) const;
    EWSRFActorPresence GetActorPresence(FWSRFActorId ActorId, bool& bFound) const;
    int32 GetRegisteredActorCount() const;

    int64 GetApproximateSnapshotMemoryBytes() const;
    int64 GetManifestMemoryBytes() const;
    int64 GetApproximatePersistentSnapshotMemoryBytes(const FWSRFWorldStateSnapshot& Snapshot) const;
    int64 GetApproximatePersistentSnapshotSerializedBytes(const FWSRFWorldStateSnapshot& Snapshot) const;
    EWSRFResetOperationState GetResetOperationState() const;

    // C++ only
    bool GetInitialState(FWSRFActorId ActorId, FWSRFActorState& OutState) const;
    void GetDiagnosticRecords(TArray<FWSRFActorDiagnosticRecord>& OutRecords) const;
    void GetKnownRegions(TArray<FGameplayTag>& OutRegions) const;
    void GetPredictedRestoreOrder(const TArray<FWSRFActorId>& ActorIds, TArray<FWSRFActorId>& OutOrder) const;
    const FWSRFResetReport& GetLastResetReport() const;
    const FWSRFPersistenceImportReport& GetLastPersistenceImportReport() const;
    int32 GetLastImportedSnapshotVersion() const;
    const UWSRFWorldManifest* GetLoadedManifest() const;
    FString GetManifestStatus() const;
    FWSRFContainerIdentity ResolveContainerIdentity(const AActor* Actor) const;
    FWSRFEffectiveActorId ResolveEffectiveActorId(const FWSRFActorId& LocalId, const AActor* Actor) const;
    void UpdateActorRegions(AActor* Actor, const FGameplayTagContainer& NewRegions);
};

Delegate types

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FWSRFResetStartedEvent, const FWSRFResetRequest&, Request);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FWSRFResetCompletedEvent, const FWSRFResetRequest&, Request, const FWSRFResetReport&, Report);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FWSRFActorResetEvent, FWSRFActorId, ActorId, const FWSRFResetRequest&, Request);

Members: OnWorldResetStarted, OnWorldResetCompleted, OnRegionResetStarted, OnRegionResetCompleted, OnActorResetStarted, OnActorResetCompleted.

UWSRFStateComponent

UCLASS(ClassGroup = (WSRF), meta = (BlueprintSpawnableComponent), BlueprintType)
class WORLDSTATERESETFRAMEWORKRUNTIME_API UWSRFStateComponent : public UActorComponent
{
public:
    FWSRFActorId GetStableId() const;
    bool IsRegisteredWithWSRF() const;
    bool RecaptureInitialState();
    void SetResetPolicy(const FWSRFResetPolicy& InPolicy);
    void SetRegionMembership(const FGameplayTagContainer& InRegions);
    void ApplyBehaviorPreset(EWSRFBehaviorPreset InPreset);

    const FGameplayTagContainer& GetRegionMembership() const;
    const FWSRFResetPolicy& GetResetPolicy() const;
    EWSRFActorOrigin GetConfiguredOrigin() const;
    int32 GetResetPriority() const;
    FWSRFRegistrationOptions BuildRegistrationOptions() const;

    FWSRFComponentResetEvent OnOwnerResetStarted;
    FWSRFComponentResetEvent OnOwnerResetCompleted;
};

IWSRFResettable

UINTERFACE(BlueprintType)
class WORLDSTATERESETFRAMEWORKRUNTIME_API UWSRFResettable : public UInterface { };

class WORLDSTATERESETFRAMEWORKRUNTIME_API IWSRFResettable
{
public:
    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "WSRF|Custom State")
    void WSRFCaptureCustomState(UWSRFStateWriter* Writer);

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "WSRF|Reset")
    void WSRFPrepareForReset(const FWSRFResetRequest& Request);

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "WSRF|Custom State")
    void WSRFRestoreCustomState(UWSRFStateReader* Reader);

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "WSRF|Reset")
    void WSRFResetCompleted(const FWSRFResetRequest& Request);
};

C++ implementations override the _Implementation variants: WSRFCaptureCustomState_Implementation, WSRFPrepareForReset_Implementation, WSRFRestoreCustomState_Implementation, WSRFResetCompleted_Implementation.

Persistence types

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFWorldStateSnapshot
{
    static constexpr int32 LegacySchemaVersion = 1;
    static constexpr int32 CurrentSchemaVersion = 3;

    int32 SchemaVersion = LegacySchemaVersion;
    FName WorldIdentity = NAME_None;
    FGuid ManifestBuildId;          // informational
    FString CapturedUtc;
    TArray<FWSRFPersistentActorState> Actors;
};

USTRUCT(BlueprintType)
struct WORLDSTATERESETFRAMEWORKRUNTIME_API FWSRFPersistentActorState
{
    FWSRFEffectiveActorId EffectiveActorId;
    FWSRFContainerIdentity ContainerIdentity;
    FGameplayTagContainer Regions;
    EWSRFPersistenceMode PersistenceMode = EWSRFPersistenceMode::Persistent;
    EWSRFActorPresence Presence = EWSRFActorPresence::Loaded;
    FWSRFActorState State;
    int64 ConfigurationHash = 0;
};

Both structures and every field are marked SaveGame, so they serialise inside your own USaveGame.

FWSRFPersistenceImportReport counts Applied, Deferred, Skipped, Missing, Failed, VersionMismatch and ConfigurationMismatch — the last one is diagnostic only: the saved configuration hash differs from the current Actor setup, and the state is still applied with the current settings.

Snapshot schema 3 is current. ApplyPersistentWorldState automatically chains the built-in schema-1 → 2 → 3 migrations; ApplyPersistentWorldStateWithMigrator stays strict and rejects an old snapshot as TooOld when no migrator is passed. UWSRFDefaultSnapshotMigrator exposes the same tested WSRF-owned chain so a project migrator can delegate to it.

Per-component-family state lives in dedicated structs — FWSRFSceneComponentState, FWSRFPrimitiveComponentState, FWSRFStaticMeshComponentState, FWSRFSkeletalMeshComponentState, FWSRFChildActorComponentState, FWSRFAudioComponentState — carried by FWSRFActorState with explicit section-presence metadata (CapturedSections). The capture contract per family is in Automatic component capture; the extension registry is in Extending capture.

UWSRFBlueprintLibrary

UCLASS()
class WORLDSTATERESETFRAMEWORKRUNTIME_API UWSRFBlueprintLibrary : public UBlueprintFunctionLibrary
{
public:
    /** DisplayName "Was WSRF Reset Successful": bWasExecuted && Failed == 0. */
    static bool WasResetSuccessful(const FWSRFResetReport& Report);

    /** Built-in plugin migration used automatically by normal imports and exposed
        for advanced Blueprint migrators. DisplayName "Migrate WSRF Snapshot v1 to v2". */
    static bool MigrateSnapshotV1ToV2(const FWSRFWorldStateSnapshot& Source,
        FWSRFWorldStateSnapshot& Migrated, FString& Message);
};

World manifest helpers

namespace WSRFManifest
{
    FGuid MakeStreamingContainerGuid(FName SourceLevelPackage, FName RuntimeLevelPackage);
    FWSRFContainerIdentity ResolveContainerIdentity(const UWorld* World, ULevel* Level);
    FWSRFContainerIdentity ResolveContainerIdentity(const AActor* Actor);
    FWSRFEffectiveActorId ResolveEffectiveActorId(const FWSRFActorId& LocalId, const AActor* Actor);
    uint32 ComputeConfigurationHash(
        const FWSRFActorId& LocalId,
        const UClass* ActorClass,
        const FWSRFContainerIdentity& ContainerIdentity,
        const FGameplayTagContainer& Regions,
        const FWSRFResetPolicy& Policy,
        EWSRFActorOrigin Origin,
        int32 ResetPriority);
}

Native gameplay tags

namespace WSRFGameplayTags
{
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Reset_Rest);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Reset_PlayerDeath);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Reset_Checkpoint);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Reset_Region);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Reset_EncounterRestart);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Reset_Manual);

    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Region_Default);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Region_DemoHall);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Region_Test_A);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Region_Test_B);
    UE_DECLARE_GAMEPLAY_TAG_EXTERN(Region_Test_Stress);
}

Editor-only services

Available to editor modules and automation only.

class WORLDSTATERESETFRAMEWORKEDITOR_API FWSRFWorldStateValidator
{
public:
    static FWSRFInspectorSnapshot BuildSnapshot(UWorld* World, bool bValidate = true);
    static void ValidateSnapshot(FWSRFInspectorSnapshot& Snapshot);
    static int32 AssignMissingIds(UWorld* World);
    static bool RegenerateId(UWSRFStateComponent* Component);
    static FString SeverityToString(EWSRFValidationSeverity Severity);
};

class WORLDSTATERESETFRAMEWORKEDITOR_API FWSRFWorldManifestBuilder
{
public:
    static FString GetDefaultManifestObjectPath(const UWorld* World);
    static FWSRFManifestBuildResult Build(UWorld* World, UWSRFWorldManifest*& OutManifest);
    static FWSRFManifestValidationResult Validate(UWorld* World, const UWSRFWorldManifest* Manifest);
    static UWSRFWorldManifest* FindAssignedManifest(UWorld* World);
};

SWSRFWorldStateInspector is the Slate widget behind the Inspector tab. It is editor UI, not a customer API.

Build integration

// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{
    "Core",
    "CoreUObject",
    "Engine",
    "GameplayTags",
    "WorldStateResetFrameworkRuntime"
});

Example: request a reset

#include "WSRFWorldStateSubsystem.h"
#include "WSRFGameplayTags.h"

void AMyCheckpoint::OnPlayerRested()
{
    if (UWSRFWorldStateSubsystem* Subsystem = GetWorld()->GetSubsystem<UWSRFWorldStateSubsystem>())
    {
        const FWSRFResetReport Report = Subsystem->ResetWorldRegion(
            WSRFGameplayTags::Region_Default,
            WSRFGameplayTags::Reset_Rest,
            this,
            /* bIncludeChildRegions */ true);

        UE_LOG(LogTemp, Log, TEXT("WSRF reset: %d restored, %d respawned, %d failed in %.3f ms"),
            Report.Restored, Report.Respawned, Report.Failed, Report.DurationMilliseconds);
    }
}

Example: register an Actor explicitly

#include "WSRFWorldStateSubsystem.h"

void AMySpawner::RegisterSpawned(AActor* Spawned)
{
    UWSRFWorldStateSubsystem* Subsystem = GetWorld()->GetSubsystem<UWSRFWorldStateSubsystem>();
    if (Subsystem == nullptr)
    {
        return;
    }

    FWSRFRegistrationOptions Options;
    Options.Regions.AddTag(WSRFGameplayTags::Region_Default);
    Options.Policy.ResetTriggers.AddTag(WSRFGameplayTags::Reset_Rest);
    Options.Policy.PersistenceMode = EWSRFPersistenceMode::Resettable;
    Options.Policy.RuntimeActorBehavior = EWSRFRuntimeActorBehavior::RemoveOnMatchingReset;
    Options.Origin = EWSRFActorOrigin::RuntimeSpawned;

    const FWSRFRegistrationResult Result = Subsystem->RegisterActor(Spawned, Options);
    if (!Result.bSuccess)
    {
        UE_LOG(LogTemp, Warning, TEXT("WSRF registration failed: %s"), *Result.Message);
    }
}

Example: custom state

void AMyTrap::WSRFCaptureCustomState_Implementation(UWSRFStateWriter* Writer)
{
    Writer->SetVersion(1);
    Writer->WriteBool(TEXT("bArmed"), bArmed);
    Writer->WriteInteger(TEXT("TriggerCount"), TriggerCount);
}

void AMyTrap::WSRFRestoreCustomState_Implementation(UWSRFStateReader* Reader)
{
    bool bRestoredArmed = true;
    if (Reader->ReadBool(TEXT("bArmed"), bRestoredArmed))
    {
        bArmed = bRestoredArmed;
    }

    int64 RestoredCount = 0;
    if (Reader->ReadInteger(TEXT("TriggerCount"), RestoredCount))
    {
        TriggerCount = static_cast<int32>(RestoredCount);
    }
}

Example: persistence

FWSRFWorldStateSnapshot Snapshot;
const FWSRFPersistenceExportReport Export = Subsystem->CapturePersistentWorldState(Snapshot);
// store Snapshot in your own USaveGame, then save it normally

const FWSRFPersistenceImportReport Import = Subsystem->ApplyPersistentWorldState(Snapshot);
if (Import.Compatibility != EWSRFSnapshotCompatibility::Compatible)
{
    UE_LOG(LogTemp, Warning, TEXT("WSRF snapshot rejected; %d records deferred, %d missing"),
        Import.Deferred, Import.Missing);
}