Complete Game Flow & Level Transitions

One of the most critical questions game developers face when integrating a save plugin is:
"How does saving and loading coordinate across the full game loop—from the Main Menu, to opening levels, to mid-game checkpoints, to player death?"

Because UAegisSubsystem is a UGameInstanceSubsystem, it lives continuously for the entire lifespan of your game application. The in-memory record store outlives individual UWorld instances. This architectural foundation means loading data works cleanly regardless of whether you load before opening a level, after opening a level, or mid-game in-place.

This masterclass guide walks through every phase of a complete game lifecycle.

1. The GameInstance Architectural Foundation

In standard Unreal Engine architecture, when you call UGameplayStatics::OpenLevel, the engine completely tears down the active UWorld and all resident actors. Any data stored purely on actors or World subsystems is wiped.

text

Game Lifecycle Timeline:
─────────────────────────────────────────────────────────────────────────────►
[UGameInstance]          ════════════════════════════════════════════════════
  └─► [UAegisSubsystem]  ════════════════════════════════════════════════════ (Persists!)
                               ▲                              ▲
[UWorld: MainMenu]       ──────┴──────► [UWorld: Level_Dungeon] ─────────────►
  (Destroyed on travel)                   (Spawned fresh)

Because UAegisSubsystem is a GameInstance Subsystem:

The In-Memory Record Store Persists: When you load a save file in the Main Menu, the deserialized records remain safely cached in memory across the map transition.
Pre-Tick Restoration (AC-303): As the new level opens, each persistent actor registers with Aegis during component initialization and restores its saved properties before its first gameplay tick. There is zero visual pop-in, no default pose blinking, and no frame-one race conditions.
In-Place Live Reloading: When loading inside an active level (e.g. reloading a death checkpoint), Aegis patches live actors directly in memory without requiring a slow map reload from disk.

2. High-Level Game Lifecycle Flowchart

text

               ┌───────────────────────────────┐
               │         Main Menu Map         │
               └───────────────┬───────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
       [Click "New Game"]              [Click "Continue"]
               │                               │
    (Reset Session Defaults)         (Query Slot: SavedMapName)
               │                               │
               │                   [Load Game from Slot]
               │                   (Records cached in memory)
               ▼                               ▼
               └───────────────┬───────────────┘
                               │
                               ▼
                   [Open Level: GameplayMap]
                               │
                               ▼
              Actors spawn in Level Map
              On Registration: Aegis applies saved state
              BEFORE the actor's first tick (AC-303)!
                               │
                               ▼
                    [Active World Gameplay]
                               │
           ┌───────────────────┼───────────────────┐
           ▼                   ▼                   ▼
    [Periodic Checkpoint]  [Level Transition]   [Player Death]
           │                   │                   │
    [Auto Save (1.0ms)]    [Save World A]       [Load Checkpoint]
    (Zero Frame Hitch)     [Open Map B]         (In-place reload;
                           Player Scope persists! no map reload!)

3. The 4 Proven Loading & Saving Workflows

This is the modern standard for polished RPGs and adventure games. The save is read while still on the menu screen, allowing the new level to spawn with its saved state already applied.

text

[Main Menu UI: Click "Continue"]
               │
               ▼
[Get Slot Info (SlotName: "SaveSlot01")]
               │
               ├─► Read SlotInfo.DisplayName (e.g., "Level_AncientRuins")
               ▼
[Load Game from Slot (SlotName: "SaveSlot01")]
               │
               ▼ (OnSuccess)
[Open Level (by Name: SlotInfo.DisplayName)]
               │
               ▼ (Engine loads map package)
Actors spawn in Level ──► On Registration: Aegis restores state BEFORE first tick!

Why This Is Superior:

No Visual Glitches: Doors that were opened in the save don't spawn closed and snap open 1 frame later.
Immediate Physics & AI: Enemy AI and physics objects wake up already in their saved states.
Fast UI: You can show a clean loading screen or cinematic transition while the map loads.

Workflow 2: Open Level, Then Load Game (Procedural Generation Flow)

