技能:ue-sequencer-cinematics
您是 Unreal Engine 的 Sequencer 與電影系統專家。
情境檢查
撰寫任何電影相關程式碼前,請先閱讀 .agents/ue-project-context.md 以確認:
- 目標 UE 版本(API 可用性因版本而異——SequencePlayer 屬性自 UE 5.4 起已棄用)
- 電影需求(過場動畫、遊戲內攝影機、離線渲染)
- 多人遊戲情境(序列複製行為有所不同)
- Build.cs 中已宣告的模組
資訊蒐集
請確認下列事項:
- 電影類型:全螢幕過場動畫、遊戲內攝影機,或背景環境序列
- 角色是在執行階段動態綁定,還是預先放置在關卡中
- 播放結束後,攝影機控制權是否必須歸還給玩家
- 單次播放或循環播放
- 即時遊戲操作或離線的 Movie Render Queue 輸出
Build.cs 模組
PublicDependencyModuleNames.AddRange(new string[]
{
"LevelSequence", "MovieScene", "CinematicCamera",
});
// 僅離線渲染時使用:
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");
播放 Level Sequence
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 中以避免被垃圾回收
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
角色綁定
在 Sequencer 中標記綁定(在物件綁定上按右鍵 -> 標籤...),然後在執行階段覆蓋。
請務必在呼叫 Play() 之前完成綁定。
生成物件(Spawnables)vs 佔用物件(Possessables)
佔用物件(Possessables) 綁定到世界中已存在的角色(預先放置在關卡中,或由遊戲邏輯生成)。生成物件(Spawnables) 是序列自身建立並銷毀的角色。
// 生成物件:序列擁有角色生命週期
// 在 Sequencer 編輯器中設定:在角色軌道上按右鍵 →「變更為生成物件」
// 執行階段時,角色會在序列進入其範圍時生成,離開範圍時消失
// 動態佔用:將遊戲生成的角色綁定到序列軌道
// 先在編輯器中建立綁定 ID,然後在執行階段覆蓋:
FMovieSceneObjectBindingID BindingID = /* 來自序列編輯器 */;
ALevelSequenceActor* SeqActor = /* 您的序列角色 */;
SeqActor->SetBinding(BindingID, {SpawnedActor});
為何重要:對持續存在的世界角色(門、電梯)使用佔用物件,對僅在過場動畫中出現的暫時性角色(僅供電影使用的角色、道具)使用生成物件。佔用物件在序列結束後依然存在;生成物件則會自動清除。
// LevelSequenceActor.h — 所有綁定 API 皆在此
// 取代已綁定的角色(建議使用標籤方式,對 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 單位 mm,唯讀 SensorAspectRatio)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop 單位 mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance 單位 cm,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); // 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);
// 視線追蹤(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);
// 混合過程在每個 tick 內由 APlayerCameraManager::UpdateCamera 處理。
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 內部存取序列播放器與已綁定角色。
// ULevelSequenceDirector.h: UPROPERTY ULevelSequencePlayer* Player(直接欄位,無存取子)
TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
// 觸發遊戲邏輯:UI、對話系統、攝影機對焦等。
}
為何選擇 Director 而非關卡腳本:Director 跟隨序列資源而非關卡。可在不同地圖間重複使用。支援每序列狀態(成員變數)。關卡腳本事件只在該序列放置於特定關卡時才有效。
MovieScene 軌道
// MovieScene.h — 從 LevelSequence 資源取得
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// 佔用物件(世界角色)——依索引迭代
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// 生成物件(序列擁有的角色)——依索引迭代
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}
// 主軌道(未綁定至任何角色)
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 子類別滿足。
...
[為翻譯而截斷]