UE5-Modular-Game-Framework/docs/developer/05-saveload-systems.md

05 — Save/Load, Persistence & Death Loop Systems (Systems 35-43)

Category Purpose: These 9 systems handle everything related to game state persistence — saving and loading player progress, checkpoint management, the death/respawn loop, the alternate death space (void/purgatory mechanic), persistent corpses, world state recording, run history tracking, and the I_Persistable interface contract that all saveable actors implement.

---

System Index

#	System	Asset Type	Role
35	SS_SaveManager	Subsystem	Save/load subsystem; slot management, serializer, manifest
36	I_Persistable	Interface	Persistence contract for any actor that saves state
37	BP_Checkpoint	Actor	Checkpoint actor; respawn point, activation, save-on-touch
38	BPC_AltDeathSpaceSystem	Component	Alternate death/void space; enter, explore, find exit
39	BPC_DeathHandlingSystem	Component	Death orchestrator; outcome determination, animation, respawn
40	BPC_PersistentCorpseSystem	Component	Corpse persistence across death/respawn/level transitions
41	BPC_PersistentWorldStateRecorder	Component	Records world state changes (doors, items, enemies) for save
42	BPC_PlayerRespawnSystem	Component	Respawn logic; checkpoint resolution, state restoration
43	BPC_RunHistoryTracker	Component	Run/session history; death count, time, checkpoint progression

---

Category Data Flow — The Death Loop

┌──────────────────────────────────────────────────────────────────┐
│                        DEATH & PERSISTENCE                       │
│                                                                  │
│  BPC_HealthSystem.OnDeath                                         │
│      ↓                                                           │
│  BPC_DeathHandlingSystem (death orchestrator)                    │
│      │  Determines outcome: Alt Death Space? Normal Respawn?      │
│      ├─► Alt Death Space:                                        │
│      │     BPC_AltDeathSpaceSystem.Enter()                       │
│      │     Player explores void/purgatory                         │
│      │     Find exit → RestorePreviousState()                     │
│      │                                                           │
│      └─► Normal Respawn:                                         │
│            GM_CoreGameMode.HandlePlayerDead()                     │
│            SS_SaveManager.LoadCheckpoint()                        │
│            BPC_PlayerRespawnSystem.Respawn()                      │
│                                                                  │
│  SS_SaveManager (persistence subsystem)                          │
│      │  Manages save slots, serialization, manifest              │
│      ├─► OnSave: iterates all I_Persistable actors               │
│      ├─► OnLoad: restores actor states from save file            │
│      │                                                           │
│      │  Coordinates with:                                        │
│      ├─► BPC_PersistentWorldStateRecorder (world changes)        │
│      ├─► BPC_PersistentCorpseSystem (corpse data)               │
│      └─► BP_Checkpoint (save-on-touch activation)                │
│                                                                  │
│  BPC_RunHistoryTracker (session stats)                           │
│      │  Tracks: death count, play time, checkpoint progression   │
│      └─► Persists across sessions for meta-progression           │
└──────────────────────────────────────────────────────────────────┘

---

35 — SS_SaveManager: Save/Load Subsystem

What It Does: The central save/load authority as a GameInstanceSubsystem. Manages save slots (create, load, delete, list), handles serialization of all I_Persistable actors, maintains a save slot manifest, and coordinates with platform save services.

How It Works Internally:

Save Protocol:

1. Save triggered (manual, auto-save, checkpoint)
2. Iterates all actors implementing I_Persistable in the world
3. Each actor returns its state via OnSave() as a GameplayTagContainer
4. Serializes all actor states + global data (chapter, play time, objectives) to save file
5. Updates slot manifest with timestamp, screenshot, play time

Load Protocol:

1. Load slot selected
2. Deserializes save file
3. Loads correct level/chapter
4. Iterates I_Persistable actors, calls OnLoad(SaveData) on each
5. Restores global state (chapter, objectives, inventory)
6. Player placed at appropriate spawn point

Slot Management:

• Multiple save slots with metadata (timestamp, play time, chapter name, thumbnail)
• Auto-save slot separate from manual slots
• Slot manifest tracks all available saves

---

36 — I_Persistable: Persistence Interface

What It Does: The contract that any actor must implement to be saveable. The save system scans the world for I_Persistable implementors and calls these functions.

Key Functions:

• OnSave() → returns actor state as GameplayTagContainer for serialization
• OnLoad(SaveData) → restores actor state from saved data
• GetSaveTag() → returns unique GameplayTag identifying this actor for lookup
• NeedsSave() → whether this actor has unsaved changes

Implementation: Doors (save locked/open state), chests (looted/not), enemies (alive/dead/position), items (collected/not), narrative triggers (fired/not), checkpoints (active/not).

---

37 — BP_Checkpoint: Checkpoint Actor

What It Does: A world-placed actor that serves as a respawn point. On player touch or interaction, becomes the active checkpoint. Triggers auto-save. Overrides previous checkpoint.