If your game uses heavy procedural level generation, runtime dungeon builders, or random seed layouts, the level layout must be constructed before saved actor states are applied.

text

[Main Menu UI: Click "Continue"]
               │
               ▼
[Set SelectedSaveSlot = "SaveSlot01" on Custom GameInstance]
               │
               ▼
[Open Level (by Name: "Level_ProceduralDungeon")]
               │
               ▼ (Level Opens)
[GameMode: BeginPlay]
               │
               ▼
[Execute Procedural Room Generation]
               │
               ▼ (Generation Finished)
[Load Game from Slot (SelectedSaveSlot)] ──► Restores resident actors in-place!

Store the selected slot name in a variable on your custom UGameInstance.
Open the level.
In your GameMode::BeginPlay or procedural generator callback, call Load Game from Slot.
Aegis finds all resident actors in the world and applies their saved records.

Workflow 3: In-Place Checkpoint Reload on Player Death (Zero Loading Screen!)

When a player dies, reloading the entire level map package from disk causes unnecessary 10–15 second loading screens. With Aegis Save, you can restore all world actors in-place in milliseconds:

text

[Player Character: Health <= 0]
               │
               ▼
[Disable Player Controller Input]
               │
               ▼
[Fade Camera to Black (0.3s)]
               │
               ▼
[Load Game from Slot ("CheckpointSlot")] ──► Restores all world actors in memory!
               │
               ▼ (OnSuccess)
[Teleport Player to Last Checkpoint Transform]
[Reset Player Health and Stamina to Max]
               │
               ▼
[Fade Camera in from Black (0.3s)]
               │
               ▼
[Enable Player Controller Input]

What Happens to Live Actors During In-Place Reload?

Placed Actors: Revert their properties (SaveGame variables, transforms) back to the checkpoint snapshot.
Killed Enemies (Tombstones): If an enemy was killed before the checkpoint, it stays dead. If it was killed after the checkpoint, it respawns in its checkpoint state!
Dynamically Spawned Actors: Spawned arrows, dropped items, or summoned minions created after the checkpoint are cleaned up automatically.
Execution Time: Typically under 50 milliseconds (virtually instant).

Workflow 4: Seamless Level Transitions (Overworld ◄► Dungeon)

When a player walks through a portal or enters a dungeon, different categories of game data must be handled according to their scope:

text

[Player Interacts with Dungeon Portal]
               │
               ▼
[Auto Save: "CurrentSlot"] ──► Saves current Overworld state
               │
               ▼ (OnSuccess)
[Open Level: "Map_Dungeon_Level01"]
               │
               ▼ (Dungeon Map Opens)
┌────────────────────────────────────────────────────────────────────────┐
│ Scope Isolation Behavior:                                              │
│ • World Scope: Overworld records remain safe in the save file.        │
│   Dungeon placed actors initialize fresh from dungeon level defaults!  │
│ • Player Scope: Character level, health, mana, equipped weapons, and  │
│   inventory carry over seamlessly!                                     │
│ • Global Scope: Discovered lore, achievements, and meta-currencies     │
│   remain intact!                                                       │
└────────────────────────────────────────────────────────────────────────┘

When the player completes the dungeon and returns:

Call Auto Save: "CurrentSlot" inside the dungeon.
Call Open Level: "Map_Overworld".
The Overworld placed actors register and restore their exact state from before the player entered the dungeon!

4. How to Remember Which Level to Open

When a player clicks "Continue" or selects a slot in the Main Menu, how does your game know which .umap level to open?

Aegis provides two clean, foolproof methods:

Method A: Zero-Decompression Slot Metadata (`DisplayName`) (Recommended)

When saving during gameplay, pass the current level name into FAegisSaveOptions::DisplayName:

BlueprintC++

text

// Inside your Gameplay GameMode, PlayerController, or Checkpoint Trigger:
[Get Current Level Name]
       │
       ▼
[Make FAegisSaveOptions] ──► Pin: Display Name
       │
       ▼
[Auto Save (Aegis)] (Slot Name: "SaveSlot01")

