# V2 Sequencer Authoring Guide

This guide is the author-facing workflow for Phase 72 cinematic sequence
content. It connects the V2 Sequencer runtime data model, editor surfaces,
collaboration workflow, export flow, and validation gates that protect shipped
cinematics.

## Source Of Truth

- Data model contract:
  [SequencerDataModel_V2_Contract.json](../../ue/Content/V2/Cinematics/Sequencer/SequencerDataModel_V2_Contract.json)
- Timeline playback contract:
  [SequencerTimelinePlayback_V2_Contract.json](../../ue/Content/V2/Cinematics/Sequencer/SequencerTimelinePlayback_V2_Contract.json)
- Actor binding contract:
  [SequencerActorBindings_V2_Contract.json](../../ue/Content/V2/Cinematics/Sequencer/SequencerActorBindings_V2_Contract.json)
- Camera track contract:
  [SequencerCameraTracks_V2_Contract.json](../../ue/Content/V2/Cinematics/Sequencer/SequencerCameraTracks_V2_Contract.json)
- Keyframe interpolation contract:
  [SequencerKeyframeInterpolation_V2_Contract.json](../../ue/Content/V2/Cinematics/Sequencer/SequencerKeyframeInterpolation_V2_Contract.json)
- Timeline editor contract:
  [SequencerTimelineEditor_V2_Contract.json](../../ue/Content/V2/Editor/SequencerTimelineEditor/SequencerTimelineEditor_V2_Contract.json)
- Track management contract:
  [SequencerTrackManagement_V2_Contract.json](../../ue/Content/V2/Editor/SequencerTrackManagement/SequencerTrackManagement_V2_Contract.json)
- Multi-user editing contract:
  [SequencerMultiUserEditing_V2_Contract.json](../../ue/Content/V2/Editor/SequencerMultiUserEditing/SequencerMultiUserEditing_V2_Contract.json)
- Render video contract:
  [SequencerRenderVideo_V2_Contract.json](../../ue/Content/V2/Editor/SequencerRenderVideo/SequencerRenderVideo_V2_Contract.json)
- Authoring guide contract:
  [SequencerAuthoringGuide_V2_Contract.json](../../ue/Content/V2/Editor/SequencerAuthoringGuide/SequencerAuthoringGuide_V2_Contract.json)

Runtime data lives in `FV2SequencerSequenceSpec` and editor authoring flows
target the `TimelineVisualizer` surface.

## Sequence Identity

Every sequence needs stable identity before tracks are authored:

| Artifact | Field        | Authoring Rule                                                    |
| -------- | ------------ | ----------------------------------------------------------------- |
| Sequence | `SequenceId` | Stable `Seq.` id. Do not reuse after shipping.                    |
| Binding  | `BindingId`  | Stable actor, component, camera, spawnable, or global binding id. |
| Track    | `TrackId`    | Stable per-track id scoped to the sequence.                       |
| Keyframe | `KeyframeId` | Stable key id scoped to the track.                                |
| Template | `TemplateId` | Stable template id for reusable sequence starts.                  |

Use `TickResolutionFps` and `DurationFrames` deliberately. Prefer 60 fps for
gameplay-adjacent sequences, and only use alternate rates when render, music, or
capture requirements demand it.

## Timeline And Tracks

Author each track with one responsibility. `EV2SequencerTrackType` supports
`Transform`, `Property`, `Camera`, `Animation`, `Audio`, `Event`, and
`SubSequence`. Keep display names readable for review, but treat ids as the
durable references used by tests, save data, collaboration, and analytics.

Track management rules:

- Add tracks through the track-management surface so mute, solo, collapsed
  group, and order state remains deterministic.
- Reorder tracks for review readability without changing stable ids.
- Lock tracks before editing in multi-user sessions.
- Use muted tracks for temporary review comparisons, not for permanent dead
  content.
- Remove unused tracks before final validation.

## Bindings And Cameras

