# Sequencer Event Tracks

This document records the `TODOS.phase-72.72.15.1.7` cinematic sequencer event
track contract. Event tracks bind gameplay event triggers to timeline frames so
cinematics can trigger explosion cues, open doors, start rain, and dispatch
other scripted gameplay events.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Event trigger spec: `FV2SequencerEventTriggerSpec`
- Event invocation row: `FV2SequencerEventInvocation`
- Track evaluation: `FV2SequencerEventTrackEvaluation`
- Issue enum: `EV2SequencerEventTrackIssueType`
- Issue struct: `FV2SequencerEventTrackIssue`
- Automation: `V2.Cinematics.Sequencer.EventTracks`
- CI checker: `V2/ue/Tools/check-v2-sequencer-event-tracks.py`

## Trigger Model

`FV2SequencerEventTriggerSpec` stores a stable event id, gameplay event name,
timeline frame, time seconds, payload tag, payload text, payload float,
fire-once flag, and authority flag. It exposes helpers for validation and
frame-crossing dispatch, so large timeline jumps still fire events whose
timestamps were crossed.

`FV2SequencerTrackSpec` now carries `EventTriggers` for
`EV2SequencerTrackType::Event` tracks. This keeps dedicated gameplay events in
the same sequencer track model while preserving the older keyframe-based event
fixture used by data-model and interpolation tests.

## Default Fixture

`BuildDefaultSequencerEventTrack` creates
`Track.Event.CouncilTrial.StageControl`, bound to `Binding.Global.Cinematic`.
The track contains:

- `Event.CouncilTrial.TriggerExplosion` at frame 45, dispatching
  `GameplayEvent.Cinematic.TriggerExplosion` with `Payload.Arena.LeftPyro`.
- `Event.CouncilTrial.OpenCouncilDoor` at frame 90, dispatching
  `GameplayEvent.Cinematic.OpenDoor` with `Payload.Door.CouncilChamber`.
- `Event.CouncilTrial.StartRain` at frame 135, dispatching
  `GameplayEvent.Cinematic.StartRain` with `Payload.Weather.Rain` and payload
  float `0.65`.

## Evaluation

`EvaluateSequencerEventTrack` validates event-track type, binding id, trigger
inventory, event ids, gameplay event names, non-negative timestamps, and
duplicate event ids. At a frame it returns triggered event invocation rows when
the timeline lands on or crosses an event frame. Each invocation carries the
event id, gameplay event name, payload fields, trigger frame, fire-once flag,
and authority flag.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-sequencer-event-tracks.py
```

Adjacent verification should include
`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`.