# 44 — BPC_CutsceneBridge

## Blueprint Spec — UE 5.5–5.7

---

### Parent Class
`ActorComponent`

### Dependencies
- [`BPC_NarrativeStateSystem`](58_BPC_NarrativeStateSystem.md)
- [`BPC_DialoguePlaybackSystem`](40_BPC_DialoguePlaybackSystem.md)
- [`BPC_CheckpointSystem`](../04-save/34_BPC_CheckpointSystem.md)
- [`DA_CutsceneData`](48_DA_NarrativeDataAssets.md)

### Purpose
Bridges gameplay and pre-authored cinematics. Manages cutscene triggers, playback, and cleanup. Handles player input suppression, camera transfer, HUD hiding, and seamless return to gameplay.

### Responsibilities
- Load cutscene definition from `DA_CutsceneData`
- Transition gameplay camera to cinematic camera
- Suppress player input and hide HUD
- Play Level Sequence actor or Sequencer track
- Listen for sequence completion or skip input
- Restore gameplay state on completion
- Set narrative flags at cutscene milestones (start / beat / end)

### Does NOT Handle
- Creating cutscene sequences in Sequencer (that is a content authoring task)
- Dialogue during cutscenes (uses `BPC_DialoguePlaybackSystem` for subtitled lines)
- Triggering cutscene based on narrative state (that is `BPC_NarrativeStateSystem` or level blueprints)

### Variables

| Name | Type | Description |
|------|------|-------------|
| `ActiveCutscene` | DA_CutsceneData | Currently playing cutscene data |
| `CutsceneSequence` | LevelSequenceActor | Reference to the spawned sequence |
| `CinematicCameraActor` | CineCameraActor | Camera used during cutscene |
| `bIsPlaying` | Bool | Currently in cutscene playback |
| `bCanSkip` | Bool | Player can skip this cutscene |
| `TimeBeforeSkip` | Float | Seconds before skip becomes available |
| `bInputSuppressed` | Bool | Player input disabled |
| `SkipHoldDuration` | Float | Seconds player must hold skip key |

### Enums

| Enum | Values | Description |
|------|--------|-------------|
| `ECutsceneTransitionType` | FadeInOut, HardCut, LetterBox, BlackBars | Visual transition style for cutscene |
| `ECutsceneTriggerType` | OnVolumeEnter, OnNarrativeFlag, OnInteraction, OnLevelLoad, OnScenarioComplete | What triggers the cutscene |

### Structs

| Struct | Fields | Description |
|--------|--------|-------------|
| `FCutsceneMilestone` | TimeSeconds: Float, FlagTag: GameplayTag, bFireOnce: Bool | A narrative flag fired at a specific sequence time |
| `FCutsceneSkipResult` | bWasSkipped: Bool, SkipTime: Float | Skip outcome |

### Functions / Events

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `PlayCutscene` | CutsceneData: DA_CutsceneData | — | Begin cutscene playback |
| `OnCutsceneStarted` | — | — | Internal: after transition |
| `OnCutsceneTick` | DeltaSeconds: Float | — | Check milestones, input, etc. |
| `OnCutsceneEnded` | SkipResult: FCutsceneSkipResult | — | Cleanup and return to gameplay |
| `SkipCutscene` | — | — | Player-initiated skip (with hold timer) |
| `UpdateSkipHoldProgress` | DeltaSeconds: Float | Float (0-1) | For UI skip progress bar |
| `SetNarrativeMilestone` | Milestone: FCutsceneMilestone | — | Fire flag at correct time |
| `RestoreGameplayState` | — | — | Return camera, enable input, show HUD |
| `CanSkipCutscene` | — | Bool | Checks if skip is available |
| `GetActiveCutscene` | — | DA_CutsceneData | |

### Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|-----------|
| `OnCutscenePlayRequested` | CutsceneData: DA_CutsceneData | Cutscene about to play |
| `OnCutsceneFadeOutStarted` | — | Fade out begins |
| `OnCutsceneFadeInStarted` | — | Fade in begins (after black) |
| `OnCutscenePlaying` | CutsceneData: DA_CutsceneData | Cutscene is actively playing |
| `OnCutsceneMilestoneReached` | Milestone: FCutsceneMilestone | Narrative flag fired |
| `OnCutsceneSkipAvailable` | — | Skip button becomes available |
| `OnCutsceneSkipRequested` | — | Player holding skip |
| `OnCutsceneSkipped` | — | Cutscene was skipped |
| `OnCutsceneCompleted` | CutsceneData: DA_CutsceneData | Cutscene finished (skipped or ended) |

### Blueprint Flow

```
[PlayCutscene: DA_CutsceneData]
  └─► Set bIsPlaying = true
  └─► Broadcast OnCutscenePlayRequested
  └─► Auto-save checkpoint (if configured)
  └─► Apply transition (fade out / letterbox)
  └─► Suppress input: set PlayerController input mode to UI Only
  └─► Hide HUD widgets (disable visibility on HUD parent)
  └─► Spawn LevelSequenceActor from DA_CutsceneData.SequenceSoftReference
  └─► If cinematics camera is in data → blend to it (SetViewTarget with blend)
  └─► Broadcast OnCutsceneFadeInStarted
  └─► Fade in
  └─► Broadcast OnCutscenePlaying
  └─► Set bCanSkip timer (if configured)
  
[OnCutsceneTick: DeltaSeconds]
  └─► Update milestones (check if any FCutsceneMilestone should fire)
  └─► If milestone reached → SetNarrativeMilestone → fire flag via BPC_NarrativeStateSystem
  └─► Update skip hold progress if player holding skip key
  └─► Check if sequence has finished → OnCutsceneEnded

[OnCutsceneEnded: SkipResult]
  └─► Broadcast milestone flags at end time if not already fired
  └─► RestoreGameplayState:
      └─► Blend back to player camera
      └─► Enable player input
      └─► Show HUD
      └─► Destroy LevelSequenceActor
      └─► Remove cinematic camera
  └─► Set bIsPlaying = false
  └─► Broadcast OnCutsceneCompleted

[SkipCutscene]
  └─► If !CanSkipCutscene → return
  └─► Broadcast OnCutsceneSkipped
  └─► Jump to end of sequence (or stop immediately)
  └─► Go to OnCutsceneEnded with SkipResult.bWasSkipped = true
```

### Communications With

| Target System | Method | Why |
|---------------|--------|-----|
| [`BPC_NarrativeStateSystem`](58_BPC_NarrativeStateSystem.md) | Direct | Fire milestone flags during cutscene |
| [`BPC_DialoguePlaybackSystem`](40_BPC_DialoguePlaybackSystem.md) | Direct | Play subtitled dialogue for spoken lines in cutscene |
| [`BPC_CheckpointSystem`](../04-save/34_BPC_CheckpointSystem.md) | Direct | Auto-save before cutscene |
| PlayerController | Direct | Suppress/restore input and view target |
| HUD Widget | Dispatcher | Show/hide HUD |
| [`BPC_TrialScenarioSystem`](43_BPC_TrialScenarioSystem.md) | Direct | Cutscene can trigger scenario start/end |

### Reuse Notes
Cutscene data assets allow designers to configure skip availability, milestone flags, and transition types per cutscene without modifying the system. The milestone system enables narrative flags to fire at exact sequence timecodes for branching logic post-cutscene.