技能:ue-sequencer-cinematics
你是一位精通虚幻引擎Sequencer与影视级过场系统的专家。
上下文检查
在编写任何过场动画代码之前,请阅读 .agents/ue-project-context.md 以了解:
- 目标UE版本(API可用性因版本而异 — SequencePlayer 属性在 5.4+ 中已弃用)
- 过场动画需求(过场动画、游戏内摄像机、离线渲染)
- 多人游戏上下文(序列复制行为不同)
- Build.cs 中已声明的模块
信息收集
请询问:
- 过场动画类型:全屏过场动画、游戏内摄像机或背景环境序列
- Actor是在运行时绑定还是预先放置在关卡中
- 播放后是否必须将摄像机控制权返还给玩家
- 单次播放还是循环序列
- 实时游戏输出还是离线 Movie Render Queue 输出
Build.cs 模块
PublicDependencyModuleNames.AddRange(new string[]
{
"LevelSequence", "MovieScene", "CinematicCamera",
});
// 仅离线渲染时添加:
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");
播放关卡序列
ALevelSequenceActor — 世界放置方式
ALevelSequenceActor 拥有播放器。使用 GetSequencePlayer() — 直接的 SequencePlayer 属性自 UE 5.4 起已弃用。
// LevelSequenceActor.h: ULevelSequencePlayer* GetSequencePlayer() const;
ULevelSequencePlayer* Player = SeqActor->GetSequencePlayer();
if (Player) { Player->Play(); }
ULevelSequencePlayer::CreateLevelSequencePlayer — 运行时生成方式
// 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=一次,-1=无限
Settings.bDisableMovementInput = true;
Settings.bDisableLookAtInput = true;
Settings.bHidePlayer = false;
Settings.bHideHud = false;
Settings.bDisableCameraCuts = false;
Settings.bPauseAtEnd = false;
Settings.FinishCompletionStateOverride =
EMovieSceneCompletionModeOverride::ForceRestoreState; // 对于可跳过的过场动画安全
ALevelSequenceActor* OutActor = nullptr;
ULevelSequencePlayer* Player = ULevelSequencePlayer::CreateLevelSequencePlayer(
this, Sequence, Settings, OutActor);
// 将 OutActor 存储在 UPROPERTY 中以防止被 GC
ActiveSequenceActor = OutActor;
if (Player)
{
Player->OnFinished.AddDynamic(this, &AMyClass::OnCutsceneFinished);
Player->Play();
}
播放控制(基类 UMovieSceneSequencePlayer)
// MovieSceneSequencePlayer.h
Player->Play();
Player->PlayReverse();
Player->PlayLooping(-1); // -1 = 无限循环
Player->Pause();
Player->Stop(); // 将光标移动到末尾,触发 OnStop
Player->StopAtCurrentTime();
Player->GoToEndAndStop();
Player->SetPlayRate(0.5f); // 负值 = 倒放
// 跳转到指定帧(跳过当前帧与目标帧之间的事件)
// 在蓝图中暴露为 GoToFrame。在 C++ 中,使用 SetPlaybackPosition 并配合 Jump 方法。
Player->SetPlaybackPosition(
FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump));
// 播放到指定帧(沿途触发所有事件)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(240), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
// 限制播放范围
Player->SetFrameRange(0, 60); // 帧 0–60
Player->SetTimeRange(0.0f, 2.5f); // 秒
// 状态查询
bool bPlaying = Player->IsPlaying();
FQualifiedFrameTime Now = Player->GetCurrentTime();
FQualifiedFrameTime Dur = Player->GetDuration();
// 委托(在调用 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); // 非动态
// 摄像机剪切事件(LevelSequencePlayer.h)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLevelSequencePlayerCameraCutEvent, UCameraComponent*, CameraComponent)
LsPlayer->OnCameraCut.AddDynamic(this, &UMyClass::OnCameraCut);
// 提前停止时恢复状态(可跳过的过场动画)
Player->SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState);
Player->Stop();
// 子序列快照
FLevelSequencePlayerSnapshot Snap;
Player->TakeFrameSnapshot(Snap);
// Snap.CurrentShotName, Snap.RootTime, Snap.CameraComponent, Snap.ActiveShot
Actor 绑定
在Sequencer中标记绑定(右键单击对象绑定 -> 标签...)然后在运行时覆盖。
始终在调用 Play() 之前进行绑定。
占据物(Possessables)与生成物(Spawnables)
占据物绑定到预先存在的世界Actor(放置在关卡中或由游戏玩法生成)。生成物是序列自身创建和销毁的Actor。
// 生成物:序列拥有Actor的生命周期
// 在Sequencer编辑器中设置:右键单击Actor轨道 → "更改为生成物"
// 运行时,当序列到达其范围时生成Actor,离开范围时销毁
// 动态占据物:将游戏玩法生成的Actor绑定到序列轨道
// 在编辑器中创建绑定ID,然后在运行时覆盖:
FMovieSceneObjectBindingID BindingID = /* 来自序列编辑器 */;
ALevelSequenceActor* SeqActor = /* 你的序列Actor */;
SeqActor->SetBinding(BindingID, {SpawnedActor});
为何重要:对持久的世界Actor(门、电梯)使用占据物,对瞬态的仅过场动画Actor(仅过场动画的角色、道具)使用生成物。占据物在序列结束后仍然存在;生成物会自动清理。
// LevelSequenceActor.h — 所有绑定API都在这里
// 替换绑定的Actor(推荐:基于标签,对GUID更改有弹性)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
/*bAllowBindingsFromAsset=*/ false);
// 基于GUID(通过 UPROPERTY 暴露 FMovieSceneObjectBindingID 以在编辑器中赋值)
// UPROPERTY(EditAnywhere) FMovieSceneObjectBindingID HeroBindingID;
SeqActor->SetBinding(HeroBindingID, TArray<AActor*>{ HeroActor }, false);
// 追加而不移除现有绑定
SeqActor->AddBindingByTag(FName("NPC"), NpcActor, /*bAllowBindingsFromAsset=*/ true);
// 移除 / 重置
SeqActor->RemoveBindingByTag(FName("NPC"), NpcActor);
SeqActor->ResetBinding(HeroBindingID); // 回退到资源绑定
SeqActor->ResetBindings(); // 回退所有覆盖
// 通过标签查找
FMovieSceneObjectBindingID ID = SeqActor->FindNamedBinding(FName("Hero"));
const TArray<FMovieSceneObjectBindingID>& All = SeqActor->FindNamedBindings(FName("NPC"));
// 检查当前绑定的内容
TArray<UObject*> Bound = Player->GetBoundObjects(HeroBindingID);
// FMovieSceneObjectBindingID (MovieSceneObjectBindingID.h):
// 通过公共访问器访问 — 内部字段是私有的:
// GetGuid() — 标识绑定轨道的 FGuid
// GetRelativeSequenceID() — 标识哪个子序列持有它(0 = 本地)
摄像机系统
ACineCameraActor / UCineCameraComponent
// CineCameraActor.h: UCineCameraComponent* GetCineCameraComponent() const;
// CineCameraComponent.h / CineCameraSettings.h:
// FCameraFilmbackSettings Filmback (SensorWidth, SensorHeight 以毫米为单位,只读 SensorAspectRatio)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop 毫米)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance 厘米, bSmoothFocusChanges)
// float CurrentFocalLength — 可插值,可在Sequencer中动画化
// float CurrentAperture — f-stop,插值可动画化
ACineCameraActor* Cam = GetWorld()->SpawnActor<ACineCameraActor>(SpawnTransform);
UCineCameraComponent* CC = Cam->GetCineCameraComponent();
FCameraFilmbackSettings FB;
FB.SensorWidth = 36.0f; FB.SensorHeight = 24.0f; // 全画幅 35mm
CC->SetFilmback(FB);
CC->SetCurrentFocalLength(50.0f); // 毫米
CC->SetCurrentAperture(2.0f); // f-stop
FCameraFocusSettings FS;
FS.FocusMethod = ECameraFocusMethod::Manual; // Manual | Tracking | Disable | DoNotOverride
FS.ManualFocusDistance = 500.0f; // 厘米
FS.bSmoothFocusChanges = true;
CC->SetFocusSettings(FS);
// 注视追踪 (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);
// 阻止序列覆盖游戏摄像机(在调用 Play 之前设置)
SeqActor->PlaybackSettings.bDisableCameraCuts = true;
// 过场动画后恢复玩家摄像机(从 OnFinished 委托中调用)
APlayerController* PC = GetWorld()->GetFirstPlayerController();
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
PC->SetIgnoreMoveInput(false);
PC->SetIgnoreLookInput(false);
APlayerCameraManager
APlayerCameraManager(通过 PlayerController->PlayerCameraManager 访问)管理本地玩家的摄像机混合和视图目标选择。过场动画结束后,显式恢复游戏摄像机 — Sequencer 不会自动执行此操作:
APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager 处理混合状态;SetViewTargetWithBlend 触发它。
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// 混合在 APlayerCameraManager::UpdateCamera 的每个tick中被处理。
Sequencer 事件
事件轨道对事件上下文中的对象调用 UFUNCTION。
默认事件上下文:UWorld + ALevelScriptActor。
// 函数必须是上下文对象上的 UFUNCTION(BlueprintCallable)
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void TriggerExplosion()
{
ExplosionSystem->SpawnExplosion(ExplosionLocation);
}
// 通过播放到特定帧来触发 C++ 代码(触发范围内的所有事件)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(60), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
FMovieSceneEvent
FMovieSceneEvent 持有事件端点数据 — 事件触发时要调用的绑定函数。事件轨道的结构如下:
UMovieSceneEventTrack— 添加到绑定或作为主轨道的主轨道UMovieSceneEventTriggerSection— 包含一个或多个触发器条目的节段FMovieSceneEvent— 触发器节段内的每个条目,指向端点函数
端点函数在运行时针对事件上下文对象(默认情况下是 UWorld 和 ALevelScriptActor)解析。基于导演的事件针对 ULevelSequenceDirector 子类实例解析。
ULevelSequenceDirector — 自定义事件上下文
ULevelSequenceDirector 提供一个每个序列的脚本上下文,该上下文接收事件轨道调用。对其子类化(蓝图或C++)并赋值给 LevelSequence 资源的 Director Class 属性。Director 实例在序列开始播放时创建,并在停止时销毁 — 其生命周期与序列播放器匹配。
// MySequenceDirector.h
#include "LevelSequenceDirector.h"
#include "MySequenceDirector.generated.h"
UCLASS(Blueprintable)
class UMySequenceDirector : public ULevelSequenceDirector
{
GENERATED_BODY()
public:
// 从Sequencer事件轨道调用 — 在Sequencer编辑器中绑定到事件键
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnDialogueStart(FName SpeakerTag);
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnCutsceneChoice(int32 ChoiceIndex);
};
// MySequenceDirector.cpp
void UMySequenceDirector::OnDialogueStart(FName SpeakerTag)
{
// 在Director内部访问序列播放器和绑定的Actor。
// ULevelSequenceDirector.h: UPROPERTY ULevelSequencePlayer* Player(直接字段,无getter)
TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
// 触发游戏逻辑:UI、对话系统、摄像机对焦等。
}
为何Director优于关卡脚本:Director随序列资源而不是关卡移动。可在多个地图中复用。支持每个序列的状态(成员变量)。关卡脚本事件仅当序列放置在特定关卡中时才有效。
MovieScene 轨道
// MovieScene.h — 从 LevelSequence 资源获取
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// 占据物(世界Actor)— 按索引迭代
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// 生成物(序列拥有的Actor)— 按索引迭代
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}
// 主轨道(未绑定到任何Actor)
const TArray<UMovieSceneTrack*>& Masters = MS->GetTracks();
// 特定绑定上的轨道
const FMovieSceneBinding* B = MS->FindBinding(SomeGuid);
if (B) { for (UMovieSceneTrack* T : B->GetTracks()) { /* 转换为子类型 */ } }
| 轨道类 | 用途 |
|---|---|
UMovieScene3DTransformTrack | 变换动画 |
UMovieSceneSkeletalAnimationTrack | 骨骼网格体动画 |
UMovieSceneEventTrack | 事件触发器 |
UMovieSceneAudioTrack | 音频 |
UMovieSceneFadeTrack | 屏幕淡入淡出 |
UMovieSceneCameraCutTrack | 摄像机剪切 |
UMovieSceneSubTrack | 子序列 |
UMovieScenePropertyTrack | 任意 UPROPERTY 动画(基类) |
所有轨道类型都需要在 Build.cs 中包含 MovieSceneTracks。
自定义轨道:子类化 UMovieSceneTrack + UMovieSceneSection 以实现领域特定的动画数据。通过 ISequencerModule::RegisterTrackEditor 注册。这是一个高级模式 — 大多数需求都可以通过 UMovieScenePropertyTrack 的子类化来满足。
…
[为翻译截断]