/ue-sequencer-cinematics

name: ue-sequencer-cinematics
description: "Use this skill when working with Sequencer, LevelSequence, cutscene, cinematic, camera, movie scene, sequencer event, or Movie Render Queue in Unreal Engine. See references/sequencer-patterns.md for dialogue cutscene, in-game camera, and scripted event patterns. For animation playback, see ue-animation-system."
metadata:
  version: 1.0.0

Skill: ue-sequencer-cinematics

You are an expert in Unreal Engine's Sequencer and cinematic systems.

Context Check

Read `.agents/ue-project-context.md` before writing any cinematic code for:

• Target UE version (API availability varies — SequencePlayer property deprecated in 5.4+)
• Cinematic requirements (cutscenes, in-game cameras, offline rendering)
• Multiplayer context (sequence replication behavior differs)
• Build.cs modules already declared

Information Gathering

Ask for: 1. Cinematic type: full-screen cutscene, in-game camera, or background ambient sequence 2. Whether actors bind at runtime or are pre-placed in the level 3. Whether camera control must return to the player after playback 4. One-shot or looping sequence 5. Real-time gameplay or offline Movie Render Queue output

---

Build.cs Modules

PublicDependencyModuleNames.AddRange(new string[]
{
    "LevelSequence", "MovieScene", "CinematicCamera",
});
// Offline rendering only:
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");

---

Playing Level Sequences

ALevelSequenceActor — World-Placed

`ALevelSequenceActor` owns the player. Use `GetSequencePlayer()` — the direct `SequencePlayer` property is deprecated since UE 5.4.

// LevelSequenceActor.h: ULevelSequencePlayer* GetSequencePlayer() const;
ULevelSequencePlayer* Player = SeqActor->GetSequencePlayer();
if (Player) { Player->Play(); }

ULevelSequencePlayer::CreateLevelSequencePlayer — Runtime Spawn

// LevelSequencePlayer.h:
// static ULevelSequencePlayer* CreateLevelSequencePlayer(
//     UObject* WorldContextObject, ULevelSequence*, FMovieSceneSequencePlaybackSettings,
//     ALevelSequenceActor*& OutActor);

FMovieSceneSequencePlaybackSettings Settings;
Settings.bAutoPlay              = false;
Settings.PlayRate               = 1.0f;
Settings.LoopCount.Value        = 0;       // 0=once, -1=infinite
Settings.bDisableMovementInput  = true;
Settings.bDisableLookAtInput    = true;
Settings.bHidePlayer            = false;
Settings.bHideHud               = false;
Settings.bDisableCameraCuts     = false;
Settings.bPauseAtEnd            = false;
Settings.FinishCompletionStateOverride =
    EMovieSceneCompletionModeOverride::ForceRestoreState; // safe for skippable cutscenes

ALevelSequenceActor* OutActor = nullptr;
ULevelSequencePlayer* Player  = ULevelSequencePlayer::CreateLevelSequencePlayer(
    this, Sequence, Settings, OutActor);

// Store OutActor in a UPROPERTY to prevent GC
ActiveSequenceActor = OutActor;

if (Player)
{
    Player->OnFinished.AddDynamic(this, &AMyClass::OnCutsceneFinished);
    Player->Play();
}

Play Control (UMovieSceneSequencePlayer base)

// MovieSceneSequencePlayer.h
Player->Play();
Player->PlayReverse();
Player->PlayLooping(-1);       // -1 = infinite loops
Player->Pause();
Player->Stop();                // moves cursor to end, fires OnStop
Player->StopAtCurrentTime();
Player->GoToEndAndStop();
Player->SetPlayRate(0.5f);     // negative = reverse

// Jump to frame (skips events between current and target)
// Blueprint exposes this as GoToFrame. In C++, use SetPlaybackPosition with Jump.
Player->SetPlaybackPosition(
    FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump));

// Play through to frame (triggers all events along the way)
Player->PlayTo(
    FMovieSceneSequencePlaybackParams(FFrameTime(240), EUpdatePositionMethod::Play),
    FMovieSceneSequencePlayToParams());

// Restrict play range
Player->SetFrameRange(0, 60);           // frames 0–60
Player->SetTimeRange(0.0f, 2.5f);       // seconds

// State query
bool bPlaying = Player->IsPlaying();
FQualifiedFrameTime Now = Player->GetCurrentTime();
FQualifiedFrameTime Dur = Player->GetDuration();

// Delegates (bind before Play)
Player->OnFinished.AddDynamic(this, &UMyClass::OnSeqFinished);
Player->OnPlay.AddDynamic(this, &UMyClass::OnSeqPlay);
Player->OnStop.AddDynamic(this, &UMyClass::OnSeqStop);
Player->OnNativeFinished.BindUObject(this, &UMyClass::OnNativeFinished); // non-dynamic

// Camera cut event (LevelSequencePlayer.h)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLevelSequencePlayerCameraCutEvent, UCameraComponent*, CameraComponent)
LsPlayer->OnCameraCut.AddDynamic(this, &UMyClass::OnCameraCut);

// Restore state on early stop (skippable cutscene)
Player->SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState);
Player->Stop();

// Sub-sequence snapshot
FLevelSequencePlayerSnapshot Snap;
Player->TakeFrameSnapshot(Snap);
// Snap.CurrentShotName, Snap.RootTime, Snap.CameraComponent, Snap.ActiveShot

---

Actor Binding

Tag bindings in Sequencer (right-click object binding -> Tags...) then override at runtime. **Always bind before calling `Play()`.**

Spawnables vs Possessables

**Possessables** bind to pre-existing world actors (placed in level or spawned by gameplay). **Spawnables** are actors the sequence itself creates and destroys.

// Spawnable: sequence owns the actor lifecycle
// Set in Sequencer editor: right-click actor track → "Change to Spawnable"
// At runtime, actor spawns when sequence reaches its range, despawns when exiting

// Dynamic possessable: bind a gameplay-spawned actor to a sequence track
// Create the binding ID in the editor, then override at runtime:
FMovieSceneObjectBindingID BindingID = /* from sequence editor */;
ALevelSequenceActor* SeqActor = /* your sequence actor */;
SeqActor->SetBinding(BindingID, {SpawnedActor});

**Why this matters**: Use possessables for persistent world actors (doors, elevators) and s