# Sequencer Property Tracks

This document records the `TODOS.phase-72.72.15.1.4` cinematic sequencer
property-track contract. Property tracks animate reflected properties through a
stable `PropertyPath`, binding id, reflected property metadata, typed keyframes,
and the existing interpolation system.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Property value enum: `EV2SequencerPropertyValueType`
- Property issue enum: `EV2SequencerPropertyTrackIssueType`
- Reflected property spec: `FV2SequencerReflectedPropertySpec`
- Property evaluation: `FV2SequencerPropertyTrackEvaluation`
- Property issue: `FV2SequencerPropertyTrackIssue`
- Automation: `V2.Cinematics.Sequencer.PropertyTracks`
- CI checker: `V2/ue/Tools/check-v2-sequencer-property-tracks.py`

## Reflected Property Metadata

`FV2SequencerReflectedPropertySpec` declares the property path, reflected
property name, optional component id, value type, enum type name, and
reflected/writable/animatable flags. A spec is valid only when it names a
reflected property path and points to a writable animatable property. Enum
property tracks must also declare `EnumTypeName`.

## Supported Property Types

The default property-track fixture covers the required reflected property
families:

- Transform: `Track.Property.Cassia.Transform` animates `Transform.Location`.
- Color: `Track.Property.Cassia.EmissiveTint` animates `Material.EmissiveTint`.
- Float: `Track.Property.Cassia.Opacity` animates `Material.Opacity`.
- Bool: `Track.Property.Cassia.Hidden` animates `Actor.bHiddenInGame`.
- Enum: `Track.Property.Cassia.CombatStance` animates `Combat.Stance` with
  `EV2CombatStance` values.

`BuildSequencerPropertyKeyframe` adds color and enum payloads to the existing
keyframe model without changing older keyframe builders. Bool and enum tracks
use step interpolation so discrete reflected properties do not drift between
authored values.

## Evaluation

`EvaluateSequencerPropertyTrack` verifies that a track is a property-compatible
track, resolves reflected property metadata, evaluates keyframe interpolation at
the requested frame, checks that the resulting keyframe value type matches the
reflected property type, and returns a typed
`FV2SequencerPropertyTrackEvaluation`.

Validation issues cover non-property tracks, missing property paths, missing
reflected metadata, empty tracks, interpolation failures, unsupported value
types, missing enum type names, and missing enum values.

## Verification

Run:

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

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