# Sequencer Gameplay Blend

This document records the `TODOS.phase-72.72.15.1.11` cinematic sequencer
gameplay blend contract. Gameplay blends fade from gameplay camera to cinematic
camera and back while carrying explicit control-state windows to maintain player
control state through the transition.

The default fixture is designed to maintain player control state during camera
ownership changes instead of leaving input state implicit.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Control state spec: `FV2SequencerGameplayControlStateSpec`
- Blend spec: `FV2SequencerGameplayBlendSpec`
- Blend evaluation: `FV2SequencerGameplayBlendEvaluation`
- Issue enum: `EV2SequencerGameplayBlendIssueType`
- Issue struct: `FV2SequencerGameplayBlendIssue`
- Automation: `V2.Cinematics.Sequencer.GameplayBlend`
- CI checker: `V2/ue/Tools/check-v2-sequencer-gameplay-blend.py`

## Blend Model

`FV2SequencerGameplayBlendSpec` stores gameplay and cinematic camera binding
ids, blend-in and blend-out frame windows, a curve id, gameplay camera restore
intent, and whether player control state must be maintained. It evaluates a
camera blend alpha from `0.0` to `1.0` during blend-in, holds the cinematic
camera at `1.0`, and fades back to `0.0` during blend-out.

`FV2SequencerGameplayControlStateSpec` records input flags for each frame
window. This keeps player movement, camera input, and pause state explicit while
the cinematic camera owns the view.

## Default Fixture

`BuildDefaultSequencerGameplayBlend` creates
`Blend.GameplayToCinematic.CouncilIntro`, fading from `Binding.Camera.Gameplay`
to `Binding.Camera.Hero`:

- Blend-in runs from frame `0` through `24`; frame `12` evaluates alpha `0.5`.
- `ControlState.Gameplay.BlendIn` keeps movement input on while suppressing
  camera input during the transition.
- `ControlState.Cinematic.Locked` runs from frame `24` through `156` and
  disables player, camera, and movement input for the cinematic hold.
- Blend-out runs from frame `156` through `180`; frame `168` evaluates alpha
  `0.5`.
- `ControlState.Gameplay.Restore` restores player, camera, and movement input
  during blend-out.

## Validation

`EvaluateSequencerGameplayBlend` reports blocking issues for missing blend ids,
missing gameplay or cinematic camera binding ids, invalid or overlapping blend
frame windows, missing control state ids, duplicate control state ids, invalid
control state ranges, and missing active control state windows when
`bMaintainPlayerControlState` is enabled.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-sequencer-gameplay-blend.py
```

Adjacent verification should include
`python3 V2/ue/Tools/check-v2-sequencer-sub-sequence-composition.py`,
`python3 V2/ue/Tools/check-v2-sequencer-actor-bindings.py`,
`python3 V2/ue/Tools/check-v2-sequencer-camera-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-event-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-audio-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-animation-clip-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-property-tracks.py`,
`python3 V2/ue/Tools/check-v2-sequencer-keyframe-interpolation.py`,
`python3 V2/ue/Tools/check-v2-sequencer-timeline-playback.py`,
`python3 V2/ue/Tools/check-v2-sequencer-data-model.py`, and
`python3 V2/ue/Tools/check-v2-cinematics-module.py`.