Fertigkeit: ue-sequencer-cinematics
Sie sind Experte für Unreal Engines Sequencer und Filmsysteme.
Kontextprüfung
Lesen Sie .agents/ue-project-context.md, bevor Sie Filmcode für Folgendes schreiben:
- Ziel-UE-Version (API-Verfügbarkeit variiert – SequencePlayer-Eigenschaft seit 5.4+ veraltet)
- Filmanforderungen (Zwischensequenzen, In-Game-Kameras, Offline-Rendering)
- Multiplayer-Kontext (Sequenz-Replikationsverhalten unterscheidet sich)
- Bereits deklarierte Build.cs-Module
Informationssammlung
Fragen Sie nach:
- Filmtyp: Vollbild-Zwischensequenz, In-Game-Kamera oder Hintergrund-Umgebungssequenz
- Ob Akteure zur Laufzeit gebunden oder bereits im Level platziert sind
- Ob die Kamerasteuerung nach der Wiedergabe an den Spieler zurückgegeben werden muss
- Einmalige oder sich wiederholende Sequenz
- Echtzeit-Gameplay oder Offline-Movie-Render-Queue-Ausgabe
Build.cs-Module
PublicDependencyModuleNames.AddRange(new string[]
{
"LevelSequence", "MovieScene", "CinematicCamera",
});
// Nur für Offline-Rendering:
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");
Abspielen von Levelsequenzen
ALevelSequenceActor — Im Level platziert
ALevelSequenceActor besitzt den Player. Verwenden Sie GetSequencePlayer() – die direkte SequencePlayer-Eigenschaft ist seit UE 5.4 veraltet.
// LevelSequenceActor.h: ULevelSequencePlayer* GetSequencePlayer() const;
ULevelSequencePlayer* Player = SeqActor->GetSequencePlayer();
if (Player) { Player->Play(); }
ULevelSequencePlayer::CreateLevelSequencePlayer — Laufzeit-Spawn
// 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=einmal, -1=unendlich
Settings.bDisableMovementInput = true;
Settings.bDisableLookAtInput = true;
Settings.bHidePlayer = false;
Settings.bHideHud = false;
Settings.bDisableCameraCuts = false;
Settings.bPauseAtEnd = false;
Settings.FinishCompletionStateOverride =
EMovieSceneCompletionModeOverride::ForceRestoreState; // sicher für überspringbare Zwischensequenzen
ALevelSequenceActor* OutActor = nullptr;
ULevelSequencePlayer* Player = ULevelSequencePlayer::CreateLevelSequencePlayer(
this, Sequence, Settings, OutActor);
// OutActor in einer UPROPERTY speichern, um GC zu verhindern
ActiveSequenceActor = OutActor;
if (Player)
{
Player->OnFinished.AddDynamic(this, &AMyClass::OnCutsceneFinished);
Player->Play();
}
Wiedergabesteuerung (Basisklasse UMovieSceneSequencePlayer)
// MovieSceneSequencePlayer.h
Player->Play();
Player->PlayReverse();
Player->PlayLooping(-1); // -1 = unendliche Schleifen
Player->Pause();
Player->Stop(); // bewegt Cursor zum Ende, feuert OnStop
Player->StopAtCurrentTime();
Player->GoToEndAndStop();
Player->SetPlayRate(0.5f); // negativ = rückwärts
// Zu Frame springen (überspringt Ereignisse zwischen aktueller und Zielposition)
// Blueprint macht dies als GoToFrame verfügbar. In C++ SetPlaybackPosition mit Jump verwenden.
Player->SetPlaybackPosition(
FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump));
// Zu Frame abspielen (löst alle Ereignisse entlang des Weges aus)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(240), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
// Wiedergabebereich einschränken
Player->SetFrameRange(0, 60); // Frames 0–60
Player->SetTimeRange(0.0f, 2.5f); // Sekunden
// Zustandsabfrage
bool bPlaying = Player->IsPlaying();
FQualifiedFrameTime Now = Player->GetCurrentTime();
FQualifiedFrameTime Dur = Player->GetDuration();
// Delegates (vor Play binden)
Player->OnFinished.AddDynamic(this, &UMyClass::OnSeqFinished);
Player->OnPlay.AddDynamic(this, &UMyClass::OnSeqPlay);
Player->OnStop.AddDynamic(this, &UMyClass::OnSeqStop);
Player->OnNativeFinished.BindUObject(this, &UMyClass::OnNativeFinished); // nicht dynamisch
// Kameraschnitt-Ereignis (LevelSequencePlayer.h)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLevelSequencePlayerCameraCutEvent, UCameraComponent*, CameraComponent)
LsPlayer->OnCameraCut.AddDynamic(this, &UMyClass::OnCameraCut);
// Zustand bei vorzeitigem Stopp wiederherstellen (überspringbare Zwischensequenz)
Player->SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState);
Player->Stop();
// Sub-Sequenz-Snapshot
FLevelSequencePlayerSnapshot Snap;
Player->TakeFrameSnapshot(Snap);
// Snap.CurrentShotName, Snap.RootTime, Snap.CameraComponent, Snap.ActiveShot
Akteursbindung
Markieren Sie Bindungen im Sequencer (Rechtsklick auf Objektbindung -> Tags...) und überschreiben Sie sie dann zur Laufzeit.
Binden Sie immer vor dem Aufruf von Play().
Spawnables vs Possessables
Possessables binden an bereits existierende Weltakteure (im Level platziert oder durch Gameplay gespawnt). Spawnables sind Akteure, die die Sequenz selbst erstellt und zerstört.
// Spawnable: Sequenz besitzt den Akteur-Lebenszyklus
// Im Sequencer-Editor einstellen: Rechtsklick auf Akteurspur → "In Spawnable ändern"
// Zur Laufzeit wird der Akteur gespawnt, wenn die Sequenz seinen Bereich erreicht, und entspawnt, wenn sie ihn verlässt
// Dynamisches Possessable: Einen durch Gameplay gespawnten Akteur an eine Sequenzspur binden
// Erstellen Sie die Bindungs-ID im Editor, dann zur Laufzeit überschreiben:
FMovieSceneObjectBindingID BindingID = /* aus dem Sequencer-Editor */;
ALevelSequenceActor* SeqActor = /* Ihr Sequenzakteur */;
SeqActor->SetBinding(BindingID, {SpawnedActor});
Warum das wichtig ist: Verwenden Sie Possessables für persistente Weltakteure (Türen, Aufzüge) und Spawnables für flüchtige, nur in Zwischensequenzen vorkommende Akteure (nur-filmsche Charaktere, Requisiten). Possessables überleben das Ende der Sequenz; Spawnables werden automatisch bereinigt.
// LevelSequenceActor.h — die gesamte Bindungs-API befindet sich hier
// Gebundene Akteure ersetzen (bevorzugt: tag-basiert, widerstandsfähig gegen GUID-Änderungen)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
/*bAllowBindingsFromAsset=*/ false);
// GUID-basiert (FMovieSceneObjectBindingID über UPROPERTY für die Editor-Zuweisung verfügbar machen)
// UPROPERTY(EditAnywhere) FMovieSceneObjectBindingID HeroBindingID;
SeqActor->SetBinding(HeroBindingID, TArray<AActor*>{ HeroActor }, false);
// Anhängen ohne vorhandene Bindungen zu entfernen
SeqActor->AddBindingByTag(FName("NPC"), NpcActor, /*bAllowBindingsFromAsset=*/ true);
// Entfernen / Zurücksetzen
SeqActor->RemoveBindingByTag(FName("NPC"), NpcActor);
SeqActor->ResetBinding(HeroBindingID); // auf Asset-Bindung zurücksetzen
SeqActor->ResetBindings(); // alle Überschreibungen zurücksetzen
// Nach Tag suchen
FMovieSceneObjectBindingID ID = SeqActor->FindNamedBinding(FName("Hero"));
const TArray<FMovieSceneObjectBindingID>& All = SeqActor->FindNamedBindings(FName("NPC"));
// Prüfen, was derzeit gebunden ist
TArray<UObject*> Bound = Player->GetBoundObjects(HeroBindingID);
// FMovieSceneObjectBindingID (MovieSceneObjectBindingID.h):
// Zugriff über öffentliche Accessoren — interne Felder sind privat:
// GetGuid() — FGuid, der die Bindungsspur identifiziert
// GetRelativeSequenceID() — welche Sub-Sequenz sie enthält (0 = lokal)
Kamerasystem
ACineCameraActor / UCineCameraComponent
// CineCameraActor.h: UCineCameraComponent* GetCineCameraComponent() const;
// CineCameraComponent.h / CineCameraSettings.h:
// FCameraFilmbackSettings Filmback (SensorWidth, SensorHeight in mm, schreibgeschützt SensorAspectRatio)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance cm, bSmoothFocusChanges)
// float CurrentFocalLength — Interp, animierbar im Sequencer
// float CurrentAperture — f-stop, Interp-animierbar
ACineCameraActor* Cam = GetWorld()->SpawnActor<ACineCameraActor>(SpawnTransform);
UCineCameraComponent* CC = Cam->GetCineCameraComponent();
FCameraFilmbackSettings FB;
FB.SensorWidth = 36.0f; FB.SensorHeight = 24.0f; // Vollformat 35 mm
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-Tracking (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);
// Verhindern, dass die Sequenz die Gameplay-Kamera überschreibt (vor Play setzen)
SeqActor->PlaybackSettings.bDisableCameraCuts = true;
// Spielerkamera nach Zwischensequenz wiederherstellen (vom OnFinished-Delegaten aufrufen)
APlayerController* PC = GetWorld()->GetFirstPlayerController();
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
PC->SetIgnoreMoveInput(false);
PC->SetIgnoreLookInput(false);
APlayerCameraManager
APlayerCameraManager (zugänglich über PlayerController->PlayerCameraManager) verwaltet die Kamerablendung und die Auswahl des Blickziels für den lokalen Spieler. Stellen Sie nach dem Ende einer Zwischensequenz explizit die Gameplay-Kamera wieder her — der Sequencer macht dies nicht automatisch:
APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager verwaltet den Blend-Zustand; SetViewTargetWithBlend löst ihn aus.
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// Der Blend wird in jedem Tick innerhalb von APlayerCameraManager::UpdateCamera verarbeitet.
Sequencer-Ereignisse
Ereignisspuren rufen UFUNCTIONs an Objekten im Ereigniskontext auf.
Standard-Ereigniskontext: UWorld + ALevelScriptActor.
// Funktion muss UFUNCTION(BlueprintCallable) auf einem Kontextobjekt sein
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void TriggerExplosion()
{
ExplosionSystem->SpawnExplosion(ExplosionLocation);
}
// C++-Code an einem bestimmten Frame auslösen, indem Sie bis zu ihm abspielen (löst alle Ereignisse im Bereich aus)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(60), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
FMovieSceneEvent
FMovieSceneEvent enthält die Ereignisendpunktdaten — die gebundene Funktion, die aufgerufen wird, wenn das Ereignis ausgelöst wird. Ereignisspuren sind wie folgt aufgebaut:
UMovieSceneEventTrack— die Masterspur, die zu einer Bindung oder als Masterspur hinzugefügt wirdUMovieSceneEventTriggerSection— ein Abschnitt, der einen oder mehrere Auslöseeinträge enthältFMovieSceneEvent— jeder Eintrag innerhalb des Auslöseabschnitts, der auf die Endpunktfunktion zeigt
Die Endpunktfunktion wird zur Laufzeit gegen die Ereigniskontextobjekte aufgelöst (standardmäßig UWorld und ALevelScriptActor). Direktorbasierte Ereignisse werden gegen eine Instanz einer ULevelSequenceDirector-Unterklasse aufgelöst.
ULevelSequenceDirector — Benutzerdefinierter Ereigniskontext
ULevelSequenceDirector bietet einen pro-Sequenz-Scripting-Kontext, der Ereignisspur-Aufrufe empfängt. Unterklassifizieren Sie ihn (Blueprint oder C++) und weisen Sie ihn der Director Class-Eigenschaft des LevelSequence-Assets zu. Die Director-Instanz wird erstellt, wenn die Sequenz abgespielt wird, und zerstört, wenn sie stoppt — ihre Lebensdauer entspricht dem Sequenzplayer.
// MySequenceDirector.h
#include "LevelSequenceDirector.h"
#include "MySequenceDirector.generated.h"
UCLASS(Blueprintable)
class UMySequenceDirector : public ULevelSequenceDirector
{
GENERATED_BODY()
public:
// Vom Sequencer-Ereignisspuren aufgerufen — im Sequencer-Editor an Ereignisschlüssel binden
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnDialogueStart(FName SpeakerTag);
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnCutsceneChoice(int32 ChoiceIndex);
};
// MySequenceDirector.cpp
void UMySequenceDirector::OnDialogueStart(FName SpeakerTag)
{
// Zugriff auf den Sequenzplayer und die gebundenen Akteure innerhalb des Directors.
// ULevelSequenceDirector.h: UPROPERTY ULevelSequencePlayer* Player (direktes Feld, kein Getter)
TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
// Gameplay-Logik auslösen: UI, Dialogsystem, Kamerafokus, etc.
}
Warum Director gegenüber Level Script: Der Director reist mit dem Sequenz-Asset, nicht mit dem Level.Über mehrere Karten hinweg wiederverwendbar. Unterstützt pro-Sequenz-Zustand (Membervariablen). Level-Script-Ereignisse funktionieren nur, wenn die Sequenz in diesem bestimmten Level platziert ist.
MovieScene-Spuren
// MovieScene.h — vom LevelSequence-Asset abrufen
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// Possessables (Weltakteure) — nach Index iterieren
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// Spawnables (sequenzeigene Akteure) — nach Index iterieren
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}
// Masterspuren (nicht an einen Akteur gebunden)
const TArray<UMovieSceneTrack*>& Masters = MS->GetTracks();
// Spuren auf einer bestimmten Bindung
const FMovieSceneBinding* B = MS->FindBinding(SomeGuid);
if (B) { for (UMovieSceneTrack* T : B->GetTracks()) { /* in Untertyp casten */ } }
| Spurklasse | Zweck |
|---|---|
UMovieScene3DTransformTrack | Transformationsanimation |
UMovieSceneSkeletalAnimationTrack | Skelettmesh-Animation |
UMovieSceneEventTrack | Ereignisauslöser |
UMovieSceneAudioTrack | Audio |
UMovieSceneFadeTrack | Bildschirmüberblendung |
UMovieSceneCameraCutTrack | Kameraschnitte |
UMovieSceneSubTrack | Sub-Sequenzen |
UMovieScenePropertyTrack | Beliebige UPROPERTY-Animation (Basisklasse) |
Alle Spurtypen erfordern MovieSceneTracks in Build.cs.
Benutzerdefinierte Spuren: Unterklassifizieren Sie UMovieSceneTrack + UMovieSceneSection für domänenspezifische Animationsdaten. Registrieren Sie über ISequencerModule::RegisterTrackEditor. Dies ist ein fortgeschrittenes Muster – die meisten Anforderungen werden von UMovieScenePropertyTrack-Unterklassen erfüllt.