UE5-Modular-Game-Framework/docs/blueprints/07-narrative/62_BPC_BranchingConsequenceSystem.md

42 — BPC_BranchingConsequenceSystem

Blueprint Spec — UE 5.5–5.7

---

Parent Class

ActorComponent

Dependencies

• BPC_NarrativeStateSystem
• DA_ConsequenceRule
• BPC_ObjectiveSystem
• BPC_DialoguePlaybackSystem

Purpose

Evaluates narrative consequences when flags change. Listens for flag changes across the narrative state and fires off deferred or immediate consequences: new dialogue, objective updates, world-state changes, or scene transitions.

Responsibilities

• Watch for flag changes (via dispatcher from BPC_NarrativeStateSystem)
• Match changed flags against DA_ConsequenceRule entries
• Execute matched consequence actions (play dialogue, update objective, modify world, trigger cutscene)
• Handle priority and stacking for multiple consequences firing simultaneously
• Separate immediate vs. delayed consequences (allow narrative beat to breathe)

Does NOT Handle

• Setting flags (that is BPC_NarrativeStateSystem)
• Playing dialogue lines (that is BPC_DialoguePlaybackSystem)
• Evaluating choices (that is BPC_DialogueChoiceSystem)
• Triggering cutscene play (that is BPC_CutsceneBridge)

Variables

Name	Type	Description
ConsequenceRules	Array of DA_ConsequenceRule	Loaded rules from content registry
PendingConsequences	Array of FConsequencePayload	Queue of delayed consequences
ActiveConsequenceCount	Integer	Prevent stacking beyond max
MaxConcurrentConsequences	Integer	Max simultaneous actions (default 3)

Structs

Struct	Fields	Description
FConsequencePayload	RuleRef: DA_ConsequenceRule, TriggerFlag: GameplayTag, FireTime: Float (world time for delayed), bIsImmediate: Bool	Holds a consequence awaiting execution

Enums

Enum	Values	Description
EConsequenceActionType	PlayDialogue, UpdateObjective, SetWorldState, TriggerCutscene, UnlockLore, ModifyStat, SpawnActor, DestroyActor	Types of actions a consequence can perform

Functions / Events

Name	Inputs	Outputs	Description
RegisterConsequenceRule	Rule: DA_ConsequenceRule	—	Add a rule to active set
OnFlagChanged	FlagTag: GameplayTag, bIsSet: Bool	—	Dispatcher callback from narrative state
EvaluateRulesForFlag	FlagTag: GameplayTag	Array of DA_ConsequenceRule	Find matching rules
ExecuteConsequence	Rule: DA_ConsequenceRule	—	Fire immediate or queue delayed
ExecuteImmediateAction	Action: FConsequenceData	—	Internal: performs single action
ProcessDelayedConsequences	—	—	Called every tick or on timer for delayed queue
ClearPendingConsequences	—	—	Clear all pending (e.g., on scene transition)
GetActiveRuleCount	—	Integer

Data: FConsequenceData (Inline in DA_ConsequenceRule)

Field	Type	Description
ActionType	Enum(EConsequenceActionType)	What to do
TargetTag	GameplayTag	Dialogue sequence, objective, or world flag to apply
FloatValue	Float	Numeric modifier (e.g., stat change)
DelaySeconds	Float	0 = immediate, >0 = delayed
bBlocking	Bool	If true, wait for this to complete before next
Priority	Integer	Higher = execute first

Event Dispatchers

Name	Parameters	Fired When
OnConsequenceTriggered	Rule: DA_ConsequenceRule, ActionType: EConsequenceActionType	Consequence begins execution
OnConsequenceCompleted	Rule: DA_ConsequenceRule	Consequence finished
OnConsequenceQueueChanged	PendingCount: Integer	Delayed queue size changed

Blueprint Flow

[BPC_NarrativeStateSystem dispatches OnFlagChanged]
  └─► BPC_BranchingConsequenceSystem.OnFlagChanged(FlagTag, bIsSet)
  └─► EvaluateRulesForFlag(FlagTag)
  └─► For each matching DA_ConsequenceRule:
      └─► Check rule's required flag state matches current state
      └─► If match → ExecuteConsequence(Rule)

