C++ API Reference

This document provides a comprehensive C++ reference for the Aegis Save runtime module.

---

1. Project Setup & Module Dependencies

To use Aegis Save in C++, add the runtime module to your game module's Build.cs file:

// YourGame.Build.cs
using UnrealBuildTool;

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

        PublicDependencyModuleNames.AddRange(new string[] {
            "Core",
            "CoreUObject",
            "Engine",
            "AegisSave" // <-- Add AegisSave runtime module
        });
    }
}

---

2. Core Class: UAegisSubsystem

The primary access point for saving, loading, and identity management. Located in #include "Core/AegisSubsystem.h".

Static Accessor

static UAegisSubsystem* UAegisSubsystem::Get(const UObject* WorldContextObject);

Save Operations

// Triggers an incremental autosave under FrameBudgetMilliseconds (default 1.0 ms)
void AutoSave(const FString& SlotName, const FAegisSaveOptions& Options = FAegisSaveOptions());

// Triggers an atomic synchronous save (full point-in-time world snapshot)
void SaveGame(const FString& SlotName, const FAegisSaveOptions& Options = FAegisSaveOptions());

Load Operations

// Loads a save slot and restores world state
void LoadGame(const FString& SlotName, const FAegisLoadOptions& Options = FAegisLoadOptions());

Slot Management

bool DoesSlotExist(const FString& SlotName) const;
FAegisStatus GetSlotInfo(const FString& SlotName, FAegisSlotInfo& OutInfo) const;
FAegisStatus GetAllSlotInfo(TArray<FAegisSlotInfo>& OutSlots) const;
FAegisStatus DeleteSlot(const FString& SlotName);

Object Registration & Lifecycle

// Plain object persistence (for non-actors)
FAegisStatus RegisterPersistentObject(UObject* Object, const FGuid& Identity, EAegisScope Scope = EAegisScope::World);
FAegisStatus UnregisterPersistentObject(UObject* Object);
FAegisStatus ForgetRecord(const FGuid& Identity);

// Deterministic string-to-GUID derivation
FGuid MakePersistentIdFromLabel(const FString& Label) const;

// Spawning
template<typename T>
T* SpawnPersistentActor(UClass* Class, const FTransform& Transform, ESpawnActorCollisionHandlingMethod CollisionHandling = ESpawnActorCollisionHandlingMethod::AlwaysSpawn);

// Lifecycle check in EndPlay
bool WasDestroyedByLoad(const AActor* Actor) const;

// Explicit change marking
void MarkChanged(UObject* Object);

Subsystem Delegates

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FAegisSaveStartedSignature, const FString&, SlotName);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FAegisSaveCompletedSignature, const FString&, SlotName, const FAegisStatus&, Status);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FAegisLoadStartedSignature, const FString&, SlotName);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FAegisLoadCompletedSignature, const FString&, SlotName, const FAegisStatus&, Status);

UPROPERTY(BlueprintAssignable)
FAegisSaveStartedSignature OnSaveStarted;

UPROPERTY(BlueprintAssignable)
FAegisSaveCompletedSignature OnSaveCompleted;

UPROPERTY(BlueprintAssignable)
FAegisLoadStartedSignature OnLoadStarted;

UPROPERTY(BlueprintAssignable)
FAegisLoadCompletedSignature OnLoadCompleted;

---

3. Component: UAegisPersistenceComponent

Located in #include "Identity/AegisPersistenceComponent.h".

UCLASS(ClassGroup=(Save), meta=(BlueprintSpawnableComponent))
class AEGIS_API UAegisPersistenceComponent : public UActorComponent
{
    GENERATED_BODY()

public:
    UAegisPersistenceComponent();

    // Identity queries
    FGuid GetPersistentId() const;
    bool HasValidId() const;

    // Scope configuration
    EAegisScope GetScope() const;
    void SetScope(EAegisScope NewScope);

    // Transform persistence
    bool ShouldPersistTransform() const;
    void SetShouldPersistTransform(bool bInPersistTransform);

    // Change detection mode
    EAegisChangeDetection GetChangeDetection() const;
    void SetChangeDetection(EAegisChangeDetection NewMode);

    // Explicit dirty marking
    void MarkChanged();

    // Runtime spawn designation (R-12 bloat prevention)
    bool IsRuntimeSpawned() const;
    void SetIsRuntimeSpawned(bool bInRuntimeSpawned);
};

---

4. Interface: IAegisPersistenceEvents

Located in #include "Identity/AegisPersistenceEvents.h". Implement this interface on actors or objects to receive persistence callbacks or supply revision counters:

UINTERFACE(MinimalAPI, Blueprintable)
class UAegisPersistenceEvents : public UInterface
{
    GENERATED_BODY()
};

class AEGIS_API IAegisPersistenceEvents
{
    GENERATED_BODY()

public:
    /** Returns state revision counter for sub-millisecond change detection */
    UFUNCTION(BlueprintNativeEvent, Category = "Aegis")
    int32 GetAegisStateRevision() const;

    /** Fired immediately before this actor's properties are captured */
    UFUNCTION(BlueprintNativeEvent, Category = "Aegis")
    void OnBeforeAegisSave();

    /** Fired after this actor has been captured to the record store */
    UFUNCTION(BlueprintNativeEvent, Category = "Aegis")
    void OnAfterAegisSave();

    /** Fired before properties are restored from a loaded save */
    UFUNCTION(BlueprintNativeEvent, Category = "Aegis")
    void OnBeforeAegisLoad();

    /** Fired after all properties have been restored (ideal for rebuilding derived state) */
    UFUNCTION(BlueprintNativeEvent, Category = "Aegis")
    void OnAfterAegisLoad();
};

---

5. Structs & Enums

FAegisStatus

USTRUCT(BlueprintType)
struct AEGIS_API FAegisStatus
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadOnly)
    EAegisResult Result = EAegisResult::Success;

    UPROPERTY(BlueprintReadOnly)
    FString Context;

    bool IsSuccess() const { return Result == EAegisResult::Success; }
    FString ToString() const;
};

EAegisScope

UENUM(BlueprintType)
enum class EAegisScope : uint8
{
    World,   // Placed actors and level state (cleared on map change)
    Player,  // Character inventory and stats (survives map change)
    Global   // Slot-wide metadata and account unlocks
};

EAegisChangeDetection

UENUM(BlueprintType)
enum class EAegisChangeDetection : uint8
{
    Automatic, // Reads GetAegisStateRevision; walks if unhandled (Conservative default)
    Revision,  // Skips walk if GetAegisStateRevision matches; warns if unhandled
    Manual,    // Only walks if MarkChanged was called
    Always     // Always walks on every save pass
};

EAegisSnapshotMode

UENUM(BlueprintType)
enum class EAegisSnapshotMode : uint8
{
    Atomic,      // Synchronous point-in-time capture
    Incremental  // Sliced across frames under FrameBudgetMilliseconds
};