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

127
docs/blueprints/07-narrative/62_BPC_BranchingConsequenceSystem.md Normal file
View File

@@ -0,0 +1,127 @@
# 42 — BPC_BranchingConsequenceSystem
## Blueprint Spec — UE 5.5–5.7
---
### Parent Class
`ActorComponent`
### Dependencies
- [`BPC_NarrativeStateSystem`](58_BPC_NarrativeStateSystem.md)
- [`DA_ConsequenceRule`](48_DA_NarrativeDataAssets.md)
- [`BPC_ObjectiveSystem`](39_BPC_ObjectiveSystem.md)
- [`BPC_DialoguePlaybackSystem`](40_BPC_DialoguePlaybackSystem.md)
### 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`](58_BPC_NarrativeStateSystem.md) | Dispatcher (receives) + Direct (sets world state) | Listens for flag changes, may set additional flags |
| [`BPC_DialoguePlaybackSystem`](40_BPC_DialoguePlaybackSystem.md) | Direct | Trigger dialogue sequences as consequences |
| [`BPC_ObjectiveSystem`](39_BPC_ObjectiveSystem.md) | Direct | Update/add objectives as consequences |
| [`BPC_CutsceneBridge`](44_BPC_CutsceneBridge.md) | Direct | Trigger cutscenes as consequences |
| [`BPC_LoreUnlockSystem`](46_BPC_LoreUnlockSystem.md) | 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.