スキル: ue-sequencer-cinematics
あなたはUnreal EngineのSequencerとシンエマティックシステムのエキスパートです。
コンテキストの確認
映画的なコードを作成する前に、.agents/ue-project-context.mdをお読みください:
- ターゲットUEバージョン(APIの利用可能性が異なります — SequencePlayerプロパティは5.4以降で非推奨)
- シンエマティック要件(カットシーン、ゲーム内カメラ、オフラインレンダリング)
- マルチプレイヤーコンテキスト(シーケンスレプリケーションの動作は異なります)
- すでに宣言されているBuild.csモジュール
情報収集
以下の情報を確認してください:
- シンエマティックのタイプ:フルスクリーンカットシーン、ゲーム内カメラ、または背景アンビエントシーケンス
- アクターはランタイムでバインドされるか、レベルに事前配置されているか
- 再生後にカメラ制御をプレイヤーに戻す必要があるか
- ワンショットかループシーケンスか
- リアルタイムゲームプレイか、オフラインの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回, -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);
// GCを防ぐために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); // 負の値 = 逆再生
// フレームにジャンプ(現在とターゲット間のイベントをスキップ)
// BlueprintではGoToFrameとして公開。C++では、Jumpを使用してSetPlaybackPositionを使用。
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()を呼び出す前に必ずバインドしてください。
SpawnableとPossessable
Possessableは、事前に存在するワールドアクター(レベルに配置された、またはゲームプレイによって生成されたもの)にバインドします。Spawnableは、シーケンス自体が作成および破棄するアクターです。
// Spawnable: シーケンスがアクターのライフサイクルを所有
// Sequencerエディターで設定:アクタートラックを右クリック→「Spawnableに変更」
// ランタイムでは、シーケンスがその範囲に到達するとアクターが生成され、範囲を出ると破棄されます
// 動的Possessable: ゲームプレイで生成されたアクターをシーケンストラックにバインド
// エディターでバインディングIDを作成し、ランタイムでオーバーライド:
FMovieSceneObjectBindingID BindingID = /* シーケンスエディターから */;
ALevelSequenceActor* SeqActor = /* シーケンスアクター */;
SeqActor->SetBinding(BindingID, {SpawnedActor});
なぜ重要か: 永続的なワールドアクター(ドア、エレベーター)にはPossessableを使用し、一時的なカットシーンのみのアクター(シンエマティック専用キャラクター、プロップ)にはSpawnableを使用します。Possessableはシーケンス終了後も存続しますが、Spawnableは自動的にクリーンアップされます。
// LevelSequenceActor.h — すべてのバインディングAPIはここにあります
// バインドされたアクターを置き換える(推奨:タグベース、GUID変更に強い)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
/*bAllowBindingsFromAsset=*/ false);
// GUIDベース(エディター割り当てのためにFMovieSceneObjectBindingIDをUPROPERTYとして公開)
// 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 in mm, read-only SensorAspectRatio)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance cm, bSmoothFocusChanges)
// float CurrentFocalLength — 補間可能、Sequencerでアニメーション化可能
// float CurrentAperture — f値、補間可能
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値
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);
// ブレンドは、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— 1つ以上のトリガーエントリを含むセクションFMovieSceneEvent— トリガーセクション内の各エントリで、エンドポイント関数を指します
エンドポイント関数は、ランタイムでイベントコンテキストオブジェクト(デフォルトではUWorldとALevelScriptActor)に対して解決されます。ディレクターベースのイベントは、ULevelSequenceDirectorサブクラスインスタンスに対して解決されます。
ULevelSequenceDirector — カスタムイベントコンテキスト
ULevelSequenceDirectorは、イベントトラック呼び出しを受け取るシーケンスごとのスクリプティングコンテキストを提供します。サブクラス化し(Blueprintまたは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、ダイアログシステム、カメラフォーカスなど
}
なぜLevel ScriptよりもDirectorか: Directorはシーケンスアセットと共に移動し、レベルとは独立しています。マップ間で再利用可能です。シーケンスごとの状態(メンバー変数)をサポートします。Level Scriptイベントは、シーケンスがその特定のレベルに配置されている場合にのみ機能します。
MovieSceneトラック
// MovieScene.h — LevelSequenceアセットから取得
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// Possessable(ワールドアクター) — インデックスで反復
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// Spawnable(シーケンス所有のアクター) — インデックスで反復
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サブクラスで満たされます。
...