ue-sequencer-cinematics

用途

该技能用于在 Unreal Engine 5.8 的 C++ 代码中处理 Sequencer 与 Cinematics：从 C++ 播放 Level Sequence、构建过场动画或游戏内镜头时刻、在运行时把 Actor 绑定到序列轨道、接入 Sequencer 事件轨道，以及配置电影摄像机与摄像机轨道、进行离线渲染。资料中的 API 已针对 5.8 头文件验证，旧写法列在“Deprecated — do not use”下。

模块结构

Sequencer 横跨三个运行时模块加一个插件：MovieScene 保存数据模型与播放器基类；MovieSceneTracks 保存具体轨道与区段类型；LevelSequence 保存资产、Actor、播放器与导演；CinematicCamera 保存电影摄像机与摄像机轨道。离线渲染位于 Movie Render Queue 插件中（运行时为 MovieRenderPipelineCore，编辑器队列 UI 为 MovieRenderPipelineEditor），默认禁用，必须在 .uproject 中启用。

主要能力

• 播放控制：Play、PlayReverse、PlayLooping、Pause、Scrub、Stop、StopAtCurrentTime、GoToEndAndStop、SetPlayRate、SetFrameRange、SetTimeRange、SetPlaybackPosition、PlayTo 等。
• 运行时创建播放器：ULevelSequencePlayer::CreateLevelSequencePlayer，配合 FMovieSceneSequencePlaybackSettings 设置自动播放、播放速率、起始时间、循环次数、输入禁用、隐藏 HUD、摄像机切换等。
• 委托：OnPlay、OnStop、OnFinished、OnPause、OnNativeFinished、OnCameraCut。OnFinished 仅在自然结束时触发（同时也会触发 OnStop），显式 Stop() 只触发 OnStop；需在 Play() 前绑定。
• 运行时绑定 Actor：区分 possessable（关卡中已存在的 Actor，可被运行时覆盖）与 spawnable（由序列创建和销毁）。可按标签（SetBindingByTag、AddBindingByTag、RemoveBindingByTag）或 GUID（SetBinding、AddBinding、RemoveBinding、ResetBinding、ResetBindings）覆盖绑定；标签在重新绑定时保留，GUID 不会。
• 序列整体位移：ALevelSequenceActor 实现 IMovieScenePlaybackClient::GetInstanceData，设置 bOverrideInstanceData 并提供 UDefaultLevelSequenceInstanceData 来偏移所有绝对变换区段。
• 事件轨道：事件键存储编译后的 UFunction 指针，在序列的导演实例上调用，该实例属于 ULevelSequence::DirectorClass（派生自 ULevelSequenceDirector）。端点必须无参数或恰好一个按值传递的对象/接口参数，且无返回值。
• MovieScene 数据模型：读取显示帧率、Tick 分辨率、播放范围、possessable 与 spawnable、根轨道与绑定；轨道类型包括 3D 变换、骨骼动画、摄像机切换、事件、音频、淡入淡出、属性轨道等。

使用方式

在 Build.cs 中添加 PublicDependencyModuleNames：LevelSequence、MovieScene、MovieSceneTracks、CinematicCamera；离线渲染添加 PrivateDependencyModuleNames 的 MovieRenderPipelineCore，并在 .uproject 启用 MovieRenderPipeline 插件。运行时播放可从已放置的 ALevelSequenceActor 调用 GetSequencePlayer()->Play()，或运行时创建播放器。绑定 Actor 时在 Sequencer 编辑器中给对象绑定打标签，再从 C++ 按标签覆盖。事件轨道需创建 ULevelSequenceDirector 子类，把 Level Sequence 的 Director Blueprint 重新指定父类为该子类，并在 UFUNCTION 上按规则声明端点。

适用场景

适用于需要在 C++ 中驱动过场动画、游戏内镜头、运行时 Actor 绑定、时间线事件回调、电影摄像机与轨道配置，以及离线渲染帧或视频的项目。

限制

创作序列是编辑器操作；发行版游戏代码只播放和重新绑定序列，不构建序列。UMovieScene::AddTrack 与 UMovieSceneSubTrack::AddSequence 虽可编译进运行时构建，但会修改序列资产，只应从编辑器工具或命令调用；已烘焙的 ULevelSequence 不得在发行游戏中编辑。在非游戏世界（Sequencer 预览）中，除非 UFUNCTION 带有 CallInEditor，否则事件会被跳过。使用 EUpdatePositionMethod::Jump 定位会跳过中间所有事件，需要事件触发时应使用 PlayTo。使用 SetWeight() 前需启用 bDynamicWeighting（或在资产上启用）。FMovieSceneObjectBindingID 的 guid 与 sequence id 为私有，需通过 GetGuid()、GetRelativeSequenceID()、IsFixedBinding() 读取，跨子序列层级移动 ID 需用 ResolveToFixed()，再对结果 UE::MovieScene::FFixedObjectBindingID 调用 ConvertToRelative()；不得直接赋值字段。