UE Sequencer and Cinematics
Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".
Sequencer spans three runtime modules plus a plugin. MovieScene holds the data model and the player base class, MovieSceneTracks holds the concrete track and section types, LevelSequence holds the asset, actor, player and director, and CinematicCamera holds the cine camera and camera rigs. Offline rendering lives in the Movie Render Queue plugin (MovieRenderPipelineCore for runtime, MovieRenderPipelineEditor for the editor queue UI); it is disabled by default and must be enabled in the .uproject.
Context
Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.
Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.
Build.cs Modules
Runtime vs Editor
Authoring a sequence is an editor operation. Shipping game code plays and re-binds sequences; it does not build them.
UMovieScene::AddTrack and UMovieSceneSubTrack::AddSequence do compile into runtime builds, but they mutate the sequence asset. Call them only from editor tooling or commandlets — a cooked ULevelSequence must not be edited in a shipped game.
Playing a Level Sequence
From a placed ALevelSequenceActor
Useful ALevelSequenceActor members: PlaybackSettings, LevelSequenceAsset, BindingOverrides, DefaultInstanceData, bOverrideInstanceData, bReplicatePlayback, GetSequence(), SetSequence(), SetReplicatePlayback(). Auto-play is PlaybackSettings.bAutoPlay; the actor's own bAutoPlay field no longer exists. AReplicatedLevelSequenceActor is a subclass that is always net-relevant.
Spawning a player at runtime
Playback control
EUpdatePositionMethod is Play, Jump or Scrub. FMovieSceneSequencePlaybackParams has constructors taking FFrameTime, float seconds, an FString marked-frame name, or an FTimecode.
Delegates
OnFinished fires only when playback ends naturally (a natural end fires OnStop too); an explicit Stop() fires only OnStop. Bind before Play().
Binding Actors at Runtime
A possessable resolves to an actor that already exists in the level. A spawnable is created and destroyed by the sequence itself. Possessables outlive the sequence; spawnables do not. Runtime overrides apply to possessables.
Tag the object binding in the Sequencer editor (right-click the binding, then Tags), and override by tag from C++ — tags survive re-binding, GUIDs do not.
FMovieSceneObjectBindingID keeps its guid and sequence id private. Read them with GetGuid(), GetRelativeSequenceID() and IsFixedBinding(); move an ID across a sub-sequence hierarchy with ResolveToFixed(), then ConvertToRelative() on the resulting UE::MovieScene::FFixedObjectBindingID (ConvertToRelative is not a member of FMovieSceneObjectBindingID, MovieSceneObjectBindingID.h:113-160,341). Never assign the fields directly.
Relocating a whole sequence
ALevelSequenceActor implements IMovieScenePlaybackClient::GetInstanceData. Set bOverrideInstanceData and supply a UDefaultLevelSequenceInstanceData to offset every absolute transform section, so one authored cutscene can play anywhere in the world.
Sequencer Event Tracks
An event key does not call a loose global function. FMovieSceneEvent stores a compiled UFunction pointer, and the evaluation system calls it on the sequence's director instance — an object of the class in ULevelSequence::DirectorClass, which derives from ULevelSequenceDirector. The UFUNCTION must therefore be a member of a ULevelSequenceDirector subclass or of its Director Blueprint.
Rules the engine enforces:
MovieSceneEvent.h:70— the endpoint takes no parameters, or exactly one pass-by-value object/interface parameter, and returns nothing.- When the event track sits under an object binding, the bound object arrives as that single parameter.
- On a root track, a parameterless endpoint runs once on the director; an endpoint with the object parameter runs once per global event context (
MovieSceneEventSystems.cpp:206-213).ULevelSequencePlayer::GetEventContextsreturns the persistent level'sALevelScriptActorplus one per streaming level — not theUWorld. - In a non-game world (the Sequencer preview), the event is skipped unless the
UFUNCTIONcarriesCallInEditor.
To attach it: open the Level Sequence, open its Director Blueprint from the Sequencer toolbar, and reparent that Blueprint to UMyCinematicDirector (Class Settings, Parent Class). Sequencer compiles the Blueprint into ULevelSequence::DirectorClass; one director instance is created per sequence during evaluation, and ULevelSequenceDirector::Player points at the owning player. ULevelSequenceDirector also exposes GetBoundObject, GetBoundActor, GetBoundActors, GetSequence, GetCurrentTime, GetRootSequenceTime and a BlueprintImplementableEvent OnCreated.
The track classes involved are UMovieSceneEventTrack (with bFireEventsWhenForwards), UMovieSceneEventTriggerSection for one-shot keys and UMovieSceneEventRepeaterSection for a key that fires on every pass. Seeking with EUpdatePositionMethod::Jump skips every event in between; use PlayTo when the events must fire.
MovieScene Data Model
UMovieScenePropertyTrack subclasses drive a named UPROPERTY marked Interp: UMovieSceneFloatTrack produces UMovieSceneFloatSection, which stores an FMovieSceneFloatChannel; UMovieSceneBoolTrack and UMovieSceneColorTrack follow the same shape. UMovieSceneSubTrack and UMovieSceneSubSection live in MovieScene, not MovieSceneTracks.
Sub-section offsets and durations are in tick-resolution frames, not display-rate frames. UE::MovieScene::DiscreteSize, DiscreteInclusiveLower and DiscreteExclusiveUpper in MovieSceneTimeHelpers.h turn a TRange<FFrameNumber> into frame counts.
Cine Cameras and Camera Rigs
This section covers cameras a sequence drives. Gameplay cameras, camera modifiers, camera shakes and view-target blending belong to ue-gameplay-cameras.
CurrentFocusDistance and CurrentHorizontalFOV are read-only; query the field of view with GetHorizontalFieldOfView() and GetVerticalFieldOfView(). Presets go through SetFilmbackPresetByName, SetLensPresetByName and SetCropPresetByName.
Attach a camera to a rig and key the rig's Interp properties in Sequencer instead of hand-animating the camera transform:
Both rigs override GetDefaultAttachComponent(), so attaching the camera as a child puts it on the correct mount.
Movie Render Graph
Movie Render Graph is production-ready in 5.8 and is the path to prefer for new work. A UMovieGraphConfig is a node graph of UMovieGraphNode subclasses (UMovieGraphSettingNode for settings, UMovieGraphRenderPassNode for passes, UMovieGraphGlobalOutputSettingNode for resolution and output paths); UMovieGraphPipeline executes it through Initialize(UMoviePipelineExecutorJob*, const FMovieGraphInitConfig&).
Runtime rendering goes through UMoviePipelineQueueEngineSubsystem, a UEngineSubsystem in MovieRenderPipelineCore. The editor-facing UMoviePipelineQueueSubsystem is a UEditorSubsystem in MovieRenderPipelineEditor and cannot be referenced from runtime code — doing so breaks a packaged build.
AllocateJob clears the queue, so it renders exactly one job; for a batch call GetQueue()->AllocateNewJob(UMoviePipelineExecutorJob::StaticClass()) per job and then RenderQueueWithExecutor(UMoviePipelineInProcessExecutor::StaticClass()). Custom executors subclass UMoviePipelineExecutorBase (override Execute_Implementation and IsRendering_Implementation) or UMoviePipelineLinearExecutorBase, which already walks the queue and leaves Start(const UMoviePipelineExecutorJob*) to you.
Render layers are a world feature: UMovieGraphRenderLayerSubsystem is a UWorldSubsystem reached with UMovieGraphRenderLayerSubsystem::GetFromWorld(World), holding UMovieGraphRenderLayer objects. Add modifiers with UMovieGraphRenderLayer::AddLayerModifier(UMovieGraphModifierBase*), read them with GetLayerModifiers() (Blueprint only — not exported from the MinimalAPI class, Graph/MovieGraphRenderLayerSubsystem.h:1216), drop them with RemoveLayerModifier(), and switch layers with SetActiveRenderLayerByName or ClearActiveRenderLayer.
Legacy Movie Render Queue — still shipped and supported, but not the default for new graphs. UMoviePipeline is the executing object, configured by a UMoviePipelinePrimaryConfig holding UMoviePipelineSetting objects, reached with FindOrAddSettingByClass / FindSettingByClass. UMoviePipelineOutputSetting lives in MovieRenderPipelineCore (OutputDirectory, FileNameFormat, OutputResolution, bUseCustomFrameRate, OutputFrameRate, ZeroPadFrameNumbers); the passes and containers (UMoviePipelineDeferredPassBase, UMoviePipelineImageSequenceOutput_PNG, UMoviePipelineImageSequenceOutput_EXR) live in MovieRenderPipelineRenderPasses, which must be added to Build.cs separately. A job is either graph-configured (SetGraphPreset, IsUsingGraphConfiguration()) or legacy-configured (SetConfiguration, IsUsingBasicConfiguration()) — never both.
DaySequence (Experimental in 5.8) builds on MovieScene for time-of-day; it is a separate asset type and the APIs above do not transfer to it unchanged.
Deprecated — do not use
Common Mistakes
UFUNCTION on a free function for an event track: a UFUNCTION is only legal inside a UCLASS or USTRUCT body, and Sequencer calls event endpoints on the director instance. Put the endpoint on a ULevelSequenceDirector subclass, with no parameters or one object parameter.
Endpoint with the wrong signature: void Foo(FName Tag, int32 Index) will never bind. The engine accepts no parameters, or one pass-by-value object/interface parameter, and no return value.
Nothing fires in the Sequencer preview: non-game worlds skip endpoints whose UFUNCTION lacks CallInEditor.
Binding after Play(): frame 0 has already evaluated against the asset binding. Call SetBindingByTag or SetBinding on the ALevelSequenceActor before Play().
Losing the spawned actor: CreateLevelSequencePlayer hands back a raw ALevelSequenceActor*. Store it and the player in UPROPERTY() members or they are garbage collected mid-cutscene.
Camera never returns to the player: the camera cut track restores the previous view target only when its section resolves to Restore State (Level Sequences default to it, DefaultCompletionMode=RestoreState in BaseEngine.ini; restore in MovieSceneCameraCutGameHandler.cpp:115-124), and cinematic mode is undone on stop (LevelSequencePlayer.cpp:177). With a Keep State section, ForceKeepState or bPauseAtEnd, handle OnFinished and call PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic) yourself.
Skipping leaves actors mid-pose: set Settings.FinishCompletionStateOverride = EMovieSceneCompletionModeOverride::ForceRestoreState, or call SetCompletionModeOverride, before Stop().
Touching UMoviePipelineQueueSubsystem from game code: it is a UEditorSubsystem in MovieRenderPipelineEditor. Runtime renders use UMoviePipelineQueueEngineSubsystem from MovieRenderPipelineCore.
Mixing graph and legacy config on one job: SetGraphPreset and SetConfiguration are mutually exclusive. Check IsUsingGraphConfiguration() before assuming GetConfiguration() is valid.
Frame-rate confusion: SetFrameRange uses display-rate frames, while UMovieSceneSubSection offsets and UMovieScene::GetPlaybackRange use tick-resolution frames. Convert with GetDisplayRate() and GetTickResolution().
Assuming camera cuts replicate: cuts are evaluated per client. Use SetReplicatePlayback(true), or AReplicatedLevelSequenceActor, so the server drives playback time and each client applies its own cut.
Related Skills
ue-animation-system— skeletal animation assets, montages and anim notifies that sequence animation tracks playue-gameplay-cameras— gameplay cameras, camera modifiers, camera shakes and view-target blending outside Sequencerue-audio-system— the sound assets, submixes and attenuation behind sequence audio tracksue-niagara-effects— particle systems a cinematic triggers or that a sequence keysue-materials-rendering— post process, Lumen and material setup that render passes captureue-actor-component-architecture— spawning and owning the actors a sequence possessesue-world-level-streaming— streaming levels in before a cutscene and Data Layer state during a render


