Skill : ue-sequencer-cinematics
Vous êtes un expert du Sequencer d'Unreal Engine et des systèmes cinématiques.
Vérification du Contexte
Lisez .agents/ue-project-context.md avant d'écrire du code cinématique pour :
- La version cible d'UE (la disponibilité des API varie — la propriété SequencePlayer est dépréciée depuis UE 5.4+)
- Les exigences cinématiques (scènes cinématiques, caméras in-game, rendu hors ligne)
- Le contexte multijoueur (le comportement de réplication des séquences diffère)
- Les modules Build.cs déjà déclarés
Collecte d'Informations
Demandez :
- Le type de cinématique : scène cinématique plein écran, caméra in-game ou séquence d'ambiance en arrière-plan
- Si les acteurs sont liés à l'exécution ou pré-placés dans le niveau
- Si le contrôle de la caméra doit revenir au joueur après la lecture
- Séquence unique ou en boucle
- Gameplay en temps réel ou sortie Movie Render Queue hors ligne
Modules Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{
"LevelSequence", "MovieScene", "CinematicCamera",
});
// Rendu hors ligne uniquement :
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");
Lecture des Level Sequences
ALevelSequenceActor — Placé dans le Monde
ALevelSequenceActor possède le lecteur. Utilisez GetSequencePlayer() — la propriété directe SequencePlayer
est dépréciée depuis UE 5.4.
// LevelSequenceActor.h : ULevelSequencePlayer* GetSequencePlayer() const;
ULevelSequencePlayer* Player = SeqActor->GetSequencePlayer();
if (Player) { Player->Play(); }
ULevelSequencePlayer::CreateLevelSequencePlayer — Apparition à l'Exécution
// 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=une fois, -1=infini
Settings.bDisableMovementInput = true;
Settings.bDisableLookAtInput = true;
Settings.bHidePlayer = false;
Settings.bHideHud = false;
Settings.bDisableCameraCuts = false;
Settings.bPauseAtEnd = false;
Settings.FinishCompletionStateOverride =
EMovieSceneCompletionModeOverride::ForceRestoreState; // sûr pour les scènes cinématiques interrompables
ALevelSequenceActor* OutActor = nullptr;
ULevelSequencePlayer* Player = ULevelSequencePlayer::CreateLevelSequencePlayer(
this, Sequence, Settings, OutActor);
// Stockez OutActor dans une UPROPERTY pour éviter le GC
ActiveSequenceActor = OutActor;
if (Player)
{
Player->OnFinished.AddDynamic(this, &AMyClass::OnCutsceneFinished);
Player->Play();
}
Contrôle de Lecture (base UMovieSceneSequencePlayer)
// MovieSceneSequencePlayer.h
Player->Play();
Player->PlayReverse();
Player->PlayLooping(-1); // -1 = boucles infinies
Player->Pause();
Player->Stop(); // déplace le curseur à la fin, déclenche OnStop
Player->StopAtCurrentTime();
Player->GoToEndAndStop();
Player->SetPlayRate(0.5f); // négatif = inverse
// Saut à une image (saute les événements entre l'image actuelle et la cible)
// Blueprint expose ceci comme GoToFrame. En C++, utilisez SetPlaybackPosition avec Jump.
Player->SetPlaybackPosition(
FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump));
// Jouer jusqu'à une image (déclenche tous les événements en cours de route)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(240), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
// Restreindre la plage de lecture
Player->SetFrameRange(0, 60); // images 0–60
Player->SetTimeRange(0.0f, 2.5f); // secondes
// Interrogation d'état
bool bPlaying = Player->IsPlaying();
FQualifiedFrameTime Now = Player->GetCurrentTime();
FQualifiedFrameTime Dur = Player->GetDuration();
// Délégations (à lier avant 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-dynamique
// Événement de coupe caméra (LevelSequencePlayer.h)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLevelSequencePlayerCameraCutEvent, UCameraComponent*, CameraComponent)
LsPlayer->OnCameraCut.AddDynamic(this, &UMyClass::OnCameraCut);
// Restaurer l'état sur arrêt anticipé (scène cinématique interrompable)
Player->SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState);
Player->Stop();
// Instantané de sous-séquence
FLevelSequencePlayerSnapshot Snap;
Player->TakeFrameSnapshot(Snap);
// Snap.CurrentShotName, Snap.RootTime, Snap.CameraComponent, Snap.ActiveShot
Liaison d'Acteurs (Actor Binding)
Créez des tags de liaison dans le Sequencer (clic droit sur la liaison d'objet -> Tags...) puis remplacez à l'exécution.
Toujours lier avant d'appeler Play().
Spawnables vs Possessables
Possessables se lient à des acteurs mondiaux préexistants (placés dans le niveau ou apparus via le gameplay). Spawnables sont des acteurs que la séquence elle-même crée et détruit.
// Spawnable : la séquence possède le cycle de vie de l'acteur
// Défini dans l'éditeur Sequencer : clic droit sur la piste d'acteur → "Changer en Spawnable"
// À l'exécution, l'acteur apparaît lorsque la séquence atteint sa plage et disparaît lorsqu'il la quitte
// Possessable dynamique : lier un acteur apparu via le gameplay à une piste de séquence
// Créez l'ID de liaison dans l'éditeur, puis remplacez à l'exécution :
FMovieSceneObjectBindingID BindingID = /* depuis l'éditeur de séquence */;
ALevelSequenceActor* SeqActor = /* votre acteur de séquence */;
SeqActor->SetBinding(BindingID, {SpawnedActor});
Pourquoi c'est important : Utilisez les Possessables pour les acteurs mondiaux persistants (portes, ascenseurs) et les Spawnables pour les acteurs transitoires propres aux scènes cinématiques (personnages de cinématique, accessoires). Les Possessables survivent à la fin de la séquence ; les Spawnables sont nettoyés automatiquement.
// LevelSequenceActor.h — toute l'API de liaison se trouve ici
// Remplacer les acteurs liés (préféré : basé sur les tags, résistant aux changements de GUID)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
/*bAllowBindingsFromAsset=*/ false);
// Basé sur GUID (exposer FMovieSceneObjectBindingID via UPROPERTY pour l'affectation dans l'éditeur)
// UPROPERTY(EditAnywhere) FMovieSceneObjectBindingID HeroBindingID;
SeqActor->SetBinding(HeroBindingID, TArray<AActor*>{ HeroActor }, false);
// Ajouter sans supprimer les liaisons existantes
SeqActor->AddBindingByTag(FName("NPC"), NpcActor, /*bAllowBindingsFromAsset=*/ true);
// Supprimer / réinitialiser
SeqActor->RemoveBindingByTag(FName("NPC"), NpcActor);
SeqActor->ResetBinding(HeroBindingID); // revenir à la liaison de l'asset
SeqActor->ResetBindings(); // revenir à toutes les liaisons de l'asset
// Recherche par tag
FMovieSceneObjectBindingID ID = SeqActor->FindNamedBinding(FName("Hero"));
const TArray<FMovieSceneObjectBindingID>& All = SeqActor->FindNamedBindings(FName("NPC"));
// Inspecter ce qui est actuellement lié
TArray<UObject*> Bound = Player->GetBoundObjects(HeroBindingID);
// FMovieSceneObjectBindingID (MovieSceneObjectBindingID.h) :
// Accès via des accesseurs publics — les champs internes sont privés :
// GetGuid() — FGuid identifiant la piste de liaison
// GetRelativeSequenceID() — quelle sous-séquence le contient (0 = locale)
Système de Caméra
ACineCameraActor / UCineCameraComponent
// CineCameraActor.h : UCineCameraComponent* GetCineCameraComponent() const;
// CineCameraComponent.h / CineCameraSettings.h :
// FCameraFilmbackSettings Filmback (SensorWidth, SensorHeight en mm, SensorAspectRatio en lecture seule)
// FCameraLensSettings LensSettings (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop en mm)
// FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance en cm, bSmoothFocusChanges)
// float CurrentFocalLength — Interp, animatable dans Sequencer
// float CurrentAperture — f-stop, Interp-animatable
ACineCameraActor* Cam = GetWorld()->SpawnActor<ACineCameraActor>(SpawnTransform);
UCineCameraComponent* CC = Cam->GetCineCameraComponent();
FCameraFilmbackSettings FB;
FB.SensorWidth = 36.0f; FB.SensorHeight = 24.0f; // plein format 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);
// Suivi du regard (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);
// Empêcher la séquence de remplacer la caméra de gameplay (définir avant Play)
SeqActor->PlaybackSettings.bDisableCameraCuts = true;
// Restaurer la caméra du joueur après la scène cinématique (appeler depuis le délégué OnFinished)
APlayerController* PC = GetWorld()->GetFirstPlayerController();
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
PC->SetIgnoreMoveInput(false);
PC->SetIgnoreLookInput(false);
APlayerCameraManager
APlayerCameraManager (accessible via PlayerController->PlayerCameraManager) gère le mélange
de caméra et la sélection de la cible de vue pour le joueur local. Après la fin d'une scène cinématique,
restaurez explicitement la caméra de gameplay — le Sequencer ne le fait pas automatiquement :
APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager gère l'état de mélange ; SetViewTargetWithBlend le déclenche.
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// Le mélange est traité à chaque tick dans APlayerCameraManager::UpdateCamera.
Événements Sequencer
Les pistes d'événements appellent des UFUNCTIONs sur les objets du contexte d'événement.
Contexte d'événement par défaut : UWorld + ALevelScriptActor.
// La fonction doit être UFUNCTION(BlueprintCallable) sur un objet de contexte
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void TriggerExplosion()
{
ExplosionSystem->SpawnExplosion(ExplosionLocation);
}
// Déclencher du code C++ à une image spécifique en jouant jusqu'à elle (déclenche tous les événements dans la plage)
Player->PlayTo(
FMovieSceneSequencePlaybackParams(FFrameTime(60), EUpdatePositionMethod::Play),
FMovieSceneSequencePlayToParams());
FMovieSceneEvent
FMovieSceneEvent contient les données du point d'extrémité de l'événement — la fonction liée à appeler lorsque l'événement
déclenche. Les pistes d'événements sont structurées comme suit :
UMovieSceneEventTrack— la piste maîtresse ajoutée à une liaison ou comme piste maîtresseUMovieSceneEventTriggerSection— une section contenant une ou plusieurs entrées de déclenchementFMovieSceneEvent— chaque entrée dans la section de déclenchement, pointant vers la fonction d'extrémité
La fonction d'extrémité est résolue à l'exécution par rapport aux objets du contexte d'événement (par défaut
UWorld et ALevelScriptActor). Les événements basés sur le directeur se résolvent par rapport à une
instance de sous-classe ULevelSequenceDirector.
ULevelSequenceDirector — Contexte d'Événement Personnalisé
ULevelSequenceDirector fournit un contexte de script par séquence qui reçoit les appels de piste d'événement.
Sous-classez-le (Blueprint ou C++) et assignez-le à la propriété Director Class de l'asset LevelSequence.
L'instance Director est créée lorsque la séquence commence à jouer et détruite lorsqu'elle s'arrête —
sa durée de vie correspond à celle du lecteur de séquence.
// MySequenceDirector.h
#include "LevelSequenceDirector.h"
#include "MySequenceDirector.generated.h"
UCLASS(Blueprintable)
class UMySequenceDirector : public ULevelSequenceDirector
{
GENERATED_BODY()
public :
// Appelé depuis les pistes d'événements Sequencer — lier à la touche d'événement dans l'éditeur Sequencer
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnDialogueStart(FName SpeakerTag);
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void OnCutsceneChoice(int32 ChoiceIndex);
};
// MySequenceDirector.cpp
void UMySequenceDirector::OnDialogueStart(FName SpeakerTag)
{
// Accéder au lecteur de séquence et aux acteurs liés depuis l'intérieur du Director.
// ULevelSequenceDirector.h : UPROPERTY ULevelSequencePlayer* Player (champ direct, pas de getter)
TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
// Déclencher la logique de gameplay : UI, système de dialogue, mise au point de la caméra, etc.
}
Pourquoi Director plutôt que Level Script : Le Director voyage avec l'asset de séquence, pas le niveau. Réutilisable entre les cartes. Prend en charge l'état par séquence (variables membres). Les événements Level Script ne fonctionnent que lorsque la séquence est placée dans ce niveau spécifique.
Pistes MovieScene
// MovieScene.h — obtenez-les depuis l'asset LevelSequence
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();
// Possessables (acteurs mondiaux) — itérer par index
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// Spawnables (acteurs possédés par la séquence) — itérer par index
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}
// Pistes maîtresses (non liées à un acteur)
const TArray<UMovieSceneTrack*>& Masters = MS->GetTracks();
// Pistes sur une liaison spécifique
const FMovieSceneBinding* B = MS->FindBinding(SomeGuid);
if (B) { for (UMovieSceneTrack* T : B->GetTracks()) { /* caster vers le sous-type */ } }
| Classe de Piste | Objectif |
|---|---|
UMovieScene3DTransformTrack | Animation de transformation |
UMovieSceneSkeletalAnimationTrack | Animation de maillage squelettique |
UMovieSceneEventTrack | Déclencheurs d'événements |
UMovieSceneAudioTrack | Audio |
UMovieSceneFadeTrack | Fondu d'écran |
UMovieSceneCameraCutTrack | Coupes de caméra |
UMovieSceneSubTrack | Sous-séquences |
UMovieScenePropertyTrack | Animation UPROPERTY arbitraire (classe de base) |
Tous les types de pistes nécessitent MovieSceneTracks dans Build.cs.
Pistes personnalisées : sous-classez UMovieSceneTrack + UMovieSceneSection pour des données
d'animation spécifiques au domaine. Enregistrez via ISequencerModule::RegisterTrackEditor. C'est un modèle
avancé — la plupart des besoins sont satisfaits par les sous-classes de UMovieScenePropertyTrack.