在 Unreal Engine 中用 Sequencer…

在 UE 中创建、播放和控制 LevelSequence 过场动画，处理 Actor 绑定、相机切换、事件触发与 Movie Render Queue 离线渲染。

适用场景

解决思路

1. 写任何 cinematic 代码前先读 .agents/ue-project-context.md，确认目标 UE 版本（5.4+ 中 SequencePlayer 属性已废弃）、cinematic 需求（过场/游戏内相机/离线渲染）、多人上下文和已声明的 Build.cs 模块。
2. 先向需求方确认：cinematic 类型（全屏过场、游戏内相机还是背景环境序列）、Actor 是运行时绑定还是预先放置在关卡中、播放后相机控制是否需归还玩家、一次性还是循环序列、实时游戏还是离线 Movie Render Queue 输出。
3. 在 Build.cs 中添加依赖模块：PublicDependencyModuleNames 加入 "LevelSequence"、"MovieScene"、"CinematicCamera"；仅离线渲染时 PrivateDependencyModuleNames 加入 "MovieRenderPipelineCore"。
4. 对世界放置的 ALevelSequenceActor，用 GetSequencePlayer() 获取播放器（不要用 5.4 起废弃的 SequencePlayer 属性），再调用 Player->Play()。
5. 运行时创建播放器用 ULevelSequencePlayer::CreateLevelSequencePlayer，配置 FMovieSceneSequencePlaybackSettings（bAutoPlay、PlayRate、LoopCount.Value 0=一次/-1=无限、bDisableMovementInput、bDisableLookAtInput、bHidePlayer、bHideHud、bDisableCameraCuts、bPauseAtEnd、FinishCompletionStateOverride 设为 ForceRestoreState 以支持可跳过过场），并把返回的 OutActor 存入 UPROPERTY 防止 GC。
6. 播放控制使用 UMovieSceneSequencePlayer 基类 API：Play、PlayReverse、PlayLooping(-1)、Pause、Stop、StopAtCurrentTime、GoToEndAndStop、SetPlayRate(0.5f)（负值为倒放）。
7. 跳帧用 SetPlaybackPosition(FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump))（会跳过中间事件）；要触发沿途所有事件用 PlayTo(..., EUpdatePositionMethod::Play, FMovieSceneSequencePlayToParams())。
8. 用 SetFrameRange(0, 60) 或 SetTimeRange(0.0f, 2.5f) 限制播放范围；用 IsPlaying()、GetCurrentTime()、GetDuration() 查询状态。
9. 在 Play 之前绑定委托：OnFinished、OnPlay、OnStop（AddDynamic）、OnNativeFinished（BindUObject），以及 OnCameraCut（FOnLevelSequencePlayerCameraCutEvent）。
10. 可跳过过场提前停止时，先 SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState) 再 Stop()，让 Actor 恢复到序列前状态；用 TakeFrameSnapshot(FLevelSequencePlayerSnapshot) 获取 CurrentShotName、RootTime、CameraComponent、ActiveShot 等子序列快照。
11. 在 Sequencer 中给对象绑定打 Tag，运行时用 SetBindingByTag(FName("Hero"), {HeroActor}, false) 覆盖绑定（比 GUID 更抗变更）；也可用 SetBinding(HeroBindingID, ...)、AddBindingByTag、RemoveBindingByTag、ResetBinding、ResetBindings 管理绑定。
12. 用 FindNamedBinding / FindNamedBindings 按 Tag 查找绑定 ID，用 Player->GetBoundObjects(BindingID) 查看当前绑定的对象；FMovieSceneObjectBindingID 通过 GetGuid() 和 GetRelativeSequenceID() 访问（内部字段为私有）。
13. 区分 Possessable 与 Spawnable：持久世界 Actor（门、电梯）用 Possessable，过场专用临时 Actor 用 Spawnable（序列自动生成和销毁）；运行时生成的 Actor 可通过 SetBinding 绑定到编辑器创建的 BindingID。
14. 所有绑定覆盖必须在调用 Play() 之前完成，否则会错过第 0 帧。
15. 相机使用 ACineCameraActor / UCineCameraComponent：用 SetFilmback 设置 SensorWidth/SensorHeight（如 36/24 为全画幅 35mm），SetCurrentFocalLength(50.0f) 设焦距，SetCurrentAperture(2.0f) 设光圈。
16. 用 SetFocusSettings 配置 FCameraFocusSettings：FocusMethod 设为 Manual/Tracking/Disable/DoNotOverride，ManualFocusDistance 单位 cm，bSmoothFocusChanges 开启平滑对焦。
17. 用 CineCameraActor 的 LookatTrackingSettings 启用注视跟踪：bEnableLookAtTracking、ActorToTrack、LookAtTrackingInterpSpeed、RelativeOffset。
18. 若不想让序列覆盖游戏相机，在 Play 前设置 SeqActor->PlaybackSettings.bDisableCameraCuts = true。
19. 过场结束后相机不会自动恢复：在 OnFinished 委托中调用 PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic) 并 PC->SetIgnoreMoveInput(false)、PC->SetIgnoreLookInput(false)；混合由 APlayerCameraManager::UpdateCamera 每帧处理。
20. 事件轨道通过 UFUNCTION(BlueprintCallable) 在事件上下文对象上调用函数，默认上下文为 UWorld + ALevelScriptActor；事件轨道结构为 UMovieSceneEventTrack → UMovieSceneEventTriggerSection → FMovieSceneEvent（指向端点函数）。
21. 需要每序列独立脚本上下文时，子类化 ULevelSequenceDirector（蓝图或 C++）并赋给 LevelSequence 资产的 Director Class 属性；Director 实例随序列播放创建、停止销毁，可通过其 Player 字段访问播放器和绑定 Actor。
22. 通过 SeqActor->GetSequence()->GetMovieScene() 获取 UMovieScene，用 GetPossessableCount/GetPossessable、GetSpawnableCount/GetSpawnable 遍历，用 GetTracks() 取 master track，用 FindBinding(Guid)->GetTracks() 取某绑定的轨道。
23. 按需选用轨道类型：UMovieScene3DTransformTrack、UMovieSceneSkeletalAnimationTrack、UMovieSceneEventTrack、UMovieSceneAudioTrack、UMovieSceneFadeTrack、UMovieSceneCameraCutTrack、UMovieSceneSubTrack、UMovieScenePropertyTrack（及其子类 UMovieSceneFloatTrack、UMovieSceneBoolTrack、UMovieSceneColorTrack）；所有轨道类型都需要 Build.cs 中的 MovieSceneTracks。
24. 自定义轨道可子类化 UMovieSceneTrack + UMovieSceneSection，并通过 ISequencerModule::RegisterTrackEditor 注册（高级模式，多数需求用 UMovieScenePropertyTrack 子类即可）。
25. 添加子序列：MasterMS->AddTrack<UMovieSceneSubTrack>() 后调用 SubTrack->AddSequence(ChildLevelSequence, Start, Duration)，并配置 SubSection->Parameters.TimeScale 和 bCanLoop；子序列内绑定 ID 的 SequenceID 非零，从根播放器覆盖绑定时用 FMovieSceneObjectBindingID::ResolveParentIndex。
26. SlowMo 效果用 Player->SetPlayRate(0.5f)，它与 UGameplayStatics::SetGlobalTimeDilation 独立，不影响世界物理和其他游戏系统，可配合后处理运动模糊增强电影感。
27. Movie Render Queue 离线渲染：创建 UMoviePipelineQueue，用 AllocateNewJob 分配 UMoviePipelineExecutorJob，设置 Job->Sequence、Job->Map、Job->JobName，并用 SetConfiguration 设置 UMoviePipelinePrimaryConfig；输出用 UMoviePipelineOutputSetting 配置路径/文件名/帧率，格式用 UMoviePipelineImageSequenceOutput_PNG/_EXR 或 UMoviePipelineAppleProResOutput，渲染通道用 UMoviePipelineDeferredPassBase 添加多个 AOV。
28. 执行渲染（仅编辑器）：通过 GEngine->GetEngineSubsystem<UMoviePipelineQueueEngineSubsystem>() 调用 RenderQueueWithExecutor(UMoviePipelineInProcessExecutor::StaticClass())；运行时/非编辑器渲染需自行实现 UMoviePipelineExecutorBase。
29. 避免常见错误：绑定必须在 Play 前；相机切换只影响本地客户端，服务器驱动同步用 SeqActor->SetReplicatePlayback(true)；过场后手动恢复相机和输入；把 CreateLevelSequencePlayer 返回的 OutActor 存入 UPROPERTY 防 GC；跳过序列前设 ForceRestoreState；不要依赖墙钟时间，用 GetCurrentTime() 帧号；不要用已废弃的 SeqActor->SequencePlayer；始终从拥有目标序列的那个 ALevelSequenceActor 获取播放器，避免用错实例导致无效果或驱动错误 Actor。

适用边界 · 注意事项

• 项目未使用 Unreal Engine 或不需要 Sequencer/cinematic 功能时。
• 仅需播放骨骼动画而不涉及 Sequencer 序列、相机或过场时（应改用 ue-animation-system 技能）。
• 无法访问 UE 编辑器或 MovieRenderPipelineEditor 模块时，无法执行 Movie Render Queue 的编辑器内渲染流程。