Features:

• Activates on overlap or interaction
• Stores checkpoint transform (player respawn location/rotation)
• Triggers SS_SaveManager.AutoSave() on activation
• Visual states: inactive (dim), active (glowing), previous (faded)
• One checkpoint active at a time
• Save-on-touch: automatic save reduces lost progress

---

38 — BPC_AltDeathSpaceSystem: Alternate Death Space

What It Does: Implements the "void space" or "purgatory" mechanic — when the player dies in specific circumstances, instead of a standard respawn, they enter an alternate death dimension. They must explore this space, find an exit, and return to the main world.

State Machine:

1. Enter() — player dies, teleports to death space level
2. Player explores void environment (puzzle, narrative, combat)
3. FindExit() — player discovers exit point
4. Exit() — teleports back to main world at respawn point
5. Fires RestorePreviousState() — pops back from force stack

Features:

• Separate level or sub-level for death space
• Unique atmosphere, enemies, and narrative content
• Exit conditions configurable (time, puzzle solve, item find)
• Multiple death space variants possible
• Coordinates with BPC_DeathHandlingSystem for entry conditions

---

39 — BPC_DeathHandlingSystem: Death Orchestrator

What It Does: Listens for BPC_HealthSystem.OnDeath and determines what happens next. The central death logic router — decides between alt death space, checkpoint respawn, permadeath, or game over.

Flow:

1. Binds to OnDeath dispatcher
2. Determines death context: enemy killed? environmental? scripted?
3. Checks BPC_DeathCauseTracker for specific death cause
4. Evaluates conditions:
   • Should alt death space trigger? (configurable chance / specific enemies)
   • Is this permadeath mode? → wipe save
   • Normal death? → checkpoint respawn
5. Routes to appropriate system: BPC_AltDeathSpaceSystem.Enter() or GM_CoreGameMode.HandlePlayerDead()
6. Plays death animation, screen effects
7. Logs death to BPC_RunHistoryTracker

---

40 — BPC_PersistentCorpseSystem: Corpse Persistence

What It Does: When the player dies, their previous body becomes a persistent corpse in the world. On respawn, the old body remains as a lootable container with the player's previous inventory. Corpses persist across deaths and level transitions.

Features:

• Spawns corpse actor at death location with player's appearance
• Contains BPC_ContainerInventory with player's previous items
• Corpse persists across respawns (doesn't disappear)
• Configurable corpse limit (oldest despawns when max reached)
• Companions can loot player corpse (co-op)

---

41-43: Supporting Systems

• 41 BPC_PersistentWorldStateRecorder: Records every world state change (door opened, item collected, enemy killed) to a change log for save/load. On load, replays changes to restore exact world state.
• 42 BPC_PlayerRespawnSystem: Loads checkpoint data, places player at checkpoint transform, restores health/stamina/inventory from save state, applies brief invincibility.
• 43 BPC_RunHistoryTracker: Tracks per-session stats: death count, play time, checkpoints reached, enemies killed, items collected. Persists for meta-progression (achievements, difficulty scaling).

---

Common Implementation Patterns in This Category

1. Force Stack Pattern: Death and alt death space push state onto a stack; RestorePreviousState() pops back. Enables nested state changes (death → void → return).
2. Interface-Based Persistence: Save system doesn't know about doors or enemies — it only calls I_Persistable.OnSave() / OnLoad(). Any new saveable type just implements the interface.
3. Save Tag Uniqueness: Each saveable actor has a unique GameplayTag for identity. The save file maps tag → serialized state.
4. Checkpoint Cascade: Checkpoints are linear — activating a new one overrides the previous. Auto-save on activation prevents progress loss.
5. Corpse as Container: Corpses reuse BPC_ContainerInventory — no special corpse inventory code needed.

---

Developer Reference v1.0 — 05 Save/Load Systems. Companion to docs/blueprints/05-saveload/ specs.

---

Multiplayer Networking

Category Authority Map

System	Authority	Notes
SS_SaveManager	Server triggers save/load	Clients receive restored state via GS_CoreGameState replication
BP_Checkpoint	Server validates activation	Active checkpoint replicates to all
BPC_DeathHandlingSystem	Server determines death outcome	Death animation multicast; respawn is server-driven
BPC_PlayerRespawnSystem	Server executes respawn	Client receives respawn state via replication
BPC_PersistentCorpseSystem	Server spawns corpse actor	Corpse replicated to all clients
BPC_PersistentWorldStateRecorder	Server records changes	State changes replicated via individual actor RepNotify
BPC_RunHistoryTracker	Server tracks; snapshot replicates	For scoreboard display

Key Multiplayer Considerations

• Save/Load is server-coordinated. Only server triggers save/load. Clients receive restored state via GS_CoreGameState and actor replication.
• Death is server-authoritative. Runs on server, determines outcome, multicasts death events.
• Alt Death Space (separate level): server calls ClientTravel for all clients.
• Corpses are replicated actors — all clients see them.