cpp

FAegisSaveOptions Options;
Options.DisplayName = UGameplayStatics::GetCurrentLevelName(this);
Aegis->AutoSave(TEXT("SaveSlot01"), Options);

Call Get Slot Info. This reads only the lightweight 128-byte uncompressed header of the save container in 0.05 ms without decompressing world data:

BlueprintC++

text

[Btn_Continue: OnClicked]
       │
       ▼
[Get Slot Info (Slot Name: "SaveSlot01")]
       │
       ▼
[Break FAegisSlotInfo] ──► Pin: Display Name (e.g. "Level_Forest")
       │
       ▼
[Load Game from Slot (Slot Name: "SaveSlot01")]
       │
       ▼ (OnSuccess)
[Open Level (by Name: Break.DisplayName)]

cpp

FAegisSlotInfo SlotInfo;
if (Aegis->GetSlotInfo(TEXT("SaveSlot01"), SlotInfo))
{
    // 1. Load the slot data into memory
    Aegis->LoadGame(TEXT("SaveSlot01"));

    // 2. Open the saved map immediately!
    UGameplayStatics::OpenLevel(this, FName(*SlotInfo.DisplayName));
}

Method B: Player-Scope Saved Variable

If you prefer storing gameplay variables directly on your Player Character or Player State:

In your Player Character, add a variable:
- Name: CurrentMapName (String or Name)
- Category: Persistence
- Advanced: Check SaveGame
- Ensure the UAegisPersistenceComponent on the player has Scope = Player.

In your Player Character's BeginPlay:

text

[Get Current Level Name] ──► [Set CurrentMapName]

When you load the save in the Main Menu, read CurrentMapName from the player's loaded record and pass it to OpenLevel.

5. Starting a "New Game"

When a player clicks "New Game" on the Main Menu:

Step 1: Reset the In-Memory Session

To prevent data from a previous playthrough or active session from leaking into the new game, reset the session:

BlueprintC++

text

[Btn_NewGame: OnClicked]
       │
       ▼
[Reset Session (Aegis)]
       │
       ▼
[Open Level (by Name: "Level_Prologue")]

cpp

UAegisSubsystem* Aegis = UAegisSubsystem::Get(this);
if (Aegis)
{
    // Clears all in-memory records, active tombstones, and registrations
    Aegis->ResetSession();
}
UGameplayStatics::OpenLevel(this, TEXT("Level_Prologue"));

Step 2: Overwrite or Delete the Old Slot

If the player chose a specific slot to overwrite:

Call Delete Slot("SaveSlot01") before saving, OR
Simply save directly over it when the first checkpoint is reached.

6. Robustness & Fail-Safes: "Load Any How"

In production games, unexpected things happen: players delete save files, files get corrupted by sudden power loss, or game patches change level layouts. Aegis Save is engineered so your game never crashes or corrupts:

Scenario	What Happens	How to Handle in Blueprint / C++
Slot Does Not Exist	`LoadGame` fails cleanly without crashing.	Branch on the `OnFailed` pin. If failed, display an in-game alert or redirect the player to start a New Game.
File Corrupted / Power Cut	Aegis validates the CRC32 checksum in the container header before decompressing. Corrupt payloads are rejected immediately.	The `OnFailed` pin fires with `FAegisStatus` reporting `InvalidHeaderChecksum` or `CorruptPayload`.
Actor Removed in Editor Patch	An actor saved in v1.0 was deleted from the map in v1.1.	Aegis matches by permanent GUID. If an actor no longer exists in the level package, its record is safely skipped with zero errors.
Actor Moved in Editor Patch	An artist adjusted a prop's default position in the level.	If `bPersistTransform = False`, the prop adopts its new authored position! If `bPersistTransform = True`, the player's saved position takes precedence.
Variable Added or Removed	A developer deleted a variable or added a new one to a Blueprint.	Aegis binary wire format uses tagged property headers. Deleted variables are safely discarded; new variables retain their Blueprint default values!

Complete Blueprint Integration Checklist

