Fighting Game · Guides & deep dives

Sequencer Data Model

The core hierarchy is intentionally simple:

8sections2 minread
Markdown source
On this page

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.