Aller au contenu

Référence de l'API Blueprint

Un index compact des principaux points d'entrée appelables en Blueprint dont un programmeur de jeu a besoin pour piloter Libretto à l'exécution. Ceci est une référence, pas un tutoriel — pour la version narrative (modes de mise en scène, comment câbler un déclencheur, patterns de fin de dialogue), lisez Jouer des dialogues à l'exécution. Pour les GPVars et les conditions, voir GPVars et Conditions.

La palette est la source de vérité

Cette page liste uniquement les fonctions clés. Chaque fonction ci-dessous est un véritable UFUNCTION ; les noms de node exacts, les infobulles et les nombreuses fonctions utilitaires secondaires se parcourent au mieux depuis la palette Blueprint dans l'éditeur (recherchez Libretto, Dialogue ou GPVar) ou le details panel d'une Dialogue Instance / du Dialogue Manager.

Les points d'entrée vivent sur trois classes réparties sur trois modules :

Classe Module Type Rôle
ALBRDialogueInstance LBRCore Actor L'instance placée (ou spawnée) sur laquelle vous démarrez un dialogue.
ULBRDialogueManager LBRCore World subsystem Enregistre, arrête et liste les dialogues en cours ; diffuse les événements globaux.
ULBRGPVarSubsystem LBRTags Engine subsystem Lit/écrit les GPFlags et les GPCounters.
ILBRDialogueCharacter LBRCore Interface Implémentée par tout personnage prenant part à un dialogue.
ULBRCondition LBRConditions Object Classe de base pour les conditions dynamiques.
ULBRDialogueReadingLibrary LBRCore Function library Lit un Dialogue en dehors du Sequencer (interfaces 2D).

Démarrer des dialogues

Vous démarrez un dialogue en appelant une fonction StartDialogue* sur l'ALBRDialogueInstance. Elles ne diffèrent que par la manière dont le sous-dialogue cible est choisi (voir Sélecteurs de sous-dialogue). Chacune prend un EndEvent (FDialogueEndEventDelegate) qui se déclenche à la fin de cette lecture — voir Événements de fin.

Sur une Dialogue Instance placée — ALBRDialogueInstance

Fonction Objet Paramètres clés Renvoie
StartDialogueInstance Démarre sans spécifier de sous-dialogue (le premier jouable). EndEvent bool (démarré)
StartDialogueWithSelector Choisit le sous-dialogue par un seul tag de sélecteur. Selector : FGameplayTag, EndEvent bool
StartDialogueWithSelectors Fait correspondre un ensemble de sélecteurs que le sous-dialogue doit porter. Selectors : FLBRGameplayTagFlags, EndEvent bool
StartDialogueWithSelectorQuery Fait correspondre une requête de sélecteur exacte (p. ex. A et B mais pas C). SelectorQuery : FGameplayTagQuery, EndEvent bool
StartDialogueWithAnySelector Combine tag + sélecteurs + requête d'un coup. Selector, Selectors, SelectorQuery, EndEvent bool

StartDialogue(SubdialogueName) est déprécié

L'ancien StartDialogue(FName SubdialogueName, EndEvent) sur l'instance (et le manager) est marqué DeprecatedFunction. Préférez les fonctions basées sur les sélecteurs ci-dessus.

Recompilez si les tags de sélecteur semblent périmés

Les pins de sélecteur sont renseignés à partir des tags du dialogue. S'ils sont périmés sur un node, recompilez le Blueprint.

Dialogues génériques — statiques sur ALBRDialogueInstance

Un dialogue générique se joue sans instance placée (message vocal, voix au téléphone, audio non rattaché). Les mêmes variantes de sélection existent en tant que fonctions statiques ; vous passez une transform de spawn et récupérez l'ALBRDialogueInstance spawné.

Fonction Objet Paramètres clés Renvoie
StartGenericDialogue Démarre à partir d'une struct entry-point générique. WorldContextObject, EntryPoint : FLBRGenericDialogueEntryPoint, EndEvent ALBRDialogueInstance*
StartGenericDialogueWithSelector Démarrage générique, tag de sélecteur unique. WorldContextObject, Dialogue, Selector : FGameplayTag, Transform, EndEvent ALBRDialogueInstance*
StartGenericDialogueWithSelectors Démarrage générique, ensemble de sélecteurs. WorldContextObject, Dialogue, Selectors : FLBRGameplayTagFlags, Transform, EndEvent ALBRDialogueInstance*
StartGenericDialogueWithSelectorQuery Démarrage générique, requête de sélecteur. WorldContextObject, Dialogue, SelectorQuery : FGameplayTagQuery, Transform, EndEvent ALBRDialogueInstance*

