System Architecture

Aegis Save is built on a high-throughput, asynchronous pipeline designed specifically to eliminate the traditional "autosave hitch" in massive Unreal Engine worlds. This guide details how the subsystem, capture scheduler, in-memory record store, and container storage engine coordinate.

---

1. High-Level Architectural Pipeline

Game Thread                      Background Workers                 File System (.aegis)
═══════════                      ══════════════════                 ════════════════════
[Persistent Actors]
       │ (Incremental Walk)
       ▼
[Aegis Snapshot Scheduler]
   (Bounds work to 1.0 ms)
       │
       ▼
[In-Memory Record Store] ──────► [Bundle Assembler]
   (World / Player / Global)        (Z-Order Locality)
                                           │
                                           ▼
                                 [Oodle Compressor]
                                 (Parallel Task Pool)
                                           │
                                           ▼
                                 [Container Storage Engine] ──► [Disk Write & .bak Retain]
                                    (CRC32 Validation)

The architecture is divided into four distinct, decoupled layers:

1. Identity & Reflection Layer: Manages stable actor identities, tracks residency across World Partition cells, and queries marked SaveGame properties.
2. Snapshot Scheduler: Slices serialization across multiple frames under a configurable frame budget (FrameBudgetMilliseconds, default 1.0 ms).
3. In-Memory Record Store: Caches all persistent records across three isolated scopes (World, Player, Global).
4. Container & Storage Backend: Assembles records into compressed bundles, reuses unchanged data verbatim, validates integrity with CRC32 checksums, and writes to disk on background worker threads.

---

2. The Four Core Subsystems

1. UAegisSubsystem (World Subsystem)

The central coordination hub. Instantiated automatically per UWorld:

• Dispatches SaveGame, AutoSave, and LoadGame requests.
• Enforces mutual exclusion: refuses overlapping operations with EAegisResult::OperationInProgress (A-3).
• Tracks active streaming residency and hooks into World Partition stream-in/stream-out delegates.
• Exposes delegates (OnSaveCompleted, OnLoadCompleted) and public Blueprint latent actions.

2. UAegisPersistenceComponent (Actor Identity & State)

Attached to any actor that requires persistence:

• Adopts the editor-assigned ActorGuid into a serialized, permanent PersistentId (C-83).
• Dictates whether location, rotation, and scale persist via bPersistTransform.
• Governs change-detection mode (Automatic, Revision, Manual, Always).
• Integrates with Unreal Editor's Map Check system to catch missing identities at edit time (FO-26).

3. Incremental Snapshot Scheduler

Spreads capture work across frames:

• Runs during engine tick when an Incremental save pass is active.
• Measures wall-clock execution time per frame against FrameBudgetMilliseconds (default 1.0 ms).
• Captures batches of resident actors until the budget is exhausted, then yields execution until the next frame.
• Mass Mutation Immediate Capture: Actors modified in the current frame are captured immediately to prevent world state tearing (FO-16).

4. Container Storage Engine & Worker Pipeline

Once all resident records are captured:

• Assembles records into locality-correlated bundles (using Morton Z-order spatial indexing) to maximize data locality.
• Reuses unchanged bundles verbatim from the existing save file (F-3), avoiding redundant compression and disk writes.
• Dispatches payload compression (using Epic's high-speed Oodle Kraken codec) to background task graph workers (FAegisPendingWrite).
• Atomically flushes the payload to disk, keeping the previous save intact as a verified .bak backup file (C-35).

---

3. Concurrency & Thread-Safety Model

To ensure zero gameplay hitches and 100% thread safety:

Pipeline Stage	Executing Thread	Impact on Gameplay Thread
Change Detection	Game Thread	Microseconds (checks integer revision counters).
Property Walk	Game Thread	Bounded by FrameBudgetMilliseconds (default 1.0 ms).
Record Hashing	Game Thread	Sub-millisecond (CRC32 of captured payload).
Verbatim Bundle Reuse	Worker Thread	0 ms (Offloaded to task graph).
Oodle Compression	Worker Thread	0 ms (Offloaded to task graph).
File I/O & Disk Flushing	Worker Thread	0 ms (Offloaded to task graph).

Game Thread Isolation

The Game Thread only performs property capture under the strict 1.0 ms budget ceiling. Heavy compression (Oodle Kraken) and disk writes never touch the Game Thread.

---

4. Multi-Scope State Isolation

Aegis Save partitions records into three independent scopes within every save container:

Save Slot Container (.aegis)
├── Scope: World
│   ├── Placed Level Actors (Chests, Doors, Puzzles)
│   └── Harvested Resource Nodes & Enemy Tombstones
├── Scope: Player
│   ├── Player Character Stats (Health, Mana, Stamina)
│   ├── Inventory Items & Equipment
│   └── Active Quest Journal & Objectives
└── Scope: Global
    ├── Unlocked Achievements & Lore Codex
    ├── Account-Wide Meta-Currency
    └── Persistent Spawn ID Monotonic Counters

• World Scope: Captures placed actors, streaming cells, and environmental modifications. Cleared when traveling to a different map.
• Player Scope: Captures player character progression, inventory, and quest status. Preserved across level transitions.
• Global Scope: Captures slot-wide metadata, achievements, and unlocked perks.

---

Next Steps

• Learn how stable identities are established in Persistent Identities.
• Understand how Aegis survives streaming in World Partition & Streaming.
• Discover how killed enemies stay dead in Destroyed Actors & Tombstones.