Habilidad: ue-sequencer-cinematics
Eres un experto en el sistema Sequencer y cinematográfico de Unreal Engine.
Verificación de Contexto
Lee .agents/ue-project-context.md antes de escribir cualquier código cinematográfico para:
- Versión objetivo de UE (la disponibilidad de la API varía — la propiedad
SequencePlayerestá obsoleta desde UE 5.4+) - Requisitos cinematográficos (cutscenes, cámaras en el juego, renderizado offline)
- Contexto multijugador (el comportamiento de replicación de secuencias difiere)
- Módulos de Build.cs ya declarados
Recopilación de Información
Pregunta por:
- Tipo de cinemática: cutscene de pantalla completa, cámara en el juego o secuencia ambiental de fondo
- Si los actores se vinculan en tiempo de ejecución o están precolocados en el nivel
- Si el control de la cámara debe devolverse al jugador después de la reproducción
- Secuencia de una sola vez o en bucle
- Juego en tiempo real o salida de Movie Render Queue offline
Módulos Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{
"LevelSequence", "MovieScene", "CinematicCamera",
});
// Solo para renderizado offline:
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");
Reproducción de Secuencias de Nivel
ALevelSequenceActor — Colocado en el Mundo
ALevelSequenceActor posee el reproductor. Usa GetSequencePlayer() — la propiedad directa SequencePlayer está obsoleta desde UE 5.4.
// LevelSequenceActor.h: ULevelSequencePlayer* GetSequencePlayer() const;
ULevelSequencePlayer* Player = SeqActor->GetSequencePlayer();
if (Player) { Player->Play(); }
ULevelSequencePlayer::CreateLevelSequencePlayer — Generación en Tiempo de Ejecución
// 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=una 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 omitibles
ALevelSequenceActor* OutActor = nullptr;
ULevelSequencePlayer* Player = ULevelSequencePlayer::CreateLevelSequencePlayer(
this, Sequence, Settings, OutActor);
// Almacena OutActor en una UPROPERTY para evitar GC
ActiveSequenceActor = OutActor;
if (Player)
{
Player->OnFinished.AddDynamic(this, &AMyClass::OnCutsceneFinished);
Player->Play();
}
Control de Reproducción (base UMovieSceneSequencePlayer)
// MovieSceneSequencePlayer.h
Player->Play();
Player->PlayReverse();
Player->PlayLooping(-1); // -1 = bucles infinitos
Player->Pause();
Player->Stop(); // mueve el cursor al final, dispara OnStop
Player->StopAtCurrentTime();
Player->GoToEndAndStop();
Player->SetPlayRate(0.5f); // negativo = reversa
// Saltar a fotograma (omite eventos entre el actual y el destino)
// Blueprint lo expone como GoToFrame. En C++, usa SetPlaybackPosition con Jump.
Player->SetPlaybackPosition(
FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump));
// Reproducir hasta el fotograma (dispara todos los eventos en el camino)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(240), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
// Restringir rango de reproducción
Player->SetFrameRange(0, 60); // fotogramas 0–60
Player->SetTimeRange(0.0f, 2.5f); // segundos
// Consulta de estado
bool bPlaying = Player->IsPlaying();
FQualifiedFrameTime Now = Player->GetCurrentTime();
FQualifiedFrameTime Dur = Player->GetDuration();
// Delegados (vincular 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); // no dinámico
// Evento de corte de cámara (LevelSequencePlayer.h)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLevelSequencePlayerCameraCutEvent, UCameraComponent*, CameraComponent)
LsPlayer->OnCameraCut.AddDynamic(this, &UMyClass::OnCameraCut);
// Restaurar estado en parada temprana (cutscene omitible)
Player->SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState);
Player->Stop();
// Instantánea de subsecuencia
FLevelSequencePlayerSnapshot Snap;
Player->TakeFrameSnapshot(Snap);
// Snap.CurrentShotName, Snap.RootTime, Snap.CameraComponent, Snap.ActiveShot
Vinculación de Actores
Etiqueta los enlaces en Sequencer (clic derecho en el enlace del objeto -> Etiquetas...) luego sobrescribe en tiempo de ejecución.
Siempre vincula antes de llamar a Play().
Spawnables vs Possessables
Possessables se vinculan a actores preexistentes en el mundo (colocados en el nivel o generados por el juego). Spawnables son actores que la secuencia misma crea y destruye.
// Spawnable: la secuencia posee el ciclo de vida del actor
// Establecido en el editor de Sequencer: clic derecho en la pista del actor → "Cambiar a Spawnable"
// En tiempo de ejecución, el actor se genera cuando la secuencia alcanza su rango y desaparece al salir
// Possessable dinámico: vincular un actor generado por el juego a una pista de secuencia
// Crea el ID de enlace en el editor, luego sobrescribe en tiempo de ejecución:
FMovieSceneObjectBindingID BindingID = /* del editor de secuencias */;
ALevelSequenceActor* SeqActor = /* tu actor de secuencia */;
SeqActor->SetBinding(BindingID, {SpawnedActor});
Por qué es importante: Usa possessables para actores persistentes del mundo (puertas, ascensores) y spawnables para actores transitorios solo de cutscenes (personajes solo cinematográficos, accesorios). Los possessables sobreviven al final de la secuencia; los spawnables se limpian automáticamente.
// LevelSequenceActor.h — toda la API de enlace vive aquí
// Reemplazar actores vinculados (preferido: basado en etiquetas, resistente a cambios de GUID)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
/*bAllowBindingsFromAsset=*/ false);
// Basado en GUID (exponer FMovieSceneObjectBindingID via UPROPERTY para asignación en editor)
// UPROPERTY(EditAnywhere) FMovieSceneObjectBindingID HeroBindingID;
SeqActor->SetBinding(HeroBindingID, TArray<AActor*>{ HeroActor }, false);
// Añadir sin eliminar enlaces existentes
SeqActor->AddBindingByTag(FName("NPC"), NpcActor, /*bAllowBindingsFromAsset=*/ true);
// Eliminar / restablecer
SeqActor->RemoveBindingByTag(FName("NPC"), NpcActor);
SeqActor->ResetBinding(HeroBindingID); // revertir al enlace del activo
SeqActor->ResetBindings(); // revertir todas las sobrescrituras
// Búsqueda por etiqueta
FMovieSceneObjectBindingID ID = SeqActor->FindNamedBinding(FName("Hero"));
const TArray<FMovieSceneObjectBindingID>& All = SeqActor->FindNamedBindings(FName("NPC"));
// Inspeccionar lo que está vinculado actualmente
TArray<UObject*> Bound = Player->GetBoundObjects(HeroBindingID);
// FMovieSceneObjectBindingID (MovieSceneObjectBindingID.h):
// Acceso a través de accesores públicos — los campos internos son privados:
// GetGuid() — FGuid que identifica la pista de enlace
// GetRelativeSequenceID() — qué subsecuencia lo contiene (0 = local)
Sistema de Cámaras
ACineCameraActor / UCineCameraComponent
// CineCameraActor.h: UCineCameraComponent* GetCineCameraComponent() const;
// CineCameraComponent.h / CineCameraSettings.h:
// FCameraFilmbackSettings Filmback (SensorWidth, SensorHeight en mm, SensorAspectRatio de solo lectura)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance cm, bSmoothFocusChanges)
// float CurrentFocalLength — Interp, animable en Sequencer
// float CurrentAperture — f-stop, Interp-animable
ACineCameraActor* Cam = GetWorld()->SpawnActor<ACineCameraActor>(SpawnTransform);
UCineCameraComponent* CC = Cam->GetCineCameraComponent();
FCameraFilmbackSettings FB;
FB.SensorWidth = 36.0f; FB.SensorHeight = 24.0f; // fotograma completo 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);
// Seguimiento 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);
// Evitar que la secuencia sobrescriba la cámara del juego (establecer antes de Play)
SeqActor->PlaybackSettings.bDisableCameraCuts = true;
// Restaurar la cámara del jugador después de la cutscene (llamar desde el delegado OnFinished)
APlayerController* PC = GetWorld()->GetFirstPlayerController();
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
PC->SetIgnoreMoveInput(false);
PC->SetIgnoreLookInput(false);
APlayerCameraManager
APlayerCameraManager (accedido a través de PlayerController->PlayerCameraManager) gestiona la
mezcla de cámaras y la selección del objetivo de vista para el jugador local. Después de que una cutscene termina, restaura la
cámara del juego explícitamente — Sequencer no lo hace automáticamente:
APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager maneja el estado de mezcla; SetViewTargetWithBlend lo activa.
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// La mezcla se procesa cada tick dentro de APlayerCameraManager::UpdateCamera.
Eventos de Sequencer
Las pistas de eventos llaman a UFUNCTIONs en objetos en el contexto del evento.
Contexto de evento predeterminado: UWorld + ALevelScriptActor.
// La función debe ser UFUNCTION(BlueprintCallable) en un objeto de contexto
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void TriggerExplosion()
{
ExplosionSystem->SpawnExplosion(ExplosionLocation);
}
// Activar código C++ en un fotograma específico reproduciendo hasta él (dispara todos los eventos en el rango)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(60), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
FMovieSceneEvent
FMovieSceneEvent contiene los datos del punto final del evento — la función vinculada a llamar cuando el evento
se dispara. Las pistas de eventos están estructuradas como:
UMovieSceneEventTrack— la pista maestra añadida a un enlace o como pista maestraUMovieSceneEventTriggerSection— una sección que contiene una o más entradas de activaciónFMovieSceneEvent— cada entrada dentro de la sección de activación, apuntando a la función del punto final
La función del punto final se resuelve en tiempo de ejecución contra los objetos del contexto del evento (por defecto
UWorld y ALevelScriptActor). Los eventos basados en director se resuelven contra una
instancia de subclase de ULevelSequenceDirector.
ULevelSequenceDirector — Contexto de Evento Personalizado
ULevelSequenceDirector proporciona un contexto de scripting por secuencia que recibe llamadas de pistas de eventos. Subclasifícalo (Blueprint o C++) y asígnalo a la propiedad Director Class del activo LevelSequence. La instancia del Director se crea cuando la secuencia comienza a reproducirse y se destruye cuando se detiene — su vida útil coincide con el reproductor de la secuencia.
// MySequenceDirector.h
#include "LevelSequenceDirector.h"
#include "MySequenceDirector.generated.h"
UCLASS(Blueprintable)
class UMySequenceDirector : public ULevelSequenceDirector
{
GENERATED_BODY()
public:
// Llamado desde pistas de eventos de Sequencer — vincular a una clave de evento en el editor de Sequencer
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnDialogueStart(FName SpeakerTag);
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnCutsceneChoice(int32 ChoiceIndex);
};
// MySequenceDirector.cpp
void UMySequenceDirector::OnDialogueStart(FName SpeakerTag)
{
// Acceder al reproductor de la secuencia y a los actores vinculados desde el Director.
// ULevelSequenceDirector.h: UPROPERTY ULevelSequencePlayer* Player (campo directo, sin getter)
TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
// Activar lógica del juego: UI, sistema de diálogo, enfoque de cámara, etc.
}
Por qué Director sobre Level Script: El Director viaja con el activo de la secuencia, no con el nivel. Reutilizable en todos los mapas. Soporta estado por secuencia (variables miembro). Los eventos de Level Script solo funcionan cuando la secuencia está colocada en ese nivel específico.
Pistas de MovieScene
// MovieScene.h — obtener del activo LevelSequence
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// Possessables (actores del mundo) — iterar por índice
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// Spawnables (actores propiedad de la secuencia) — iterar por índice
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}
// Pistas maestras (no vinculadas a ningún actor)
const TArray<UMovieSceneTrack*>& Masters = MS->GetTracks();
// Pistas en un enlace específico
const FMovieSceneBinding* B = MS->FindBinding(SomeGuid);
if (B) { for (UMovieSceneTrack* T : B->GetTracks()) { /* convertir a subtipo */ } }
| Clase de Pista | Propósito |
|---|---|
UMovieScene3DTransformTrack | Animación de transformación |
UMovieSceneSkeletalAnimationTrack | Animación de malla esquelética |
UMovieSceneEventTrack | Disparadores de eventos |
UMovieSceneAudioTrack | Audio |
UMovieSceneFadeTrack | Desvanecimiento de pantalla |
UMovieSceneCameraCutTrack | Cortes de cámara |
UMovieSceneSubTrack | Subsecuencias |
UMovieScenePropertyTrack | Animación arbitraria de UPROPERTY (clase base) |
Todos los tipos de pista requieren MovieSceneTracks en Build.cs.
Pistas personalizadas: subclase de UMovieSceneTrack + UMovieSceneSection para datos de animación
específicos del dominio. Registra a través de ISequencerModule::RegisterTrackEditor. Este es un patrón
avanzado — la mayoría de las necesidades se satisfacen con subclases de UMovieScenePropertyTrack.