Warning

Le dialogue doit d'abord avoir été généré en tant que dialogue générique (clic droit sur l'asset ▸ generate as generic).

Vous ne savez pas lequel vous détenez ? — statiques sur ALBRDialogueInstance

Fonction Objet Paramètres clés Renvoie
StartDialogueWithAnyEntryPoint Démarre une instance placée ou un dialogue générique à partir d'une seule valeur entry-point. WorldContextObject, EntryPoint : FLBRAnyDialogueEntryPoint, EndEvent ALBRDialogueInstance*

FLBRAnyDialogueEntryPoint porte un Dialogue ou une DialogueInstance, plus une transform de spawn et des sélecteurs — le point d'entrée recommandé pour les déclencheurs placés par les designers. Voir Déclencher un dialogue depuis vos propres objets.

Fonction utilitaire pour le menu déroulant d'entry-point

Pour renseigner le menu déroulant de sélecteurs sur votre propre propriété FLBRAnyDialogueEntryPoint, appelez la fonction utilitaire statique ALBRDialogueInstance::GetSubdialogueSelectorsCategoriesFromAnyEntryPoint(EntryPoint) depuis votre surcharge GetGPTagRootFilter / GetSubdialogueSelectorsCategories.

Sur le Dialogue Manager — ULBRDialogueManager

Le manager expose également quelques fonctions de démarrage (pratiques lorsque vous détenez déjà le subsystem) :

Fonction Objet Paramètres clés Renvoie
StartDialogueInstance Démarre une instance placée (pas de sélection de sous-dialogue). DialogueInstance : ALBRDialogueInstance* bool
StartDialogueWithEntryPoint Démarre à partir d'un FLBRDialogueEntryPoint. EntryPoint : FLBRDialogueEntryPoint bool
StartDialogueAtTime Démarre le sequence player de l'instance à un instant donné (secondes). DialogueStartTime : float, DialogueInstance —

Accès au manager

ULBRDialogueManager est un World subsystem — obtenez-le via Get Subsystem (World Subsystem) sur un world-context object.

Arrêter & interroger — ULBRDialogueManager

Pour arrêter un dialogue en cours, vous passez l'instance et une raison de fin (FLBRGameplayTagFlags).

Fonction Objet Paramètres clés
StopDialogue Arrête une instance en cours. DialogueInstance, EndReason : FLBRGameplayTagFlags
StopDialogueInstancesForDialogue Arrête chaque instance en cours d'un asset Dialogue donné. Dialogue : ULBRDialogue*, EndReason
StopDialogueInstancesInvolving Arrête chaque instance en cours impliquant un personnage donné. DialogueCharacter : TScriptInterface<ILBRDialogueCharacter>, EndReason
StopAll Arrête chaque dialogue en cours. EndReason
PauseDialogue Met en pause un dialogue en cours (⚠️ tous les dialogues ne supportent pas la pause). DialogueInstance, PauseReason : FLBRGameplayTagFlags
Propriété en lecture seule Type Objet
RunningDialogues TArray<ALBRDialogueInstance*> Chaque dialogue actuellement en cours.
FocusedDialogue ALBRDialogueInstance* Le dialogue détenant actuellement le focus.

Événements de fin & délégués

Il existe trois manières de réagir à la fin d'un dialogue — choisissez selon la portée.

Mécanisme Où Type Se déclenche…
Pin End Event (EndEvent) Argument de chaque StartDialogue* FDialogueEndEventDelegate (ULBRSubdialogue*, EndReason) Uniquement pour cet appel StartDialogue*.
DialogueEndEvent Propriété sur ALBRDialogueInstance FDialogueEndEventMulticastDelegate (multicast) À chaque sortie de cette instance.
OnDialogueEnd Propriété sur ULBRDialogueManager FOnDialogueEnd (ALBRDialogueInstance*, EndReason) À chaque fin de dialogue, globalement.

Warning

Le pin End Event ne se déclenche que pour la lecture que vous avez démarrée. Si le même dialogue est ensuite lancé d'une autre manière (un déclencheur, par exemple), ce pin n'est pas appelé — utilisez DialogueEndEvent ou OnDialogueEnd pour un hook persistant.

