10-Minute Quick Start

Persist an actor's state in three simple steps. No base class to inherit from, no mandatory interfaces, and no macros altering your class declarations.

---

1. Add the Persistence Component

Attach UAegisPersistenceComponent to any Actor in your game. That single component turns an ordinary actor into a persistent entity tracked by the Aegis subsystem.

Blueprint

1. Open your Actor Blueprint (e.g., BP_TreasureChest or BP_PlayerCharacter).
2. In the Components panel, click "+ Add".
3. Search for "Aegis Persistence" and select it.
4. Leave the default component settings (Scope = World, Persist Transform = True).

C++

// YourActor.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Identity/AegisPersistenceComponent.h"
#include "YourActor.generated.h"

UCLASS()
class YOURGAME_API AYourActor : public AActor
{
    GENERATED_BODY()

public:
    AYourActor();

protected:
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Persistence")
    TObjectPtr<UAegisPersistenceComponent> Persistence;
};

// YourActor.cpp
#include "YourActor.h"

AYourActor::AYourActor()
{
    PrimaryActorTick.bCanEverTick = true;

    // Attach the Aegis Persistence Component
    Persistence = CreateDefaultSubobject<UAegisPersistenceComponent>(TEXT("Persistence"));
}

---

2. Mark What to Save

Aegis saves properties marked with Unreal's native SaveGame specifier. You do not need to create custom data structs or pack binary buffers manually.

Blueprint

1. Select the variable in your My Blueprint panel (e.g., CurrentHealth, bIsChestOpened).
2. In the Details panel on the right, expand "Advanced" under the variable settings.
3. Check the "SaveGame" checkbox.
4. Recompile and save the Blueprint.

C++

// In YourActor.h:
UPROPERTY(EditAnywhere, BlueprintReadWrite, SaveGame, Category = "Gameplay")
int32 CurrentHealth = 100;

UPROPERTY(EditAnywhere, BlueprintReadWrite, SaveGame, Category = "Gameplay")
bool bIsChestOpened = false;

UPROPERTY(EditAnywhere, BlueprintReadWrite, SaveGame, Category = "Gameplay")
TArray<FString> InventoryItems;

What Gets Persisted Automatically?

When an actor has UAegisPersistenceComponent:

• All variables marked with SaveGame (primitives, structs, arrays, maps, object references).
• The Actor Transform (Location, Rotation, Scale) — enabled by default via bPersistTransform.
• Actor Attachment (if attached to another persistent actor).

---

3. Save and Load World State

In Blueprints

Aegis provides asynchronous latent action nodes under the Aegis | Slots category. These nodes execute asynchronously and notify you via execution pins when done:

               ┌──────────────────────────────────────────────┐
               │              Auto Save (Aegis)               │
               ├──────────────────────────────────────────────┤
  [Exec In] ──►│ In Exec                                      │
               │                                   OnSuccess ─┼──► [Play Audio: "Chime"]
 "SaveSlot01" ─┼─► Slot Name                        OnFailed  ─┼──► [Log: "Save Failed!"]
               │                                      Status ─┼──► [Break FAegisStatus]
               │ Options (Optional)                           │
               └──────────────────────────────────────────────┘

• Auto Save: Recommended for gameplay checkpoints and rolling autosaves. Automatically runs in Incremental mode under a 1.0 ms frame budget without hitching.
• Save Game: Performs a synchronous point-in-time snapshot (Atomic mode). Recommended for manual save slots triggered from pause menus.
• Load Game: Reads the slot, restores all persistent actor states, and cleans up actors that were destroyed in that save.

In C++

Access the world subsystem via UAegisSubsystem::Get(WorldContextObject):

#include "Core/AegisSubsystem.h"

// 1. Trigger an asynchronous Autosave (Incremental Mode under 1.0 ms budget)
UAegisSubsystem* Aegis = UAegisSubsystem::Get(this);
if (Aegis)
{
    Aegis->AutoSave(TEXT("SaveSlot01"));
}

// 2. Trigger an explicit Manual Save
Aegis->SaveGame(TEXT("SaveSlot01"));

// 3. Load a Save Slot
Aegis->LoadGame(TEXT("SaveSlot01"));

To receive global save/load notifications in C++, bind to the subsystem delegates:

Aegis->OnSaveCompleted.AddDynamic(this, &AMyGameMode::HandleSaveCompleted);
Aegis->OnLoadCompleted.AddDynamic(this, &AMyGameMode::HandleLoadCompleted);

---

4. Lifecycle: Distinguishing a Load from Gameplay Death

When a saved game is loaded, Aegis destroys any placed actors that were recorded as destroyed in that save. This triggers AActor::EndPlay(EEndPlayReason::Destroyed) just like normal gameplay death.

If your actor spawns death effects, plays death screams, or drops loot in EndPlay, check WasDestroyedByLoad to prevent duplicate effects on load:

Blueprint

[Event End Play]
       │
       ▼
[Was Destroyed By Load (Aegis)]
       │
       ▼
   [Branch]
   ├── True  ──► (Do nothing; actor was cleaned up by save load)
   └── False ──► [Spawn Loot Item] ──► [Play Death Particles]

C++

void AYourActor::EndPlay(const EEndPlayReason::Type EndPlayReason)
{
    Super::EndPlay(EndPlayReason);

    UAegisSubsystem* Aegis = UAegisSubsystem::Get(this);
    if (Aegis && Aegis->WasDestroyedByLoad(this))
    {
        // Destroyed because a loaded save says this actor was already killed.
        // Skip death animations, score rewards, and loot drops!
        return;
    }

    // Normal gameplay destruction: drop loot and play death FX
    DropLoot();
}

---

Summary Checklist

• [x] Added UAegisPersistenceComponent to the actor.
• [x] Ticked SaveGame on variables that need to persist.
• [x] Triggered saves using Auto Save (for hitch-free autosaves) or Save Game (for manual saves).
• [x] Guarded loot/death logic using WasDestroyedByLoad.

That's it! Your actor now survives level transitions, streaming cell unloads, and save/load cycles.

---

Where to Go Next

• The First-Save Characteristic — Understand how initial slot writes differ from subsequent incremental autosaves.
• Interactive Loot Chest Recipe — See a full, production-ready interactive container built step-by-step.
• Making Saves Cheap — Learn how to turn 10,000-actor checks into sub-millisecond skips using GetAegisStateRevision.