122 lines
5.7 KiB
Markdown
122 lines
5.7 KiB
Markdown
# 40 — BPC_DialoguePlaybackSystem
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`ActorComponent`
|
||
|
||
### Dependencies
|
||
- [`DA_DialogueSequence`](47_DA_NarrativeDataAssets.md) data assets
|
||
- [`WBP_SubtitleDisplay`](../06-ui/49_WBP_SubtitleDisplay.md)
|
||
- [`BPC_NarrativeStateSystem`](58_BPC_NarrativeStateSystem.md)
|
||
- [`BPC_DialogueChoiceSystem`](41_BPC_DialogueChoiceSystem.md)
|
||
|
||
### Purpose
|
||
Manages the playback of dialogue sequences: line queuing, timing, subtitle routing, audio playback, and lip-sync. Serves as the audio/visual delivery layer for all spoken narrative content.
|
||
|
||
### Responsibilities
|
||
- Receive dialogue sequence data from `DA_DialogueSequence`
|
||
- Queue lines and play in order with timing
|
||
- Trigger subtitle display via dispatcher
|
||
- Play voiceover audio
|
||
- Fire narrative flags on line completion (if configured in sequence data)
|
||
- Pause/interrupt dialogue on player action or external event
|
||
- Support skip-to-next-line and full-skip-sequence
|
||
|
||
### Does NOT Handle
|
||
- Choice presentation (that is [`BPC_DialogueChoiceSystem`](41_BPC_DialogueChoiceSystem.md))
|
||
- What dialogue plays when (that is level or narrative flow)
|
||
- Subtitle styling (that is `WBP_SubtitleDisplay`)
|
||
|
||
### Variables
|
||
|
||
| Name | Type | Description |
|
||
|------|------|-------------|
|
||
| `ActiveSequence` | DA_DialogueSequence | Currently playing sequence asset |
|
||
| `LineQueue` | Array of S_DialogueLine | Remaining lines to play |
|
||
| `bIsPlaying` | Bool | Dialogue currently active |
|
||
| `bIsPaused` | Bool | Dialogue paused |
|
||
| `CurrentLineIndex` | Integer | Index in sequence |
|
||
| `LineTimer` | TimerHandle | Auto-advance timer |
|
||
| `bBlockInputWhilePlaying` | Bool | Suppress player input during dialogue |
|
||
|
||
### Structs
|
||
|
||
| Struct | Fields | Description |
|
||
|--------|--------|-------------|
|
||
| `S_DialogueLine` | SpeakerTag: GameplayTag, LineText: FText, VoiceAudio: USoundBase, Duration: Float, LipSyncData: UAnimSequence, FlagToSetOnComplete: GameplayTag, AnimTag: GameplayTag, bIsChoicePoint: Bool | One dialogue line with metadata |
|
||
| `S_DialoguePlaybackOptions` | bCanSkipLine: Bool, bCanSkipSequence: Bool, bShowSubtitles: Bool, SubtitleDelay: Float | Per-sequence playback settings |
|
||
|
||
### Functions / Events
|
||
|
||
| Name | Inputs | Outputs | Description |
|
||
|------|--------|---------|-------------|
|
||
| `PlaySequence` | Sequence: DA_DialogueSequence | — | Loads and begins playback of a dialogue sequence |
|
||
| `PlaySequenceWithOptions` | Sequence, Options: S_DialoguePlaybackOptions | — | Play with overrides |
|
||
| `QueueSequence` | Sequence | — | Adds sequence to pending queue (for chaining) |
|
||
| `PlayNextLine` | — | — | Advances to next line in queue |
|
||
| `SkipCurrentLine` | — | — | Ends current line early, plays next |
|
||
| `SkipSequence` | — | — | Aborts entire sequence |
|
||
| `PauseDialogue` | — | — | Pause audio, hold subtitles |
|
||
| `ResumeDialogue` | — | — | Resume from pause |
|
||
| `IsDialoguePlaying` | — | Bool | Query |
|
||
| `SetSpeakerOverride` | SpeakerTag: GameplayTag | — | Override speaker for accessibility |
|
||
| `GetCurrentLine` | — | S_DialogueLine | For UI binding |
|
||
| `GetRemainingLineCount` | — | Integer | For UI progress indicator |
|
||
| `EnqueueDialogueFromVolume` | OverlapActor | — | Called by trigger volume overlap |
|
||
|
||
### Event Dispatchers
|
||
|
||
| Name | Parameters | Fired When |
|
||
|------|-----------|-----------|
|
||
| `OnDialogueStarted` | SequenceTag: GameplayTag | Sequence begins |
|
||
| `OnLineStarted` | Line: S_DialogueLine | New line begins playback |
|
||
| `OnLineCompleted` | Line: S_DialogueLine | Line audio finishes |
|
||
| `OnSequenceCompleted` | SequenceTag: GameplayTag | Full sequence done |
|
||
| `OnDialogueSkipped` | SequenceTag: GameplayTag | Player skipped sequence |
|
||
| `OnDialoguePaused` | — | Pause triggered |
|
||
| `OnDialogueResumed` | — | Resume triggered |
|
||
| `OnChoicePointReached` | Choices: Array of S_DialogueChoice | Sequence reaches a branching point |
|
||
|
||
### Blueprint Flow
|
||
|
||
```
|
||
[PlaySequence called]
|
||
└─► If bIsPlaying → return (or QueueSequence)
|
||
└─► Set bIsPlaying = true
|
||
└─► Validate sequence conditions (RequiredFlags from DA_DialogueSequence)
|
||
└─► Load line queue from sequence asset
|
||
└─► Broadcast OnDialogueStarted
|
||
└─► Call PlayNextLine
|
||
|
||
[PlayNextLine]
|
||
└─► Queue empty? → Broadcast OnSequenceCompleted → bIsPlaying = false → return
|
||
└─► Get next S_DialogueLine
|
||
└─► Start LineTimer (Duration)
|
||
└─► Play VoiceAudio
|
||
└─► Broadcast OnLineStarted
|
||
└─► If line has AnimTag → notify ABP via dispatcher
|
||
└─► If line is choice point → hand off to BPC_DialogueChoiceSystem
|
||
└─► Wait for LineTimer or SkipCurrentLine
|
||
|
||
[OnLineCompleted]
|
||
└─► If line has FlagToSetOnComplete → BPC_NarrativeStateSystem.SetFlag()
|
||
└─► Advance CurrentLineIndex
|
||
└─► Call PlayNextLine
|
||
```
|
||
|
||
### Communications With
|
||
|
||
| Target System | Method | Why |
|
||
|---------------|--------|-----|
|
||
| [`WBP_SubtitleDisplay`](../06-ui/49_WBP_SubtitleDisplay.md) | Dispatcher | Show/hide subtitles |
|
||
| [`BPC_NarrativeStateSystem`](58_BPC_NarrativeStateSystem.md) | Direct | Set flags on line completion |
|
||
| [`BPC_DialogueChoiceSystem`](41_BPC_DialogueChoiceSystem.md) | Dispatcher | Hand off at choice points |
|
||
| [`BPC_CameraStateLayer`](../02-player/14_BPC_CameraStateLayer.md) | Dispatcher | Cinematic camera mode for dialogue |
|
||
| [`BPC_EmbodimentSystem`](../02-player/13_BPC_EmbodimentSystem.md) | Dispatcher | Gesture animation tags |
|
||
| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | Direct | Set game phase during dialogue |
|
||
|
||
### Reuse Notes
|
||
`DA_DialogueSequence` data assets hold all content — add new sequences per project without touching this system. Voice audio is optional: sequences work without audio (text-only dialogue). Lip-sync data is per-line and can use audio-driven or procedural lip sync. |