En Blueprint, ajoutez l'événement d'instance via Actor menu ▸ Add Event ▸ DialogueEndEvent. En interne, le pin par-démarrage est le délégué à usage unique DialogueEndOnce de l'instance.

Autres délégués du manager (BlueprintAssignable)

ULBRDialogueManager diffuse également OnDialogueStarted, OnSubdialogueStarted, OnSubdialogueEnd, OnSubtitleDisplayed, OnSubtitleHidden, OnDialogueSetTags, et OnDialogueRemoveTags. Voir le manager dans la palette pour leurs signatures.

Personnages — ILBRDialogueCharacter (interface)

Tout actor/objet prenant part à un dialogue implémente ILBRDialogueCharacter (module LBRCore). Tous les membres sont des BlueprintNativeEvent (à surcharger en C++ ou en Blueprint). Les deux plus couramment surchargés :

Fonction Objet Signature
LBRGetCharacterName Nom d'affichage localisé (sous-titres, UI). Par défaut, le nom de la classe. FText LBRGetCharacterName() const
LBRGetCharacterGender Pilote la sélection de voix TTS. ELBRCharacterGender LBRGetCharacterGender() const
Interface complète (tous BlueprintNativeEvent)
Fonction Renvoie Objet
LBRGetBodyComponent USkeletalMeshComponent* Mesh du corps à lier dans les séquences générées.
LBRGetHeadComponent USkeletalMeshComponent* Mesh de la tête (visage) pour la génération faciale.
SetLookAtTarget — Oriente le personnage vers un actor cible.
RequestStartDialogue — L'instance a besoin que ce personnage soit prêt ; appelez ULBRDialogueManager::OnDialogueCharacterReadyForDialogue une fois terminé (supporte le walk-to avant d'être prêt).
RequestEndDialogue bool L'instance demande au personnage de terminer.
DialogueSwitch — Appelée lors du passage d'un dialogue à un autre.
FindWorldInstance UObject* Résout l'instance à utiliser pour jouer un dialogue dans un monde (appelée sur le CDO).
SetupEditorPreview — Prépare le personnage pour l'aperçu d'animation dans l'éditeur/Sequencer.
GetIgnoredTracks / GetGenerationFlags FLBRGameplayTagFlags Ignore certaines tracks à la génération (p. ex. lipsync en FPS).
GetLipsyncModel FString Identifiant de modèle pour la génération de lipsync.
GetStageRoles FGameplayTagContainer Rôles de mise en scène utilisés pour faire correspondre ce personnage à un slot de stage.

Bases prêtes à l'emploi

ALBRSimpleDialogueCharacter (mesh) et ULBRIntangibleCharacter (voix seule : narrateur, téléphone) implémentent déjà l'interface — implémentez LBRGetCharacterName une fois dans votre classe de base à partir d'une propriété Name/CharacterName.

GPVars — ULBRGPVarSubsystem (module LBRTags)