[ExecuteConsequence - immediate]
  └─► Broadcast OnConsequenceTriggered
  └─► ExecuteImmediateAction(Action)
  └─► Switch on ActionType:
      PlayDialogue → request BPC_DialoguePlaybackSystem.PlaySequence(TargetTag)
      UpdateObjective → request BPC_ObjectiveSystem.AddOrUpdateObjective(...)
      SetWorldState → BPC_NarrativeStateSystem.SetStateFlag(TargetTag, true)
      TriggerCutscene → request BPC_CutsceneBridge.BeginCutscene(TargetTag)
      UnlockLore → BPC_NarrativeStateSystem.UnlockLoreEntry(TargetTag)
      ModifyStat → through player's stat component
      SpawnActor → spawn from registry
      DestroyActor → destroy by tag lookup
  └─► Broadcast OnConsequenceCompleted

[ExecuteConsequence - delayed]
  └─► Create FConsequencePayload with FireTime = WorldTime + DelaySeconds
  └─► Add to PendingConsequences array
  └─► Sort by FireTime
  └─► Broadcast OnConsequenceQueueChanged

Communications With

Target System	Method	Why
BPC_NarrativeStateSystem	Dispatcher (receives) + Direct (sets world state)	Listens for flag changes, may set additional flags
BPC_DialoguePlaybackSystem	Direct	Trigger dialogue sequences as consequences
BPC_ObjectiveSystem	Direct	Update/add objectives as consequences
BPC_CutsceneBridge	Direct	Trigger cutscenes as consequences
BPC_LoreUnlockSystem	Direct	Unlock lore entries

Reuse Notes

Consequence rules are data-driven via DA_ConsequenceRule, enabling designers to author branch logic without blueprint edits. The system supports both immediate and delayed consequences, allowing dramatic pacing. Priority sorting ensures critical consequences fire first. Blocking flag prevents race conditions between sequential narrative beats.

---

Manual Implementation Guide

Class Setup

1. Create Blueprint Class: Parent = ActorComponent, Name = BPC_BranchingConsequenceSystem
2. Add to Player Character

Variable Init (BeginPlay)

Event BeginPlay
  ├─ Set ConsequenceRules = empty array (loaded from DA_ConsequenceRule registry)
  ├─ Set PendingConsequences = empty array
  ├─ Set MaxConcurrentConsequences = 3
  └─ Cache: BPC_NarrativeStateSystem, BPC_DialoguePlaybackSystem, BPC_ObjectiveSystem, BPC_CutsceneBridge, BPC_LoreUnlockSystem

Function Node-by-Node

OnFlagChanged(Fage: GameplayTag, NewValue: Boolean) → void (Bind to NarrativeStateSystem.OnFlagChanged)

Step 1: If NewValue == false → Return (only react to true flags)
Step 2: ForEach ConsequenceRules:
  If Rule.TriggerFlag == Flag:
    Create FConsequencePayload(RuleRef=Rule, TriggerFlag=Flag, bIsImmediate=Rule.bIsImmediate, FireTime=Now+Delay)
    If bIsImmediate: Add to pending, call ProcessPendingConsequences
    Else: Add to PendingConsequences queue with timer

ProcessPendingConsequences() → void

Step 1: Sort PendingConsequences by Rule.Priority (descending)
Step 2: ForEach PendingConsequences (up to MaxConcurrentConsequences):
  Switch on Rule.ActionType:
    PlayDialogue → BPC_DialoguePlaybackSystem.PlaySequence(Rule.DialogueSequence)
    SetObjective → BPC_ObjectiveSystem.ActivateObjective(Rule.ObjectiveTag)
    UnlockLore → BPC_LoreUnlockSystem.UnlockEntry(Rule.LoreTag)
    TriggerCutscene → BPC_CutsceneBridge.PlayCutscene(Rule.CutsceneData)
    SetFlag → BPC_NarrativeStateSystem.SetFlag(Rule.FlagTag, true)
    GrantItem → BPC_InventorySystem.AddItem(Rule.ItemAsset, 1)
Step 3: Remove processed from queue

Build Checklist

• Create component, add to Player Character
• Bind to BPC_NarrativeStateSystem.OnFlagChanged
• Load DA_ConsequenceRule assets into ConsequenceRules array
• Implement OnFlagChanged: match trigger flag → create payload
• Implement ProcessPendingConsequences with action switch
• Create DA_ConsequenceRule Data Asset type with action enum and fields