admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add blueprints

Browse Source
This commit is contained in:
Lefteris Notas
2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/blueprints/07-narrative/58_BPC_NarrativeStateSystem.md Normal file
View File

@@ -0,0 +1,114 @@
# 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.