Bindings connect authored data to runtime objects. Treat actor bindings as the
reviewed handoff between authored sequence data and runtime actors. Use entity
bindings for characters, component bindings for specific animated or property
targets, camera bindings for cinematic camera state, spawnable bindings for
authored temporary objects, and global bindings for sequence-wide events.

Camera tracks should include at least one authored camera binding and camera cut
when the sequence is rendered or used for thumbnails. Camera preview and
viewport preview should resolve the active camera before review. Avoid unbound
camera tracks; they make `Saved/SequencerRenders` and
`Saved/SequencerThumbnails` outputs unreliable.

## Keyframes And Curves

Use keyframes for state changes that must be deterministic in playback. Property
tracks use `FV2SequencerKeyframe`; camera tracks use camera keyframes, cuts, and
optional rail camera entries.

Interpolation rules:

- Use `Interpolation.Linear` for mechanical values and audio automation.
- Use `Interpolation.Step` for event-like or discrete values.
- Use `Interpolation.CubicEaseInOut` for camera motion and visible character
  staging unless design asks for a harder move.
- Use custom curve editor presets only when the curve is part of the shot
  direction.

Review the curve editor after moving keyframes. The keyframe interpolation pass
should make timing intent clear before review. Tangent handles and preset curves
should support the shot, not hide timing problems.

## Audio Events And Animation

Animation clips need stable clip ids, skeletal component ids, blend windows,
looping state, playback rate, and root-motion intent. Audio cues need stable cue
ids, sound paths, audio bus ids, start frames, duration, base volume, pitch, and
automation when needed. Event tracks need stable event ids and payload tags that
QA can trigger and inspect.

Do not encode narrative meaning only in timing. Important story beats should
have event payloads, camera cuts, dialogue or bark integration, and review notes
that make the intent visible to tools.

## Sub-Sequences Templates And LOD

Use sub-sequences for reusable shot fragments, repeated camera language, or
large sequences that need isolated review. Use templates to start common
patterns such as dialogue scenes, explosions, and camera fly-throughs, then
rename sequence ids and rebind actors before content review.

LOD and trigger rules:

- Use full playback for first-view or critical-story sequences.
- Use abbreviated playback for repeat viewing only when narrative context is
  preserved.
- Use skip rules only for gameplay-safe cinematic moments.
- Use area, interaction, and gameplay-event triggers with explicit required tags
  and replay safety.

## Editor Workflow

1. Create or instantiate the sequence and set `SequenceId`, display name,
   `TickResolutionFps`, and `DurationFrames`.
2. Add bindings before tracks so tracks can reference durable `BindingId`
   values.
3. Add transform, property, camera, animation, audio, event, and sub-sequence
   tracks as needed.
4. Add keyframes, cuts, audio cues, animation clips, and event triggers.
5. Scrub in the timeline editor and viewport preview.
6. Review curves, hotkeys, undo/redo history, recording-mode captures, and track
   order.
7. Generate a thumbnail from frame `0` for asset browser review.
8. Queue a render to `Saved/SequencerRenders` when video review is required.
9. Run the validation commands in this guide before content review.

## Collaboration And Review

multi-user editing uses `V2.Editor.Sequencer.MultiUserEditing`. Lock a track
before editing it. Release the lock when the edit is ready for review. Remote
presence should show the editor, track owner, revision, and any dirty state.

Merge rules:

- incoming-only track changes can apply automatically.
- Local-only track changes should be kept.
- Identical local and incoming changes are accepted.
- Conflicting local and incoming changes require conflict inspection unless the
  review owner explicitly chooses incoming.
- Stale revisions must be rebased before merge.

Before signoff, confirm undo/redo can restore the review state and that
multi-user conflicts have no blocking rows.

## Export Thumbnails And Playback

Use thumbnail preview for asset browser recognition. It captures the first frame
through the configured render target and writes a PNG under
`Saved/SequencerThumbnails`.

