# Sequencer Animation Clip Tracks

This document records the `TODOS.phase-72.72.15.1.5` cinematic sequencer
animation clip track contract. Animation clip tracks bind a skeletal mesh
component to one or more animation clips, trigger those clips from timeline
frames, and evaluate blend-in/blend-out weights for overlap and transitions.

## Runtime Ownership

- Runtime module: `V2Cinematics`
- Clip spec: `FV2SequencerAnimationClipSpec`
- Clip playback row: `FV2SequencerAnimationClipPlayback`
- Track evaluation: `FV2SequencerAnimationClipTrackEvaluation`
- Issue enum: `EV2SequencerAnimationClipIssueType`
- Issue struct: `FV2SequencerAnimationClipIssue`
- Automation: `V2.Cinematics.Sequencer.AnimationClipTracks`
- CI checker: `V2/ue/Tools/check-v2-sequencer-animation-clip-tracks.py`

## Clip Model

`FV2SequencerAnimationClipSpec` stores a stable clip id, animation asset path,
start frame, duration frames, blend-in frames, blend-out frames, playback rate,
slot name, looping flag, and root-motion flag. It exposes helpers for end frame,
frame containment, blend weight, and validation.

`FV2SequencerTrackSpec` now carries `SkeletalMeshComponentId` and
`AnimationClips` for `EV2SequencerTrackType::Animation` tracks. This keeps
animation clips in the same track hierarchy as keyframes, property tracks, and
playback.

## Default Fixture

`BuildDefaultSequencerAnimationClipTrack` creates `Track.Animation.Cassia.Body`,
bound to `Binding.Actor.Cassia` and `Component.Mesh.Body`. The track contains:

- `Clip.Cassia.CouncilIdle`, starting at frame 0 with 12-frame blend in/out.
- `Clip.Cassia.CinematicReady`, starting at frame 84 with 12-frame blend in,
  18-frame blend out, and root motion enabled.

The overlap around frame 90 evaluates both clips as active so callers can blend
idle out while blending cinematic-ready in.

## Evaluation

`EvaluateSequencerAnimationClipTrack` validates animation-track type, binding
id, skeletal mesh component id, clip inventory, clip asset paths, frame ranges,
playback rates, and blend windows. At a frame it returns active clip playback
rows with local frame, blend weight, slot, playback rate, trigger flag,
blend-in/blend-out flags, looping state, and root-motion state.

## Verification

Run:

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

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