Skill: ue-sequencer-cinematics
Você é um especialista no Sequencer e sistemas cinematográficos da Unreal Engine.
Verificação de Contexto
Leia o arquivo .agents/ue-project-context.md antes de escrever qualquer código cinematográfico para:
- Versão alvo da UE (a disponibilidade da API varia — a propriedade
SequencePlayerfoi descontinuada na 5.4+) - Requisitos cinematográficos (cutscenes, câmeras em jogo, renderização offline)
- Contexto multijogador (o comportamento de replicação de sequências difere)
- Módulos do Build.cs já declarados
Coleta de Informações
Pergunte sobre:
- Tipo de cinemática: cutscene em tela cheia, câmera em jogo ou sequência ambiente de fundo
- Se os atores são vinculados em tempo de execução ou pré-posicionados no nível
- Se o controle da câmera deve retornar ao jogador após a reprodução
- Sequência de uma vez ou em loop
- Jogabilidade em tempo real ou saída offline do Movie Render Queue
Módulos do Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{
"LevelSequence", "MovieScene", "CinematicCamera",
});
// Apenas para renderização offline:
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");
Reprodução de Sequências de Nível
ALevelSequenceActor — Posicionado no Mundo
ALevelSequenceActor possui o player. Use GetSequencePlayer() — a propriedade direta SequencePlayer foi descontinuada desde a UE 5.4.
// LevelSequenceActor.h: ULevelSequencePlayer* GetSequencePlayer() const;
ULevelSequencePlayer* Player = SeqActor->GetSequencePlayer();
if (Player) { Player->Play(); }
ULevelSequencePlayer::CreateLevelSequencePlayer — Spawn em Tempo de Execução
// 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=uma vez, -1=infinito
Settings.bDisableMovementInput = true;
Settings.bDisableLookAtInput = true;
Settings.bHidePlayer = false;
Settings.bHideHud = false;
Settings.bDisableCameraCuts = false;
Settings.bPauseAtEnd = false;
Settings.FinishCompletionStateOverride =
EMovieSceneCompletionModeOverride::ForceRestoreState; // seguro para cutscenes dispensáveis
ALevelSequenceActor* OutActor = nullptr;
ULevelSequencePlayer* Player = ULevelSequencePlayer::CreateLevelSequencePlayer(
this, Sequence, Settings, OutActor);
// Armazene OutActor em UPROPERTY para evitar GC
ActiveSequenceActor = OutActor;
if (Player)
{
Player->OnFinished.AddDynamic(this, &AMyClass::OnCutsceneFinished);
Player->Play();
}
Controle de Reprodução (base UMovieSceneSequencePlayer)
// MovieSceneSequencePlayer.h
Player->Play();
Player->PlayReverse();
Player->PlayLooping(-1); // -1 = loops infinitos
Player->Pause();
Player->Stop(); // move o cursor para o fim, dispara OnStop
Player->StopAtCurrentTime();
Player->GoToEndAndStop();
Player->SetPlayRate(0.5f); // negativo = reverso
// Pular para quadro (ignora eventos entre o atual e o destino)
// Blueprint expõe isso como GoToFrame. Em C++, use SetPlaybackPosition com Jump.
Player->SetPlaybackPosition(
FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump));
// Reproduzir até o quadro (dispara todos os eventos ao longo do caminho)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(240), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
// Restringir intervalo de reprodução
Player->SetFrameRange(0, 60); // quadros 0–60
Player->SetTimeRange(0.0f, 2.5f); // segundos
// Consulta de estado
bool bPlaying = Player->IsPlaying();
FQualifiedFrameTime Now = Player->GetCurrentTime();
FQualifiedFrameTime Dur = Player->GetDuration();
// Delegates (vincule antes de 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); // não-dinâmico
// Evento de corte de câmera (LevelSequencePlayer.h)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLevelSequencePlayerCameraCutEvent, UCameraComponent*, CameraComponent)
LsPlayer->OnCameraCut.AddDynamic(this, &UMyClass::OnCameraCut);
/ Restaurar estado na parada antecipada (cutscene dispensável)
Player->SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState);
Player->Stop();
// Instantâneo de sub-sequência
FLevelSequencePlayerSnapshot Snap;
Player->TakeFrameSnapshot(Snap);
// Snap.CurrentShotName, Snap.RootTime, Snap.CameraComponent, Snap.ActiveShot
Vinculação de Atores
Marque as vinculações no Sequencer (clique direito na vinculação do objeto -> Marcas...) e depois substitua em tempo de execução.
Sempre vincule antes de chamar Play().
Spawnáveis vs Possesáveis
Possesáveis vinculam-se a atores preexistentes do mundo (colocados no nível ou gerados pela jogabilidade). Spawnáveis são atores que a própria sequência cria e destrói.
// Spawnável: a sequência controla o ciclo de vida do ator
// Defina no editor Sequencer: clique direito na trilha do ator → "Alterar para Spawnável"
// Em tempo de execução, o ator é gerado quando a sequência atinge seu intervalo e desaparece ao sair
// Possesável dinâmico: vincule um ator gerado pela jogabilidade a uma trilha de sequência
// Crie o ID de vinculação no editor e depois substitua em tempo de execução:
FMovieSceneObjectBindingID BindingID = /* do editor da sequência */;
ALevelSequenceActor* SeqActor = /* seu ator de sequência */;
SeqActor->SetBinding(BindingID, {SpawnedActor});
Por que isso importa: Use possesáveis para atores persistentes do mundo (portas, elevadores) e spawnáveis para atores transitórios apenas de cutscene (personagens apenas cinematográficos, adereços). Possesáveis sobrevivem ao fim da sequência; spawnáveis são limpos automaticamente.
// LevelSequenceActor.h — toda a API de vinculação está aqui
// Substituir atores vinculados (preferido: baseado em marca, resistente a alterações de GUID)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
/*bAllowBindingsFromAsset=*/ false);
// Baseado em GUID (expondo FMovieSceneObjectBindingID via UPROPERTY para atribuição no editor)
// UPROPERTY(EditAnywhere) FMovieSceneObjectBindingID HeroBindingID;
SeqActor->SetBinding(HeroBindingID, TArray<AActor*>{ HeroActor }, false);
// Adicionar sem remover vinculações existentes
SeqActor->AddBindingByTag(FName("NPC"), NpcActor, /*bAllowBindingsFromAsset=*/ true);
// Remover / redefinir
SeqActor->RemoveBindingByTag(FName("NPC"), NpcActor);
SeqActor->ResetBinding(HeroBindingID); // reverter para vinculação do asset
SeqActor->ResetBindings(); // reverter todas as substituições
/ Pesquisar por marca
FMovieSceneObjectBindingID ID = SeqActor->FindNamedBinding(FName("Hero"));
const TArray<FMovieSceneObjectBindingID>& All = SeqActor->FindNamedBindings(FName("NPC"));
// Inspecionar o que está vinculado atualmente
TArray<UObject*> Bound = Player->GetBoundObjects(HeroBindingID);
// FMovieSceneObjectBindingID (MovieSceneObjectBindingID.h):
// Acesso via acessadores públicos — campos internos são privados:
// GetGuid() — FGuid que identifica a trilha de vinculação
// GetRelativeSequenceID() — qual sub-sequência a contém (0 = local)
Sistema de Câmera
ACineCameraActor / UCineCameraComponent
// CineCameraActor.h: UCineCameraComponent* GetCineCameraComponent() const;
// CineCameraComponent.h / CineCameraSettings.h:
// FCameraFilmbackSettings Filmback (SensorWidth, SensorHeight em mm, SensorAspectRatio somente leitura)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance cm, bSmoothFocusChanges)
// float CurrentFocalLength — Interp, animável no Sequencer
// float CurrentAperture — f-stop, animável com Interp
ACineCameraActor* Cam = GetWorld()->SpawnActor<ACineCameraActor>(SpawnTransform);
UCineCameraComponent* CC = Cam->GetCineCameraComponent();
FCameraFilmbackSettings FB;
FB.SensorWidth = 36.0f; FB.SensorHeight = 24.0f; // full-frame 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);
// Rastreamento de olhar (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);
// Impedir que a sequência substitua a câmera da jogabilidade (defina antes de Play)
SeqActor->PlaybackSettings.bDisableCameraCuts = true;
// Restaurar câmera do jogador após cutscene (chame do delegate OnFinished)
APlayerController* PC = GetWorld()->GetFirstPlayerController();
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
PC->SetIgnoreMoveInput(false);
PC->SetIgnoreLookInput(false);
APlayerCameraManager
APlayerCameraManager (acessado via PlayerController->PlayerCameraManager) gerencia a
mistura de câmeras e a seleção do alvo de visualização para o jogador local. Após uma cutscene
terminar, restaure a câmera da jogabilidade explicitamente — o Sequencer não faz isso
automaticamente:
APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager gerencia o estado da mistura; SetViewTargetWithBlend o dispara.
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// A mistura é processada a cada tick dentro de APlayerCameraManager::UpdateCamera.
Eventos do Sequencer
Trilhas de evento chamam UFUNCTIONs em objetos no contexto do evento.
Contexto padrão do evento: UWorld + ALevelScriptActor.
// A função deve ser UFUNCTION(BlueprintCallable) em um objeto de contexto
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void TriggerExplosion()
{
ExplosionSystem->SpawnExplosion(ExplosionLocation);
}
// Disparar código C++ em um quadro específico reproduzindo até ele (dispara todos os eventos no intervalo)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(60), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
FMovieSceneEvent
FMovieSceneEvent contém os dados do endpoint do evento — a função vinculada a ser chamada quando o evento
dispara. As trilhas de evento são estruturadas como:
UMovieSceneEventTrack— a trilha mestre adicionada a uma vinculação ou como trilha mestreUMovieSceneEventTriggerSection— uma seção contendo uma ou mais entradas de disparoFMovieSceneEvent— cada entrada dentro da seção de disparo, apontando para a função endpoint
A função endpoint é resolvida em tempo de execução contra os objetos de contexto do evento (por padrão
UWorld e ALevelScriptActor). Eventos baseados em diretor são resolvidos contra uma instância
de subclasse de ULevelSequenceDirector.
ULevelSequenceDirector — Contexto de Evento Personalizado
ULevelSequenceDirector fornece um contexto de script por sequência que recebe chamadas de trilha
de evento. Crie uma subclasse (Blueprint ou C++) e atribua à propriedade Director Class do asset
LevelSequence. A instância do Director é criada quando a sequência começa a reproduzir e destruída
quando ela para — seu tempo de vida corresponde ao player da sequência.
// MySequenceDirector.h
#include "LevelSequenceDirector.h"
#include "MySequenceDirector.generated.h"
UCLASS(Blueprintable)
class UMySequenceDirector : public ULevelSequenceDirector
{
GENERATED_BODY()
public:
// Chamado de trilhas de evento do Sequencer — vincule a uma chave de evento no editor Sequencer
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnDialogueStart(FName SpeakerTag);
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnCutsceneChoice(int32 ChoiceIndex);
};
// MySequenceDirector.cpp
void UMySequenceDirector::OnDialogueStart(FName SpeakerTag)
{
// Acesse o player da sequência e os atores vinculados de dentro do Director.
// ULevelSequenceDirector.h: UPROPERTY ULevelSequencePlayer* Player (campo direto, sem getter)
TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
// Disparar lógica da jogabilidade: UI, sistema de diálogo, foco da câmera, etc.
}
Por que Director em vez de Level Script: O Director viaja com o asset da sequência, não com o nível. Reutilizável entre mapas. Suporta estado por sequência (variáveis membro). Eventos do Level Script só funcionam quando a sequência é colocada naquele nível específico.
Trilhas do MovieScene
// MovieScene.h — obtido do asset LevelSequence
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// Possesáveis (atores do mundo) — itere por índice
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// Spawnáveis (atores de propriedade da sequência) — itere por índice
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}
// Trilhas mestre (não vinculadas a nenhum ator)
const TArray<UMovieSceneTrack*>& Masters = MS->GetTracks();
// Trilhas em uma vinculação específica
const FMovieSceneBinding* B = MS->FindBinding(SomeGuid);
if (B) { for (UMovieSceneTrack* T : B->GetTracks()) { /* converter para subtipo */ } }
| Classe da Trilha | Propósito |
|---|---|
UMovieScene3DTransformTrack | Animação de transformação |
UMovieSceneSkeletalAnimationTrack | Animação de malha esquelética |
UMovieSceneEventTrack | Disparadores de evento |
UMovieSceneAudioTrack | Áudio |
UMovieSceneFadeTrack | Desvanecimento de tela |
UMovieSceneCameraCutTrack | Cortes de câmera |
UMovieSceneSubTrack | Sub-sequências |
UMovieScenePropertyTrack | Animação arbitrária de UPROPERTY (classe base) |
Todos os tipos de trilha requerem MovieSceneTracks no Build.cs.
Trilhas personalizadas: crie subclasses de UMovieSceneTrack + UMovieSceneSection para dados
de animação específicos de domínio. Registre via ISequencerModule::RegisterTrackEditor. Este é um padrão
avançado — a maioria das necessidades é atendida por subclasses de UMovieScenePropertyTrack.