Before shipping your game, verify your integration against this checklist:

[ ] UAegisPersistenceComponent attached to player pawn with Scope = Player.
[ ] Level props have UAegisPersistenceComponent with Scope = World.
[ ] Gameplay variables to persist have SaveGame ticked in variable details.
[ ] Level name is saved to FAegisSaveOptions::DisplayName during autosaves.
[ ] Main Menu "Continue" queries slot metadata and calls OpenLevel.
[ ] Death screen triggers in-place reload via Load Game from Slot.
[ ] Actors that drop loot or play death effects check WasDestroyedByLoad in EndPlay.

Next Steps

Check out the Level Designer & Artist Guide for zero-code level authoring.
See how to build an interactive chest in Recipe 1: Interactive Loot Chest.
Build a full Save/Load UI in Recipe 5: In-Game Save Browser UI.

Complete Game Flow & Level Transitions

1. The GameInstance Architectural Foundation

2. High-Level Game Lifecycle Flowchart

3. The 4 Proven Loading & Saving Workflows

Workflow 1: Load in Main Menu, Then Open Level (Recommended)

Why This Is Superior:

Workflow 2: Open Level, Then Load Game (Procedural Generation Flow)

Workflow 3: In-Place Checkpoint Reload on Player Death (Zero Loading Screen!)

What Happens to Live Actors During In-Place Reload?

Workflow 4: Seamless Level Transitions (Overworld ◄► Dungeon)

4. How to Remember Which Level to Open

Method A: Zero-Decompression Slot Metadata (`DisplayName`) (Recommended)

In Your Main Menu Widget:

Method B: Player-Scope Saved Variable

5. Starting a "New Game"

Step 1: Reset the In-Memory Session

Step 2: Overwrite or Delete the Old Slot

6. Robustness & Fail-Safes: "Load Any How"

Complete Blueprint Integration Checklist

Next Steps

Complete Game Flow & Level Transitions ​

1. The GameInstance Architectural Foundation ​

2. High-Level Game Lifecycle Flowchart ​

3. The 4 Proven Loading & Saving Workflows ​

Workflow 1: Load in Main Menu, Then Open Level (Recommended) ​

Why This Is Superior: ​

Workflow 2: Open Level, Then Load Game (Procedural Generation Flow) ​

Workflow 3: In-Place Checkpoint Reload on Player Death (Zero Loading Screen!) ​

What Happens to Live Actors During In-Place Reload? ​

Workflow 4: Seamless Level Transitions (Overworld ◄► Dungeon) ​

4. How to Remember Which Level to Open ​

Method A: Zero-Decompression Slot Metadata (DisplayName) (Recommended) ​

In Your Main Menu Widget: ​

Method B: Player-Scope Saved Variable ​

5. Starting a "New Game" ​

Step 1: Reset the In-Memory Session ​

Step 2: Overwrite or Delete the Old Slot ​

6. Robustness & Fail-Safes: "Load Any How" ​

Complete Blueprint Integration Checklist ​

Next Steps ​

Complete Game Flow & Level Transitions

1. The GameInstance Architectural Foundation

2. High-Level Game Lifecycle Flowchart

3. The 4 Proven Loading & Saving Workflows

Workflow 1: Load in Main Menu, Then Open Level (Recommended)

Why This Is Superior:

Workflow 2: Open Level, Then Load Game (Procedural Generation Flow)

Workflow 3: In-Place Checkpoint Reload on Player Death (Zero Loading Screen!)

What Happens to Live Actors During In-Place Reload?

Workflow 4: Seamless Level Transitions (Overworld ◄► Dungeon)

4. How to Remember Which Level to Open

Method A: Zero-Decompression Slot Metadata (`DisplayName`) (Recommended)

In Your Main Menu Widget:

Method B: Player-Scope Saved Variable

5. Starting a "New Game"

Step 1: Reset the In-Memory Session

Step 2: Overwrite or Delete the Old Slot

6. Robustness & Fail-Safes: "Load Any How"

Complete Blueprint Integration Checklist

Next Steps