# Sequencer Data Model

This document records the `TODOS.phase-72.72.15.1.1` cinematic sequencer data
model contract. The runtime model is owned by `V2Cinematics` and keeps the
authored hierarchy explicit: a sequence contains tracks, each track contains
keyframes, and every track binds to an entity, component, camera, spawnable, or
global context plus an optional property path.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Sequence struct: `FV2SequencerSequenceSpec`
- Binding struct: `FV2SequencerBindingSpec`
- Track struct: `FV2SequencerTrackSpec`
- Keyframe struct: `FV2SequencerKeyframe`
- Validation result: `FV2SequencerDataModelValidationResult`
- Blueprint builders: `BuildSequencerBindingSpec`, `BuildSequencerKeyframe`,
  `BuildSequencerTrackSpec`, `BuildSequencerSequenceSpec`, and
  `BuildDefaultSequencerDataModel`
- Validator: `ValidateSequencerDataModel`
- Automation: `V2.Cinematics.Sequencer.DataModel`
- CI checker: `V2/ue/Tools/check-v2-sequencer-data-model.py`

## Sequence Model

The core hierarchy is intentionally simple:

- A sequence contains tracks.
- Each track contains keyframes.
- Every track binds to an entity, component, camera, spawnable, or global
  context.

`FV2SequencerSequenceSpec` stores a stable `SequenceId`, display name, tick
resolution, duration, binding list, track list, and sequence tags. It exposes
`CountKeyframes`, `FindBinding`, and `FindTrack` helpers so editor and runtime
systems can inspect the authored hierarchy without duplicating lookup logic.

## Binding Model

`FV2SequencerBindingSpec` defines the binding id, binding kind, entity id,
component id, spawnable class path, binding path, and rebindability. Entity and
camera bindings require an entity id, component bindings require entity and
component ids, spawnable bindings require a class path, and global bindings are
valid for timeline-wide event or context tracks.

## Track Model

`FV2SequencerTrackSpec` stores a track id, display name, track type, binding id,
property path, keyframe array, mute/lock flags, and rebindability. Transform,
property, and camera tracks are treated as property tracks and must include a
property path such as `Transform.Location` or `CineCamera.FieldOfView`.

## Keyframe Model

`FV2SequencerKeyframe` stores a stable keyframe id, frame number, time in
seconds, typed value discriminator, typed value fields, and interpolation id.
The initial model supports float, vector, rotator, bool, name, and string values
so later interpolation, property, audio, camera, and event work can reuse one
authored timeline shape.

## Validation

`ValidateSequencerDataModel` rejects missing sequence ids, invalid frame rates
or durations, missing or duplicate bindings, missing or duplicate tracks,
unknown track bindings, missing property paths, empty tracks, invalid keyframe
ids, out-of-range frames, duplicate or unsorted frame numbers, and untyped
keyframe values. Validation issues use `EV2SequencerDataModelIssueType` and
store sequence, track, binding, and keyframe ids for precise editor feedback.

## Default Fixture

`BuildDefaultSequencerDataModel` seeds `Seq.DataModel.CouncilIntro` with three
bindings and three tracks:

- `Binding.Actor.Cassia` drives `Track.Cassia.Transform` on
  `Transform.Location`.
- `Binding.Camera.Hero` drives `Track.HeroCamera.FOV` on
  `CineCamera.FieldOfView`.
- `Binding.Global.Cinematic` drives `Track.Global.Event` on `GameplayEvent`.

The fixture contains six keyframes and validates cleanly, while the automation
spec also constructs broken sequences to prove validation catches malformed
bindings, property paths, duplicate frames, unsorted frames, and missing typed
values.

## Verification

Run:

```bash
python3 V2/ue/Tools/check-v2-sequencer-data-model.py
```

Adjacent cinematic verification should also include
`python3 V2/ue/Tools/check-v2-cinematics-module.py` so the module inventory and
automation spec coverage remain in sync.