UE5-Modular-Game-Framework/docs/blueprints/07-narrative/58_BPC_NarrativeStateSystem.md

38 — BPC_NarrativeStateSystem

Blueprint Spec — UE 5.5–5.7

---

Parent Class

ActorComponent

Dependencies

• I_Persistable Interface
• Gameplay Tag System
• SS_SaveManager
• BPC_ObjectiveSystem
• BPC_EndingAccumulatorSystem
• BPC_BranchingConsequenceSystem
• 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
• 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 job)
• Dialogue flow or choices (those are separate systems)
• Objective tracking (that is BPC_ObjectiveSystem)
• Ending condition evaluation (that is BPC_EndingAccumulatorSystem)

---

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
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	Direct + Dispatcher	Objective activation / completion
BPC_BranchingConsequenceSystem	Dispatcher	Consequence evaluation trigger
BPC_EndingAccumulatorSystem	Direct	Ending condition evaluation
BPC_DialoguePlaybackSystem	Direct	Dialogue condition checks
BPC_LoreUnlockSystem	Dispatcher	Lore discovery on flag set
All I_NarrativeActor implementors (doors, lights, etc.)	Interface	World reacts to flag changes
SS_SaveManager	I_Persistable	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.

---

Manual Implementation Guide

Class Setup

1. Create Blueprint Class: Parent = ActorComponent, Name = BPC_NarrativeStateSystem
2. Add to Player Character or GameState (if shared)
3. Implement Interface: I_Persistable

Variable Init (BeginPlay)

Event BeginPlay
  ├─ Set NarrativeFlags = empty Map<GameplayTag, Boolean>
  ├─ Set NarrativeValues = empty Map<GameplayTag, Float>
  ├─ Set NarrativeHistory = empty Array<GameplayTag>
  ├─ Set MaxHistorySize = 500
  └─ If implementing I_Persistable: register with SS_SaveManager

Function Node-by-Node

SetFlag(Tag: GameplayTag, Value: Boolean) → void

Step 1: OldValue = NarrativeFlags.Find(Tag) or false
Step 2: NarrativeFlags.Add(Tag, Value)  ← Map Add (overwrites if exists)
Step 3: If Value == true AND OldValue == false:
  NarrativeHistory.Add(Tag)
  If NarrativeHistory.Length > MaxHistorySize: Remove oldest entry
Step 4: Fire OnFlagChanged(Tag, Value)
Step 5: Notify I_Persistable: Mark dirty for save

Nodes: Map Find, Map Add, Array Add, Array Length, Remove Index 0

SetValue(Tag, Value: Float) → void

Step 1: NarrativeValues.Add(Tag, Value)
Step 2: Fire OnValueChanged(Tag, Value)

GetFlag(Tag) → Boolean (Pure)

NarrativeFlags.Find(Tag) → if found: return value, else: return false

HasAllFlags(Tags: Array<GameplayTag>) → Boolean

ForEach Tags:
  If GetFlag(ArrayElement) == false → Return false
Return true

CollectState() → S_WorldObjectState (I_Persistable)

Step 1: Create S_WorldObjectState
Step 2: Serialize NarrativeFlags: ForEach → store (Tag, Value) as string pairs in CustomData
Step 3: Serialize NarrativeValues similarly
Step 4: Return struct

RestoreState(Data: S_WorldObjectState) (I_Persistable)

Step 1: Clear NarrativeFlags, NarrativeValues, NarrativeHistory
Step 2: Parse CustomData → ForEach entry → NarrativeFlags.Add(Tag, BoolValue)
Step 3: Parse values → NarrativeValues.Add(Tag, FloatValue)

Build Checklist

• Create BPC_NarrativeStateSystem, add to Player Character
• Define variables: NarrativeFlags (Map), NarrativeValues (Map), NarrativeHistory (Array), MaxHistorySize
• Implement SetFlag/GetFlag with map operations
• Implement SetValue/GetValue for numeric values
• Implement HasAllFlags/HasAnyFlags for batch queries
• Implement CollectState/RestoreState for I_Persistable
• Create OnFlagChanged/OnValueChanged event dispatchers
• Test: call SetFlag → verify OnFlagChanged fires → other systems react