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:
- Cinematic type: full-screen cutscene, in-game camera, or background ambient sequence
- Whether actors bind at runtime or are pre-placed in the level
- Whether camera control must return to the player after playback
- One-shot or looping sequence
- 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 spawnables for transient cutscene-only actors (cinematic-only characters, props). Possessables survive sequence end; spawnables are cleaned up automatically.
// LevelSequenceActor.h — all binding API lives here
// Replace bound actors (preferred: tag-based, resilient to GUID changes)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
/*bAllowBindingsFromAsset=*/ false);
// GUID-based (expose FMovieSceneObjectBindingID via UPROPERTY for editor assignment)
// UPROPERTY(EditAnywhere) FMovieSceneObjectBindingID HeroBindingID;
SeqActor->SetBinding(HeroBindingID, TArray<AActor*>{ HeroActor }, false);
// Append without removing existing bindings
SeqActor->AddBindingByTag(FName("NPC"), NpcActor, /*bAllowBindingsFromAsset=*/ true);
// Remove / reset
SeqActor->RemoveBindingByTag(FName("NPC"), NpcActor);
SeqActor->ResetBinding(HeroBindingID); // revert to asset binding
SeqActor->ResetBindings(); // revert all overrides
// Lookup by tag
FMovieSceneObjectBindingID ID = SeqActor->FindNamedBinding(FName("Hero"));
const TArray<FMovieSceneObjectBindingID>& All = SeqActor->FindNamedBindings(FName("NPC"));
// Inspect what is currently bound
TArray<UObject*> Bound = Player->GetBoundObjects(HeroBindingID);
// FMovieSceneObjectBindingID (MovieSceneObjectBindingID.h):
// Access via public accessors — internal fields are private:
// GetGuid() — FGuid identifying the binding track
// GetRelativeSequenceID() — which sub-sequence holds it (0 = local)
Camera System
ACineCameraActor / UCineCameraComponent
// CineCameraActor.h: UCineCameraComponent* GetCineCameraComponent() const;
// CineCameraComponent.h / CineCameraSettings.h:
// FCameraFilmbackSettings Filmback (SensorWidth, SensorHeight in mm, read-only SensorAspectRatio)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance cm, bSmoothFocusChanges)
// float CurrentFocalLength — Interp, animatable in Sequencer
// float CurrentAperture — f-stop, Interp-animatable
ACineCameraActor* Cam = GetWorld()->SpawnActor<ACineCameraActor>(SpawnTransform);
UCineCameraComponent* CC = Cam->GetCineCameraComponent();
FCameraFilmbackSettings FB;
FB.SensorWidth = 36.0f; FB.SensorHeight = 24.0f; // full-frame 35mm
CC->SetFilmback(FB);
CC->SetCurrentFocalLength(50.0f); // mm
CC->SetCurrentAperture(2.0f); // f-stop
FCameraFocusSettings FS;
FS.FocusMethod = ECameraFocusMethod::Manual; // Manual | Tracking | Disable | DoNotOverride
FS.ManualFocusDistance = 500.0f; // cm
FS.bSmoothFocusChanges = true;
CC->SetFocusSettings(FS);
// Lookat tracking (CineCameraActor.h: FCameraLookatTrackingSettings LookatTrackingSettings)
Cam->LookatTrackingSettings.bEnableLookAtTracking = true;
Cam->LookatTrackingSettings.ActorToTrack = TargetActor;
Cam->LookatTrackingSettings.LookAtTrackingInterpSpeed = 5.0f;
Cam->LookatTrackingSettings.RelativeOffset = FVector(0, 0, 90.f);
// Prevent sequence from overriding gameplay camera (set before Play)
SeqActor->PlaybackSettings.bDisableCameraCuts = true;
// Restore player camera after cutscene (call from OnFinished delegate)
APlayerController* PC = GetWorld()->GetFirstPlayerController();
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
PC->SetIgnoreMoveInput(false);
PC->SetIgnoreLookInput(false);
APlayerCameraManager
APlayerCameraManager (accessed via PlayerController->PlayerCameraManager) manages camera
blending and view target selection for the local player. After a cutscene ends, restore the
gameplay camera explicitly — Sequencer does not do this automatically:
APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager handles blend state; SetViewTargetWithBlend triggers it.
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// The blend is processed each tick inside APlayerCameraManager::UpdateCamera.
Sequencer Events
Event tracks call UFUNCTIONs on objects in the event context.
Default event context: UWorld + ALevelScriptActor.
// Function must be UFUNCTION(BlueprintCallable) on a context object
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void TriggerExplosion()
{
ExplosionSystem->SpawnExplosion(ExplosionLocation);
}
// Trigger C++ code at a specific frame by playing to it (fires all events in range)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(60), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
FMovieSceneEvent
FMovieSceneEvent holds the event endpoint data — the bound function to call when the event
fires. Event tracks are structured as:
UMovieSceneEventTrack— the master track added to a binding or as a master trackUMovieSceneEventTriggerSection— a section containing one or more trigger entriesFMovieSceneEvent— each entry inside the trigger section, pointing to the endpoint function
The endpoint function is resolved at runtime against the event context objects (by default
UWorld and ALevelScriptActor). Director-based events resolve against a
ULevelSequenceDirector subclass instance.
ULevelSequenceDirector — Custom Event Context
ULevelSequenceDirector provides a per-sequence scripting context that receives event track
calls. Subclass it (Blueprint or C++) and assign to the LevelSequence asset's Director Class
property. The Director instance is created when the sequence begins playing and destroyed
when it stops — its lifetime matches the sequence player.
// MySequenceDirector.h
#include "LevelSequenceDirector.h"
#include "MySequenceDirector.generated.h"
UCLASS(Blueprintable)
class UMySequenceDirector : public ULevelSequenceDirector
{
GENERATED_BODY()
public:
// Called from Sequencer event tracks — bind to event key in the Sequencer editor
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnDialogueStart(FName SpeakerTag);
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnCutsceneChoice(int32 ChoiceIndex);
};
// MySequenceDirector.cpp
void UMySequenceDirector::OnDialogueStart(FName SpeakerTag)
{
// Access the sequence player and bound actors from within the Director.
// ULevelSequenceDirector.h: UPROPERTY ULevelSequencePlayer* Player (direct field, no getter)
TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
// Trigger gameplay logic: UI, dialogue system, camera focus, etc.
}
Why Director over Level Script: The Director travels with the sequence asset, not the level. Reusable across maps. Supports per-sequence state (member variables). Level Script events only work when the sequence is placed in that specific level.
MovieScene Tracks
// MovieScene.h — get from the LevelSequence asset
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// Possessables (world actors) — iterate by index
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// Spawnables (sequence-owned actors) — iterate by index
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}
// Master tracks (not bound to any actor)
const TArray<UMovieSceneTrack*>& Masters = MS->GetTracks();
// Tracks on a specific binding
const FMovieSceneBinding* B = MS->FindBinding(SomeGuid);
if (B) { for (UMovieSceneTrack* T : B->GetTracks()) { /* cast to subtype */ } }
| Track Class | Purpose |
|---|---|
UMovieScene3DTransformTrack | Transform animation |
UMovieSceneSkeletalAnimationTrack | Skeletal mesh animation |
UMovieSceneEventTrack | Event triggers |
UMovieSceneAudioTrack | Audio |
UMovieSceneFadeTrack | Screen fade |
UMovieSceneCameraCutTrack | Camera cuts |
UMovieSceneSubTrack | Sub-sequences |
UMovieScenePropertyTrack | Arbitrary UPROPERTY animation (base class) |
All track types require MovieSceneTracks in Build.cs.
Custom tracks: subclass UMovieSceneTrack + UMovieSceneSection for domain-specific
animation data. Register via ISequencerModule::RegisterTrackEditor. This is an advanced
pattern — most needs are met by UMovieScenePropertyTrack subclasses.
UMovieScenePropertyTrack animates arbitrary UPROPERTY values on bound objects. Common
concrete subclasses: UMovieSceneFloatTrack (float properties), UMovieSceneBoolTrack
(bool properties), UMovieSceneColorTrack (FLinearColor / FColor properties). Each creates
sections of the matching type (e.g., UMovieSceneFloatSection) that store a FMovieSceneFloatChannel.
Sub-Sequences
// Add a sub-sequence track to a master UMovieScene
UMovieScene* MasterMS = MasterSequence->GetMovieScene();
UMovieSceneSubTrack* SubTrack = MasterMS->AddTrack<UMovieSceneSubTrack>();
// Add a child sequence — AddSequence(Sequence, StartFrame, Duration)
FFrameRate DisplayRate = MasterMS->GetDisplayRate();
FFrameNumber Start = (2.0 * DisplayRate).FloorToFrame(); // 2 seconds in
int32 Duration = (5.0 * DisplayRate).FloorToFrame().Value; // 5 seconds long
UMovieSceneSubSection* SubSection =
SubTrack->AddSequence(ChildLevelSequence, Start, Duration);
// Configure sub-section timing
SubSection->Parameters.TimeScale = 1.0; // FMovieSceneTimeWarpVariant (double), playback speed multiplier
SubSection->Parameters.bCanLoop = false;
UMovieSceneSubTrack is a singleton master track — AddTrack returns the existing one if already present. Binding IDs inside sub-sequences carry a non-zero SequenceID; use FMovieSceneObjectBindingID::ResolveParentIndex when overriding bindings from the root player. Requires MovieSceneTracks module.
Time Dilation and SlowMo
For SlowMo effects during sequences, use Player->SetPlayRate(0.5f) on the sequence player —
this is independent of UGameplayStatics::SetGlobalTimeDilation and does not affect world
physics or other gameplay systems. Combine with a post-process motion blur intensity increase
for cinematic slow motion without disrupting gameplay state.
Movie Render Queue
// MovieRenderPipelineCore module. Classes:
// UMoviePipelineQueue — holds jobs
// UMoviePipelineExecutorJob — sequence + map + config per job
// UMoviePipelinePrimaryConfig — root settings container
// UMoviePipelineOutputSetting — output path, file name format, frame rate
// Output formats: UMoviePipelineImageSequenceOutput_PNG / _EXR, UMoviePipelineAppleProResOutput
// Render passes: UMoviePipelineDeferredPassBase (final color, world normal, base color, depth)
// Add passes to the PrimaryConfig to capture multiple AOVs per frame
UMoviePipelineQueue* Queue = NewObject<UMoviePipelineQueue>(this);
UMoviePipelineExecutorJob* Job =
Queue->AllocateNewJob(UMoviePipelineExecutorJob::StaticClass());
Job->Sequence = FSoftObjectPath(MySequence);
Job->Map = FSoftObjectPath(GetWorld());
Job->JobName = TEXT("MyRender");
Job->SetConfiguration(NewObject<UMoviePipelinePrimaryConfig>(Job));
// Add pass/output settings to Job->GetConfiguration() as needed.
// Execute the render (editor only — MovieRenderPipelineEditor module)
UMoviePipelineQueueEngineSubsystem* QueueSubsystem =
GEngine->GetEngineSubsystem<UMoviePipelineQueueEngineSubsystem>();
QueueSubsystem->RenderQueueWithExecutor(UMoviePipelineInProcessExecutor::StaticClass());
// For runtime/non-editor rendering, implement UMoviePipelineExecutorBase instead.
Common Mistakes
Binding after Play: Overrides applied after Play() miss frame 0.
Always SetBinding* before Play().
Multiplayer camera cuts: Camera cuts only affect the local client.
Use SeqActor->SetReplicatePlayback(true) for server-driven sync.
Camera not returning after cutscene: Sequencer does not auto-restore the player camera.
Subscribe to OnFinished and call SetViewTargetWithBlend + re-enable input.
GC of spawned sequence actor: CreateLevelSequencePlayer returns a raw pointer.
Store OutActor in a UPROPERTY() member to prevent garbage collection.
Skipping mid-sequence: Call SetCompletionModeOverride(ForceRestoreState) before Stop()
so actors return to their pre-sequence state.
PIE timing: Avoid wall-clock assumptions; use GetCurrentTime() frame numbers.
Deprecated direct property: SeqActor->SequencePlayer is deprecated since UE 5.4.
Use SeqActor->GetSequencePlayer().
Wrong player instance: Calling Play() on a stale or mismatched ULevelSequencePlayer
pointer (e.g., from a different ALevelSequenceActor in the level) produces no visible effect
or animates the wrong actors. Always retrieve the player from the specific ALevelSequenceActor
that owns the sequence you intend to drive.
Related Skills
ue-actor-component-architecture— actor spawning and component setup for bound actorsue-animation-system— skeletal animation tracks, AnimMontage integration in Sequencerue-cpp-foundations— delegate patterns,UFUNCTION,UPROPERTYue-gameplay-framework— PlayerController camera restoration, GameMode flow