114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
# 38 — BPC_NarrativeStateSystem
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`ActorComponent`
|
||
|
||
### Dependencies
|
||
- [`I_Persistable`](../01-core/29_I_Persistable.md) Interface
|
||
- Gameplay Tag System
|
||
- [`SS_SaveManager`](../05-save/28_SS_SaveManager.md)
|
||
- [`BPC_ObjectiveSystem`](39_BPC_ObjectiveSystem.md)
|
||
- [`BPC_EndingAccumulatorSystem`](45_BPC_EndingAcceleratorSystem.md)
|
||
- [`BPC_BranchingConsequenceSystem`](42_BPC_BranchingConsequenceSystem.md)
|
||
- All `I_NarrativeActor` implementors
|
||
|
||
### Purpose
|
||
The authoritative store of all narrative flags. Every story decision, discovered secret, and consequence tag is registered here. Acts as the single source of truth for narrative state — all other systems read from here rather than maintaining their own flag copies.
|
||
|
||
### Responsibilities
|
||
- Store narrative flags as `GameplayTag → Bool` map
|
||
- Store numeric narrative values as `GameplayTag → Float` map
|
||
- Provide add / check / remove flag API
|
||
- Persist flags via [`I_Persistable`](../01-core/29_I_Persistable.md)
|
||
- Broadcast flag changes so reactive systems update (doors, dialogue, environment)
|
||
- Maintain ordered acquisition log for run summary
|
||
|
||
### Does NOT Handle
|
||
- What happens when a flag changes (that is [`BPC_BranchingConsequenceSystem`](42_BPC_BranchingConsequenceSystem.md) job)
|
||
- Dialogue flow or choices (those are separate systems)
|
||
- Objective tracking (that is [`BPC_ObjectiveSystem`](39_BPC_ObjectiveSystem.md))
|
||
- Ending condition evaluation (that is [`BPC_EndingAccumulatorSystem`](45_BPC_EndingAcceleratorSystem.md))
|
||
|
||
---
|
||
|
||
### Variables
|
||
|
||
| Name | Type | Description |
|
||
|------|------|-------------|
|
||
| `NarrativeFlags` | Map (GameplayTag → Bool) | Binary story flags |
|
||
| `NarrativeValues` | Map (GameplayTag → Float) | Numeric story values (reputation, corruption, etc.) |
|
||
| `NarrativeHistory` | Array of GameplayTag | Ordered flag acquisition log |
|
||
| `bPersistEnabled` | Bool | Whether state auto-persists through [`I_Persistable`](../01-core/29_I_Persistable.md) |
|
||
| `MaxHistorySize` | Integer | Limits history log to prevent save bloat (default: 500) |
|
||
|
||
### Enums
|
||
|
||
None required. Flags are GameplayTag-driven.
|
||
|
||
### Structs
|
||
|
||
None required. Flat Tag maps suffice.
|
||
|
||
### Functions / Events
|
||
|
||
| Name | Inputs | Outputs | Description |
|
||
|------|--------|---------|-------------|
|
||
| `SetFlag` | Tag: GameplayTag, Value: Bool | — | Sets a narrative flag to true/false |
|
||
| `GetFlag` | Tag: GameplayTag | Bool | Reads a flag; returns false if tag not present |
|
||
| `RemoveFlag` | Tag: GameplayTag | — | Removes a flag entirely from the map |
|
||
| `SetValue` | Tag: GameplayTag, Value: Float | — | Sets a numeric narrative value |
|
||
| `GetValue` | Tag: GameplayTag | Float | Reads numeric value; returns 0 if not present |
|
||
| `AddToValue` | Tag: GameplayTag, Delta: Float | — | Adds delta to existing value (creates if absent) |
|
||
| `HasAllFlags` | Tags: Array of GameplayTag | Bool | Returns true only if ALL flags are true |
|
||
| `HasAnyFlag` | Tags: Array of GameplayTag | Bool | Returns true if ANY flag is true |
|
||
| `GetAllActiveFlags` | — | Array of GameplayTag | Returns all currently-true flags |
|
||
| `ClearAllFlags` | — | — | Resets all flags and values (used on new game) |
|
||
| `CollectState` (I_Persistable) | — | S_WorldObjectState | Serializes flags and values into the custom data map |
|
||
| `RestoreState` (I_Persistable) | Data: S_WorldObjectState | — | Deserializes flags and values from the custom data map |
|
||
|
||
### Event Dispatchers
|
||
|
||
| Name | Parameters | Fired When |
|
||
|------|-----------|-----------|
|
||
| `OnFlagChanged` | Tag: GameplayTag, NewValue: Bool | Any flag value changes |
|
||
| `OnValueChanged` | Tag: GameplayTag, NewValue: Float | Any numeric value changes |
|
||
| `OnHistoryFull` | — | History log reaches MaxHistorySize |
|
||
|
||
### Blueprint Flow
|
||
|
||
```
|
||
[SetFlag called]
|
||
└─► Store value in NarrativeFlags map
|
||
└─► Append tag to NarrativeHistory (if becoming true)
|
||
└─► Broadcast OnFlagChanged
|
||
└─► Mark owner for persistence via I_Persistable
|
||
|
||
[GetFlag called]
|
||
└─► Look up tag in NarrativeFlags map
|
||
└─► Tag found? → return its value
|
||
└─► Tag missing? → return false
|
||
|
||
[CollectState for save]
|
||
└─► Serialize NarrativeFlags → array of (Tag, Bool) pairs
|
||
└─► Serialize NarrativeValues → array of (Tag, Float) pairs
|
||
└─► Bundle into S_WorldObjectState.CustomData with key "NarrativeData"
|
||
```
|
||
|
||
### Communications With
|
||
|
||
| Target System | Method | Why |
|
||
|---------------|--------|-----|
|
||
| [`BPC_ObjectiveSystem`](39_BPC_ObjectiveSystem.md) | Direct + Dispatcher | Objective activation / completion |
|
||
| [`BPC_BranchingConsequenceSystem`](42_BPC_BranchingConsequenceSystem.md) | Dispatcher | Consequence evaluation trigger |
|
||
| [`BPC_EndingAccumulatorSystem`](45_BPC_EndingAcceleratorSystem.md) | Direct | Ending condition evaluation |
|
||
| [`BPC_DialoguePlaybackSystem`](40_BPC_DialoguePlaybackSystem.md) | Direct | Dialogue condition checks |
|
||
| [`BPC_LoreUnlockSystem`](46_BPC_LoreUnlockSystem.md) | Dispatcher | Lore discovery on flag set |
|
||
| All `I_NarrativeActor` implementors (doors, lights, etc.) | Interface | World reacts to flag changes |
|
||
| [`SS_SaveManager`](../05-save/28_SS_SaveManager.md) | [`I_Persistable`](../01-core/29_I_Persistable.md) | Flag persistence across sessions |
|
||
|
||
### Reuse Notes
|
||
The entire system is tag-driven and fully generic. The `Narrative.Flag.*` and `Narrative.Phase.*` namespaces are empty by default — fill them per project with game-specific flags. Add new numeric value types (reputation, corruption, etc.) by simply calling `SetValue` with the appropriate tag. No code/blueprint changes needed. |