Flags et compteurs indexés par un FGPTagPath. Obtenez le subsystem avec la fonction statique GetGPVarSubsystem (BlueprintPure) ; chaque opération ci-dessous possède aussi une variante statique (Static_*, exposée sous son nom d'affichage simple, p. ex. RaiseGPFlag) pour l'appeler sans détenir d'abord le subsystem. Voir GPVars pour le modèle.

Flags

Node Objet Paramètres Renvoie
RaiseGPFlag Lève un flag. Path bool (false si déjà levé)
LowerGPFlag Abaisse un flag. Path bool (false si non levé)
CheckGPFlag Le flag est-il levé ? Path, bExact bool
CheckNotGPFlag Le flag est-il non levé ? Path, bExact bool
RaiseGPFlags / LowerGPFlags Lève / abaisse plusieurs flags dans un path. Path, GPFlags, (bExact) FGameplayTagContainer (réellement modifiés)
SetGPFlags / RemoveGPFlags Écrase / efface tous les flags d'un path. Path, (GPFlags) —
GetGPFlags / GetFilteredGPFlags Lit les flags d'un path. Path, (Filters, bExact, bInvert) FGameplayTagContainer
CheckAllGPFlags / CheckAnyGPFlag Tous / au moins un flag levé ? Path, GPFlags, bExact bool
CheckGPFlagQuery Une FGameplayTagQuery correspond-elle ? Path, Query bool
RaiseExclusiveGPFlag / GetExclusiveGPFlag Lève un unique flag exclusif / le lit. Path, (GPFlag) FGameplayTagContainer / FGameplayTag
RaiseCountedGPFlag / LowerCountedGPFlag / ClearCountedGPFlag Flag à comptage de références (ne s'efface que lorsque les levées/abaissements s'équilibrent). Path int

Compteurs

Node Objet Paramètres Renvoie
SetGPCounter Fixe la valeur d'un compteur. Path, Value int
AddToGPCounter Incrémente/décrémente un compteur. Path, Diff int (nouvelle valeur)
GetGPCounter Lit un compteur (0 si non défini). Path int
IsGPCounterDefined A-t-il déjà été défini (même à 0) ? Path bool
RemoveGPCounter Efface et supprime un compteur. Path —

Écouteurs & durée de vie

Node Objet
BindEventToOnGPFlagChangedPerPaths / ...GPCounter... S'abonne aux changements sur des paths spécifiques (et leurs enfants).
UnbindEventFrom... / UnbindAllEventsFrom... / ...ForObject Se désabonne d'un événement spécifique, de tous les événements d'un path, ou de tous les événements d'un objet.
OnGPFlagChanged / OnGPCounterChanged Délégués multicast assignables levés à tout changement.
ResetGPVars Efface tous les GPVars (recharge éventuellement les valeurs par défaut).

Lecture des dialogues — ULBRDialogueReadingLibrary

Des helpers statiques et sans état (module LBRCore, catégorie Libretto ▸ Reading) qui parcourent un Dialogue sans le jouer, pour des documents, des fils de messagerie, des popups et d'autres interfaces 2D. Les lignes sont désignées par leur index ; FlagFilter ne garde que les sous-dialogues qui portent un flag (vide = aucun filtre). Voir Lire des dialogues dans des interfaces 2D.

Fonction Rôle
FindFirstPlayableSubdialogue / GetPlayableSubdialogues Le premier / chaque sous-dialogue qui passe le filtre et sa condition, dans l'ordre de l'asset.
GetSubdialogueEntry Première étape (FLBRReadStep) d'un sous-dialogue.
GetNextStep Étape suivant une ligne affichée ou un reply choisi : If/Else, fin d'un reply, Goto.
GetValidReplies Replies à proposer (FLBRReplyOption : bAvailable, bIsDefault).
GetDefaultReply Le reply par défaut, s'il est encore valide.
FindReplyMatchingInput Le reply qui correspond au texte saisi, ou le reply par défaut.
RecordReplyChosen Enregistre le reply dans les GPVars.
GetRetainedReply None / Single / Ambiguous : quel reply d'un choice a été choisi auparavant.
ApplyLineEffects SetTags, RemoveTags, puis actions d'une ligne.
MarkSubdialogueDone / MarkDialogueDone Lèvent les flags « done », comme un dialogue joué.

Conditions — ULBRCondition (module LBRConditions)

Créez une condition dynamique (pour un sous-dialogue, une Reply ou une branche If) en sous-classant ULBRCondition et en surchargeant Evaluate.

Membre Type Objet
Evaluate BlueprintNativeEvent, protected À surcharger. Renvoie le résultat de la condition. PURE_VIRTUAL sur la base.
EvaluateWithCache BlueprintCallable Renvoie le résultat en cache s'il est valide, sinon Evaluate() puis met en cache.
GetStoredResult / IsStoredResultValid BlueprintCallable Lit le résultat en cache / indique s'il est valide.
InvalidateLastResult BlueprintCallable Force une réévaluation la prochaine fois.
GetLabel / GetLabelSuccess / GetLabelFail BlueprintNativeEvent, pure Labels affichés dans l'éditeur sur la ligne Reply / If / Else.
Propriété Objet
bCacheSuccess / bCacheFailure Met en cache les résultats positifs / négatifs pour éviter de revérifier.
Comment Note libre de l'auteur.

Conditions intégrées

Les opérateurs AND / OR / XOR / NOT / FALSE sont livrés en tant que sous-classes de ULBRCondition, avec des conditions GPVar et une condition dédiée ULBRDialogueDoneCondition (préférez-la aux vérifications de path GPVar « ce dialogue a-t-il été joué » écrites à la main). Voir Conditions.

Voir aussi