Skill: ue-sequencer-cinematics
당신은 언리얼 엔진의 시퀀서 및 시네마틱 시스템 전문가입니다.
컨텍스트 확인
시네마틱 코드를 작성하기 전에 .agents/ue-project-context.md를 읽어 다음 사항을 확인하세요:
- 대상 UE 버전 (API 가용성에 차이가 있음 — SequencePlayer 속성은 5.4+에서 폐기됨)
- 시네마틱 요구 사항 (컷씬, 게임 내 카메라, 오프라인 렌더링)
- 멀티플레이어 컨텍스트 (시퀀스 복제 동작이 다름)
- 이미 선언된 Build.cs 모듈
정보 수집
다음 사항을 물어보세요:
- 시네마틱 유형: 전체 화면 컷씬, 게임 내 카메라, 또는 배경 앰비언트 시퀀스
- 액터가 런타임에 바인딩되는지 아니면 레벨에 미리 배치되었는지
- 재생 후 카메라 제어권이 플레이어에게 반환되어야 하는지
- 원샷(One-shot) 또는 루핑(Looping) 시퀀스
- 실시간 게임플레이 또는 오프라인 무비 렌더 큐 출력
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);
// 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); // 음수 = 역방향
// 프레임으로 이동 (현재 위치와 대상 위치 사이의 이벤트 건너뜀)
// 블루프린트에서는 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); // non-dynamic
// 카메라 컷 이벤트 (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
액터 바인딩
시퀀서에서 태그 바인딩 (오브젝트 바인딩 우클릭 -> 태그...) 후 런타임에 재정의합니다.
Play()를 호출하기 전에 항상 바인딩하세요.
Spawnable vs Possessable
Possessable은 레벨에 미리 배치되었거나 게임플레이에 의해 스폰된 기존 월드 액터에 바인딩됩니다. Spawnable은 시퀀스 자체가 생성하고 파괴하는 액터입니다.
// Spawnable: 시퀀스가 액터 라이프사이클을 소유
// 시퀀서 편집기에서 설정: 액터 트랙 우클릭 → "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, 읽기 전용 SensorAspectRatio)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance cm, bSmoothFocusChanges)
// float CurrentFocalLength — 보간 가능, 시퀀서에서 애니메이션 가능
// 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);
// Lookat 추적 (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를 통해 접근) 로컬 플레이어의 카메라 블렌딩 및 뷰 타겟 선택을 관리합니다. 컷씬이 끝난 후에는 게임플레이 카메라를 명시적으로 복원하세요 — 시퀀서가 자동으로 수행하지 않습니다:
APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager가 블렌드 상태를 처리합니다. SetViewTargetWithBlend가 이를 트리거합니다.
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// 블렌드는 APlayerCameraManager::UpdateCamera 내부에서 매 틱마다 처리됩니다.
시퀀서 이벤트
이벤트 트랙은 이벤트 컨텍스트의 객체에 있는 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:
// 시퀀서 이벤트 트랙에서 호출됨 — 시퀀서 편집기에서 이벤트 키에 바인딩
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();
// 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 서브클래스로 충족됩니다.