World Partition & Streaming

Unreal Engine's World Partition system transforms how massive worlds are loaded: the world is divided into spatial grid cells, and actors are dynamically spawned when a cell streams in and destroyed when a cell streams out.

Traditional save systems fail completely in World Partition environments. This guide explains the fundamental hazards of streaming worlds and how Aegis Save guarantees 100% data fidelity across streaming cycles.

---

1. The World Partition Streaming Problem

In standard Unreal Engine save plugins:

1. When a player walks away from an area, that spatial cell unloads.
2. All actors in that cell are destroyed from memory. Any modified state (opened doors, damaged structures, looted chests) is wiped.
3. If the game saves while those actors are streamed out, standard plugins only save resident actors. The unloaded world is permanently lost.
4. When the player walks back, the cell streams in from disk with fresh archetype defaults. Killed enemies respawn and opened chests close!

---

2. The Aegis Solution: Record Store Superset

Aegis Save decouples the Persistence State Store from the Live World Residency:

[Streaming World Partition]
   ├── Resident Cell A (Player nearby)  ──► Live in World (Active Actor Instances)
   └── Unloaded Cell B (Player far)     ──► Destroyed from Memory

[Aegis In-Memory Record Store]
   ├── Records for Cell A (Captured from live actors)
   └── Records for Cell B (Retained in Record Store!)
            │
            ▼ (Player moves near Cell B)
   [Cell B Streams In] ──► Before First Tick: Restore State from Record Store!

Key Residency Invariants

• Get Record Count $\ge$ Get Live Actor Count: The record store is always a superset of live actors. If an actor's cell unloads, its record remains safely cached.
• Restore Before First Tick (AC-303): When a cell streams in, UAegisSubsystem intercepts actor registration and restores persistent state before the actor's first gameplay tick. The player never sees visual popping or snap-backs.
• Streaming Eviction & Return (FO-27): An actor can be evicted and streamed back dozens of times; its persistent state, inventory, and health are restored bit-exact on every cycle.

---

3. Surviving Grid Re-Partitioning (AC-209)

A common architectural trap in save plugins is indexing saved actors by their spatial grid cell coordinates (e.g. Cell_X12_Y44).

Why Cell Indexing Fails

During game development, designers frequently reconfigure World Partition grid settings:

• Grid cell size may change from 25,200 to 7,200 to optimize memory.
• Loading ranges and HLOD layer layouts are frequently adjusted.

If save records are tied to cell coordinates, every player save is corrupted whenever level settings change.

Aegis Decoupled Resolution

Aegis Save binds persistence strictly to Immutable 128-Bit Actor Identities, completely decoupled from cell coordinates or grid geometry:

Empirically Proven in AC-209

In our verified acceptance test AC-209, a save containing 10,000 external actors was written under a grid cell size of 25,200. The map was then completely re-partitioned down to 7,200 units, fundamentally altering every cell boundary.

• Result: RECORDS_RESOLVED — 9,986 of 9,986 resident actors restored with 100% bit-exact property fidelity and 0 unrestored records.

---

4. Streaming Sources & Loading Ranges

In World Partition, streaming is driven by UWorldPartitionStreamingSourceComponent and the player controller:

• Default player controllers spawn with bEnableStreamingSource = true and a typical radius of 76,800 units (~768 meters).
• In a world smaller than 76,800 units, all cells remain permanently loaded.
• To verify streaming behavior in large worlds, ensure your map extent exceeds your streaming source radius (e.g., our 10,000-actor benchmark spans 240,000 units with a loading range of 76,800 units, cycling residency actively between 0 and 10,000 actors).

---

Next Steps

• Understand how killed actors stay dead in Destroyed Actors & Tombstones.
• Review how the file layout ensures safety in Binary Wire Format v1.