# BPC_PersistentWorldStateRecorder — Actor Component

**File:** [`Content/Framework/Save/BPC_PersistentWorldStateRecorder`](Content/Framework/Save/BPC_PersistentWorldStateRecorder.uasset)
**Parent Class:** `UActorComponent`
**Dependencies:** [`I_Persistable`](36_I_Persistable.md), [`SS_SaveManager`](35_SS_SaveManager.md)

**Purpose:** Tracks all world-object state changes throughout a session so they can be serialised on save and restored on load. Maintains the delta map of changed world objects and coordinates save/load with all registered `I_Persistable` actors.

---

## Variables

| Name | Type | Description |
|------|------|-------------|
| `PersistableActors` | Array of Actor Reference | All registered `I_Persistable` actors |
| `WorldStateDelta` | Map (Name → `S_WorldObjectState`) | Changed state records since last save |
| `bIsCollecting` | Bool | Prevent re-entrant collect operations |
| `bIsDistributing` | Bool | Prevent re-entrant distribute operations |

## Structs

```cpp
S_WorldObjectState
{
    ObjectTag:    GameplayTag   // Unique identifier matching the actor's tag
    bDestroyed:   Bool          // Was the actor destroyed?
    CustomData:   Map (Name → String)  // Generic key-value store for any component state
}
```

## Functions / Events

| Name | Inputs | Outputs | What it does |
|------|--------|---------|--------------|
| `RegisterPersistableActor` | Actor: Actor Reference | — | Adds an `I_Persistable` actor to the tracked list |
| `UnregisterPersistableActor` | Actor: Actor Reference | — | Removes an `I_Persistable` actor from the tracked list |
| `CollectWorldState` | — | — | Iterates all registered actors and calls `I_Persistable.CollectState()` |
| `DistributeWorldState` | — | — | Iterates all registered actors and calls `I_Persistable.RestoreState()` |
| `GetWorldStateDelta` | — | Map (Name → S_WorldObjectState) | Returns full delta map for serialisation |
| `ClearWorldStateDelta` | — | — | Clears the delta after save |
| `HasPersistableActor` | Actor: Actor Reference | Bool | Check if actor is registered |

## Event Dispatchers

| Name | Parameters | Fired when |
|------|-----------|-----------|
| `OnWorldStateCollected` | ActorCount: Integer | All registered actors collected |
| `OnWorldStateDistributed` | ActorCount: Integer | All registered actors restored |

## Blueprint Flow Diagram

```mermaid
flowchart TD
    A[RegisterPersistableActor] --> B[Add to PersistableActors array]
    C[SS_SaveManager.SaveToSlot called] --> D[Call CollectWorldState]
    D --> E[bIsCollecting?]
    E -->|Yes| F[Return]
    E -->|No| G[Set bIsCollecting = true]
    G --> H[Iterate PersistableActors]
    H --> I[Call I_Persistable.CollectState on each]
    I --> J[Store in WorldStateDelta]
    J --> K[Set bIsCollecting = false]
    K --> L[Broadcast OnWorldStateCollected]

    M[SS_SaveManager.LoadFromSlot called] --> N[Call DistributeWorldState]
    N --> O[bIsDistributing?]
    O -->|Yes| P[Return]
    O -->|No| Q[Set bIsDistributing = true]
    Q --> R[Iterate PersistableActors]
    R --> S[Call I_Persistable.RestoreState with WorldStateDelta entry]
    S --> T[Set bIsDistributing = false]
    T --> U[Broadcast OnWorldStateDistributed]
```

## Communications With

| Target System | Method | Why |
|---------------|--------|-----|
| All `I_Persistable` actors | Interface calls | Collect/restore world state |
| `SS_SaveManager` | Direct | Provides world state delta for save |
| `GI_GameFramework` | Direct | Lifecycle bindings |

## Reuse Notes

- Actors register themselves in `BeginPlay` and unregister in `EndPlay`
- The `CustomData` map allows any component to store arbitrary state without modifying the struct
- Adding new `I_Persistable` actor types requires zero changes to this system
- For spawned/destroyed actors mid-session, register/unregister when the actor is created/destroyed
- The `WorldStateDelta` is cleared after each save to track only changes since last save