Générateurs de pistes personnalisés¶

La génération remplit les Level Sequences d'un dialogue en exécutant une liste de générateurs de pistes — un par type de piste Sequencer (animation, audio, caméras, événements, synchronisation labiale, sous-titres). Cette liste est ouverte : vous pouvez y ajouter votre propre générateur pour poser un type de piste Sequencer que Libretto ne fournit pas, et il participe exactement au même pipeline de génération que ceux intégrés.

Cette page couvre le point d'extension — la classe de base ULBRTrackGenerator, ses points de surcharge (hooks) et la manière d'enregistrer votre sous-classe pour qu'elle apparaisse dans les options Generate Sequences. Pour le pipeline qui pilote ces hooks, voir la Vue d'ensemble de la génération.

L'ancienne « Animatic Text Track » ne fait pas partie de Libretto

Une Animatic Text Track (texte d'animatique à l'écran avec position et fondu d'entrée/sortie) existait dans l'ensemble d'outils de l'éditeur interne BigBadTools. C'était un type de piste Sequencer distinct, non livré avec Libretto, et sans rapport avec le pipeline de génération de dialogue décrit ici. Si vous avez besoin de texte à l'écran pendant une séquence générée, écrivez un générateur de pistes personnalisé (ci-dessous) — c'est le point d'extension pris en charge.

Où se situent les générateurs de pistes¶

Lorsque vous appuyez sur Generate, le sous-système de génération charge les classes de générateurs de pistes enregistrées dans les réglages de projet, les instancie et appelle leurs hooks dans un ordre fixe pour chaque sous-dialogue, séquence et réplique. Chaque générateur possède un type de piste : il crée sa piste, la remplit réplique par réplique et nettoie sa sortie précédente lors d'une régénération.

Les générateurs intégrés — LBRAnimationTrackGenerator, LBRAudioTrackGenerator, LBRCameraTrackGenerator, LBREventTrackGenerator, LBRLipSyncTrackGenerator et LBRSubtitleTrackGenerator — sont tous des sous-classes de ULBRTrackGenerator. Votre propre classe rejoint la liste sur un pied d'égalité.

The Track Generators setting

La classe de base `ULBRTrackGenerator`¶

ULBRTrackGenerator est un UObject abstrait de type BlueprintType dans le module LBRSequenceGenerator. Chaque hook est un BlueprintNativeEvent, vous pouvez donc implémenter un générateur en C++ (surcharge du _Implementation) ou en Blueprint (surcharge de l'événement) — les générateurs de sous-titres et d'événements intégrés sont Blueprintable.

Pendant son exécution, le générateur peut accéder au contexte de génération partagé via son champ Generator, un pointeur vers le ULBRSequenceGenerator propriétaire (dialogue courant, instance de dialogue, séquence master, GUID de personnages en cache, données par phrase, etc.).

Identité de la piste — `GetTrackID`¶

UFUNCTION(BlueprintNativeEvent, Category = "Generation")
FGameplayTag GetTrackID() const;

Renvoie le GameplayTag qui identifie le type de piste que ce générateur produit. Il sert à filtrer quels générateurs s'exécutent pour une requête de génération donnée : un générateur s'exécute lorsque la requête porte soit son tag GetTrackID(), soit le drapeau fourre-tout Libretto.Generation.Tracks.All.

L'implémentation de base renvoie Libretto.Generation.Tracks (TAG_LBRFlag_TrackTypeRoot), la racine de la hiérarchie des types de pistes. Les générateurs intégrés renvoient des tags feuilles sous celle-ci, par exemple :

Générateur	Track ID
`LBRAnimationTrackGenerator`	`Libretto.Generation.Tracks.PostureGesture`
`LBRAudioTrackGenerator`	`Libretto.Generation.Tracks.Audio`
`LBRCameraTrackGenerator`	`Libretto.Generation.Tracks.Camera`
`LBREventTrackGenerator`	`Libretto.Generation.Tracks.Event`
`LBRSubtitleTrackGenerator`	`Libretto.Generation.Tracks.Subtitle`

Définissez votre propre tag feuille sous Libretto.Generation.Tracks et renvoyez-le ici, afin que votre piste puisse être activée indépendamment dans le wizard Generate Sequences. Plusieurs générateurs peuvent partager le même Track ID si vous souhaitez les activer ensemble.

Le drapeau All

Une génération complète est normalement lancée avec Libretto.Generation.Tracks.All coché, ce qui écrase tous les types de pistes enregistrés — le vôtre inclus — indépendamment des cases à cocher par piste. C'est la valeur par défaut de Tracks to Generate ; sans lui, une génération peut produire un résultat vide. Voir Running generation.

Hooks de cycle de vie¶

Tous les hooks sont facultatifs (BlueprintNativeEvent) ; la base ne fait rien, ne surchargez donc que ceux dont vous avez besoin. Ils sont appelés dans cet ordre au cours d'une génération :

Hook	Signature (paramètres)	Quand il s'exécute	Usage typique
`InitDialogue`	`(const FLBRGameplayTagFlags& Options)`	Une fois, au début d'un dialogue.	Construire des caches / fabriques valables pour tout le dialogue.
`InitSubDialogue`	`(ULBRSubdialogue* Subdialogue, const FLBRGameplayTagFlags& Options)`	À chaque changement de sous-dialogue (mise en place de la scène).	Réinitialiser l'état propre au sous-dialogue.
`InitSequence`	`(ULevelSequence* CurrentSequence, const FLBRSequence& DialogueSequence, const FLBRGameplayTagFlags& Options)`	Lorsqu'un asset de séquence (non verrouillé) est (re)construit.	Créer et initialiser vos véritables pistes/sections Sequencer dans l'asset.
`CleanSequence`	`(ULevelSequence* CurrentSequence, const FLBRGameplayTagFlags& Options)`	Lors de la régénération d'une séquence réutilisée.	Supprimer vos pistes/sections précédemment générées pour qu'elles puissent être reconstruites.
`InitSentenceData`	`(int32 CurrentIndex, ULevelSequence* CurrentSequence, const FLBRSequence& DialogueSequence, FLBRSequenceSentenceData& SentenceData, const FLBRGameplayTagFlags& Options)`	Par réplique, avant que tout générateur ne la remplisse.	Influencer les données partagées par phrase (p. ex. allonger la durée de la réplique) avant que d'autres ne les lisent.
`PopulateSequenceForLine`	(mêmes paramètres que ci-dessus, renvoie `FLBRGameplayTagFlags`)	Par réplique.	Générer le contenu de ce générateur pour la réplique. Peut renvoyer des drapeaux demandant une génération supplémentaire.
`FinishSequence`	`(ULevelSequence* CurrentSequence, const FLBRSequence& DialogueSequence, const FLBRGameplayTagFlags& Options)`	Après que toutes les répliques d'une séquence ont été remplies.	Finaliser la séquence — vous pouvez analyser les données produites par d'autres générateurs.
`FinishGeneration`	`()`	Une fois, tout à la fin.	Nettoyage final, sauvegarde des journaux, libération des caches.

Nettoyer derrière soi

Chaque générateur est responsable de supprimer les pistes qu'il a créées précédemment avant de les recréer — faites-le dans CleanSequence. Les pistes placées sous un dossier listé dans Folder Names To Save (par défaut VFX, Audio) ne sont pas écrasées lors d'une régénération, même avec le drapeau All, ce qui permet aux ajouts faits à la main de survivre.

`PopulateSequenceForLine` — le hook central¶

UFUNCTION(BlueprintNativeEvent, Category = "Generation")
FLBRGameplayTagFlags PopulateSequenceForLine(
    int32                       CurrentIndex,
    ULevelSequence*             CurrentSequence,
    const FLBRSequence&         DialogueSequence,
    FLBRSequenceSentenceData&   SentenceData,
    const FLBRGameplayTagFlags& Options);

C'est là que la plupart des générateurs font leur travail. Pour la réplique à CurrentIndex, ajoutez des sections à la piste que vous avez créée dans InitSequence, en lisant les données par réplique résolues depuis SentenceData (locuteur/auditeur, durée de la réplique, destinations goto…). La base renvoie FLBRGameplayTagFlags::EmptyFlags ; ne renvoyez des drapeaux non vides que si la réplique nécessite une génération supplémentaire (le générateur d'événements intégré, par exemple, peut demander une séquence de boucle de suivi).

Écrire votre propre générateur¶

Créez une classe dérivant de ULBRTrackGenerator — une UCLASS C++ ou un Blueprint (la base est BlueprintType ; rendez votre sous-classe C++ Blueprintable si vous voulez l'étendre davantage en Blueprint, comme le font les générateurs de sous-titres/d'événements livrés).
Définissez un tag de piste feuille sous Libretto.Generation.Tracks et renvoyez-le depuis GetTrackID.
Surchargez les hooks dont vous avez besoin — au minimum InitSequence (créer votre piste), CleanSequence (supprimer votre piste précédente) et PopulateSequenceForLine (la remplir par réplique).
Enregistrez la classe dans les réglages de projet (ci-dessous). Elle apparaît alors dans la liste Tracks to Generate du wizard Generate Sequences et s'exécute avec les autres.

Creating a generator class

Partez d'un générateur intégré

La référence la plus simple est LBRSubtitleTrackGenerator : il ne surcharge que GetTrackID, InitSequence, PopulateSequenceForLine et CleanSequence — exactement la forme minimale d'un nouveau type de piste.

Enregistrer le générateur¶

Les générateurs de pistes sont enregistrés dans Project Settings ▸ Libretto – Sequence Generator (la classe ULBRSequenceGeneratorSettings), dans le tableau Track Generators. Ajoutez-y votre classe ; la liste par défaut contient les six générateurs intégrés :

Libretto – Sequence Generator ▸ Track Generators
  LBRAnimationTrackGenerator
  LBRAudioTrackGenerator
  LBRCameraTrackGenerator
  LBREventTrackGenerator
  LBRLipSyncTrackGenerator
  LBRSubtitleTrackGenerator
  ← add your class here

Ce tableau est ce qui pilote la liste Tracks to Generate du wizard Generate Sequences : une fois enregistré, votre générateur y apparaît et peut être activé/désactivé comme n'importe quel autre type de piste.

Les générateurs d'assets sont une liste distincte

Si votre piste consomme un nouveau type d'asset qui doit être produit au préalable (comme les pistes audio consomment l'audio TTS), cette production d'asset relève d'un générateur d'assets (ULBRAssetGenerator, enregistré dans la liste Asset Generators) — la génération d'assets s'exécute avant la génération de pistes. Voir Asset generators.