Use render-to-video for review and handoff. MP4 is the default review format;
MOV/ProRes is reserved for high-quality editorial review. Include audio when the
sequence has audio cues, and keep output frame ranges inside the authored
duration.

Playback signoff should cover runtime timeline playback, gameplay blend,
serialization, networking sync, LOD, triggers, and sub-sequence composition when
those systems are present in the authored sequence.

## Review Checklist

Before cinematic content review, confirm:

- `SequenceId`, `BindingId`, `TrackId`, and `KeyframeId` values are stable and
  unique.
- The sequence has positive `TickResolutionFps` and `DurationFrames`.
- Every track has a clear `EV2SequencerTrackType`, display name, and valid
  binding when one is required.
- Camera tracks resolve an active camera for viewport preview, thumbnail
  generation, and render-to-video.
- Curves use approved interpolation ids such as `Interpolation.Linear`,
  `Interpolation.Step`, or `Interpolation.CubicEaseInOut`.
- Audio, event, animation, and sub-sequence tracks use stable ids and valid
  frame ranges.
- Multi-user locks are released or intentionally owned for active review.
- Serialization, gameplay blend, LOD, triggers, and networking behavior are
  valid for the sequence's intended runtime use.
- Thumbnail and video output paths are deterministic.
- CI validation passes without missing references, blocking conflicts, or stale
  documentation.

## Validation Commands

Run these commands after changing Sequencer runtime behavior, editor authoring
surfaces, cinematic content, guide text, or CI wiring:

```bash
python3 V2/ue/Tools/check-v2-sequencer-authoring-guide.py
python3 V2/ue/Tools/check-v2-sequencer-data-model.py
python3 V2/ue/Tools/check-v2-sequencer-timeline-playback.py
python3 V2/ue/Tools/check-v2-sequencer-actor-bindings.py
python3 V2/ue/Tools/check-v2-sequencer-camera-tracks.py
python3 V2/ue/Tools/check-v2-sequencer-animation-clip-tracks.py
python3 V2/ue/Tools/check-v2-sequencer-audio-tracks.py
python3 V2/ue/Tools/check-v2-sequencer-event-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-sub-sequence-composition.py
python3 V2/ue/Tools/check-v2-sequencer-gameplay-blend.py
python3 V2/ue/Tools/check-v2-sequencer-serialization.py
python3 V2/ue/Tools/check-v2-sequencer-lod.py
python3 V2/ue/Tools/check-v2-sequencer-triggers.py
python3 V2/ue/Tools/check-v2-sequencer-networking.py
python3 V2/ue/Tools/check-v2-sequencer-timeline-editor.py
python3 V2/ue/Tools/check-v2-sequencer-track-management.py
python3 V2/ue/Tools/check-v2-sequencer-keyframe-editing.py
python3 V2/ue/Tools/check-v2-sequencer-curve-editor.py
python3 V2/ue/Tools/check-v2-sequencer-viewport-preview.py
python3 V2/ue/Tools/check-v2-sequencer-camera-preview-window.py
python3 V2/ue/Tools/check-v2-sequencer-undo-redo.py
python3 V2/ue/Tools/check-v2-sequencer-hotkeys.py
python3 V2/ue/Tools/check-v2-sequencer-recording-mode.py
python3 V2/ue/Tools/check-v2-sequencer-template-library.py
python3 V2/ue/Tools/check-v2-sequencer-render-video.py
python3 V2/ue/Tools/check-v2-sequencer-thumbnail-preview.py
python3 V2/ue/Tools/check-v2-sequencer-multi-user-editing.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Editor/SequencerAuthoringGuide/SequencerAuthoringGuide_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
pnpm exec prettier --check V2/docs/cinematics/sequencer-authoring-guide.md V2/ue/Content/V2/Editor/SequencerAuthoringGuide/SequencerAuthoringGuide_V2_Contract.json V2/ue/Build/Horde/v2-buildgraph-job.json TODOS/phase-72.md
```