Priorités de dialogue

Lorsqu'un dialogue tente de démarrer alors qu'un autre dialogue est déjà en cours, Libretto doit décider ce qui se passe : le nouveau se joue-t-il, attend-il, met-il l'ancien en sourdine, est-il ignoré ? C'est le rôle du système de priorités.

Chaque dialogue porte un niveau de priorité (une classe Blueprint). Lorsqu'un nouveau dialogue est demandé, Libretto recherche la nouvelle priorité, la compare à celle de chaque dialogue en cours, et résout la paire en un résultat (outcome). Les résultats peuvent être affinés par paire de priorités et par contexte (qui parle à qui), avec une valeur par défaut sensée lorsque rien de spécifique n'est configuré.

Résultats

L'enum d'exécution est ELBRDialoguePriorityOutcome. Tout au long de cette page :

• New — le dialogue qui tente de démarrer.
• Running — le dialogue déjà en cours de lecture.

Résultat	Effet
Play	Joue le dialogue New normalement ; laisse le dialogue Running intact.
PlayMuffled	Joue le dialogue New avec un son atténué (muffled) ; laisse le dialogue Running intact.
PlayMuted	Joue le dialogue New sans son ; laisse le dialogue Running intact.
Interrupt	Interrompt (termine) le dialogue Running, puis joue le New.
Muffle	Atténue le son du dialogue Running pendant que le New se joue.
Mute	Coupe le son du dialogue Running pendant que le New se joue.
Pause	Met en pause le dialogue Running, puis joue le New.
Ignore	Abandonne la demande de lecture — le dialogue New ne démarre jamais.
Default	Aucun résultat explicite — revient au comportement par défaut basé sur l'ordre des index (voir ci-dessous).

Les dialogues ignorés n'exécutent aucun effet de bord

Lorsque le résultat est Ignore, le dialogue New est entièrement abandonné, de sorte que tous les effets de bord qu'il aurait produits (lever des GPFlags, exécuter des actions de ligne…) ne sont pas appliqués. De même, Interrupt coupe court au dialogue Running : les effets de bord qui n'avaient pas encore été déclenchés ne le seront pas.

Info

PlayMuffled/PlayMuted agissent sur le dialogue New ; Muffle/Mute agissent sur le dialogue Running. Ce sont les images en miroir l'un de l'autre — voir Directionnalité.

Comment muffle/mute affectent le son

Muffle et mute s'expriment à l'exécution sous forme de flags d'instance sur le dialogue affecté : Libretto.RuntimeFlags.Muffled et Libretto.RuntimeFlags.Muted. Le volume réellement appliqué pour chaque flag se configure dans Project Settings ▸ Libretto sous RuntimeFlagsToVolumeModifier — une liste associant une requête de GameplayTag à des multiplicateurs de volume (global / animation / voix). Les valeurs par défaut livrées sont :

Flag	Multiplicateurs de volume (défaut / animation / voix)
Libretto.RuntimeFlags.Muffled	0.1 / 0.1 / 0.1
Libretto.RuntimeFlags.Muted	0.0 / 0.0 / 0.0

Note

Le volume est rafraîchi manuellement — actuellement lorsqu'un dialogue démarre, et lorsqu'il est atténué ou coupé par un résultat de priorité.

Contextes

Un résultat peut dépendre de qui est présent dans chacun des deux dialogues. Libretto rassemble un contexte pour la paire et choisit le premier résultat configuré dont le contexte correspond. Les contextes sont des GameplayTags sous Libretto.Priority :

Tag de contexte	Signification
Libretto.Priority.NPC.Both	Un PNJ (un personnage partagé) est présent dans les deux dialogues.
Libretto.Priority.Player.Both	Le joueur est présent dans les deux dialogues.
Libretto.Priority.Player.New	Le joueur est présent uniquement dans le dialogue New.
Libretto.Priority.Player.Running	Le joueur est présent uniquement dans le dialogue Running.

Un contexte rassemblé peut combiner le tag NPC avec l'un des tags player — par exemple « un PNJ partagé et le joueur uniquement dans le dialogue New » correspond à NPC.Both + Player.New. Un résultat de relation avec un contexte vide correspond à tout, il agit donc comme la valeur par défaut fourre-tout pour cette paire de priorités.

La matrice résultats × contextes qu'un projet peut configurer ressemble donc à ceci (un résultat est choisi par cellule ; les cellules laissées vides retombent sur All contexts, puis sur le comportement par défaut) :

Contexte	Résultat (exemple)
All contexts (contexte vide)	valeur par défaut fourre-tout pour cette paire de priorités
NPC.Both + Player.Both	PNJ partagé, joueur dans les deux
NPC.Both + Player.New	PNJ partagé, joueur uniquement dans New
NPC.Both + Player.Running	PNJ partagé, joueur uniquement dans Running
Player.Both	pas de PNJ partagé, joueur dans les deux
Player.New	pas de PNJ partagé, joueur uniquement dans New
Player.Running	pas de PNJ partagé, joueur uniquement dans Running

Comment le contexte est construit

L'implémentation de base (ULBRDialoguePriority::GatherContext) ajoute un unique tag Player.* (Both/New/Running) selon l'endroit où se trouve le joueur, et ajoute NPC.Both lorsque les deux dialogues partagent au moins un personnage. Vous pouvez surcharger GatherContext dans une priorité Blueprint pour calculer un contexte personnalisé.

Directionnalité (recherche inverse)

Les relations sont recherchées d'abord du côté de la priorité New. Si la priorité New ne définit aucune relation vers la priorité Running, Libretto la recherche du côté Running et inverse le résultat, de sorte que vous n'avez à définir chaque paire qu'une seule fois. Les inversions sont :

Résultat trouvé de l'autre côté	Résultat inversé utilisé
Play	Play
PlayMuffled	Muffle
PlayMuted	Mute
Interrupt	Ignore
Muffle	PlayMuffled
Mute	PlayMuted
Ignore	Interrupt
Pause	Ignore

Comportement par défaut

Lorsqu'aucun résultat de relation ne correspond (le résultat se résout en Default), Libretto revient à l'ordre de la liste de priorités dans Project Settings (voir Niveaux de priorité) :

• Si la priorité New a un index inférieur à celui de la Running (c.-à-d. qu'elle est plus importante), le résultat est Interrupt — le dialogue New interrompt le Running.
• Sinon (index égal ou supérieur), le résultat est Ignore — le dialogue New est abandonné.

En bref : l'index 0 est le plus important, et un dialogue plus important interrompt un dialogue moins important par défaut.

Niveaux de priorité

Un niveau de priorité est une classe Blueprint qui dérive de ULBRDialoguePriority (un UObject abstrait, Blueprintable). Chaque projet peut en définir autant qu'il en a besoin.

Libretto livre trois niveaux d'exemple, ordonnés du plus au moins important :

1. BP_DialoguePriority_Cinematic
2. BP_DialoguePriority_Stage
3. BP_DialoguePriority_3C

Avec cet ordre, un dialogue Cinematic interrompt par défaut un dialogue Stage ou 3C, et ainsi de suite.

Tip

Les noms Cinematic, Stage et 3C sont des étiquettes arbitraires. Ils n'ont aucun lien technique avec les types de dialogue du même nom.

Enregistrer les niveaux

Les niveaux de priorité du projet — et leur ordre — vivent dans Project Settings ▸ Libretto sous le tableau DialoguePriorities (ULBRDialogueCoreSettings). L'ordre a de l'importance : plus l'index est bas, plus la priorité est importante. Cet ordre définit le comportement par défaut.

Les valeurs par défaut livrées sont déclarées dans le DefaultLibretto.ini du plugin :

[/Script/LBRCore.LBRDialogueCoreSettings]
+DialoguePriorities=/Libretto/Blueprints/BP_DialoguePriority_Cinematic.BP_DialoguePriority_Cinematic_C
+DialoguePriorities=/Libretto/Blueprints/BP_DialoguePriority_Stage.BP_DialoguePriority_Stage_C
+DialoguePriorities=/Libretto/Blueprints/BP_DialoguePriority_3C.BP_DialoguePriority_3C_C

Décider du niveau attribué à un sous-dialogue

Surchargez AppliesToSubdialogue dans chaque priorité Blueprint. Elle reçoit le sous-dialogue dont la priorité est en cours de résolution, vous laisse exécuter le test de votre choix, et renvoie un booléen — true si ce sous-dialogue appartient à ce niveau de priorité. Par exemple, le niveau Cinematic renvoie true lorsque le sous-dialogue porte le flag cinématique.

La priorité d'un sous-dialogue

La priorité est résolue par sous-dialogue. Lorsqu'un sous-dialogue est ouvert, sa priorité par défaut est calculée automatiquement en exécutant l'AppliesToSubdialogue de chaque niveau enregistré dans l'ordre de la liste et en prenant la première correspondance. Dans le details panel de l'Éditeur de dialogue, cela apparaît (en aperçu uniquement) sous Default Priority.

Pour forcer un niveau spécifique, renseignez la propriété DialoguePriority du sous-dialogue. Lorsqu'elle est remplie, elle surcharge celle détectée automatiquement. Ainsi un sous-dialogue marqué Cinematic peut tout de même être traité comme Stage si vous réglez son DialoguePriority sur le niveau Stage.

Info

Des fonctions utilitaires de résolution vivent sur le sous-dialogue : GetDefaultPriority() la calcule à partir des settings, et GetPriority() renvoie le DialoguePriority personnalisé s'il est renseigné, sinon la valeur par défaut.

Configurer les relations — l'éditeur de priorités

Les relations entre niveaux de priorité sont stockées dans Project Settings ▸ Libretto sous DialoguePrioritiesRelations — une map indexée par classe de priorité, chaque entrée contenant une liste de relations vers d'autres classes de priorité, et chaque relation contenant une liste ordonnée de résultats (contexte → résultat).

Éditer cette map brute à la main est fastidieux, aussi Libretto fournit un widget d'éditeur dédié : EWBP_LBRDialoguePriorities. C'est un Editor Utility Widget situé dans le dossier toolbar-widgets du plugin, il apparaît donc dans le menu déroulant de la toolbar Libretto de la fenêtre principale.

L'éditeur présente les priorités sous forme de grille. Pour chaque paire de priorités, vous choisissez un résultat par contexte ; chaque résultat a sa propre couleur et son icône (Play, PlayMuffled, PlayMuted, Interrupt, Muffle, Mute, Pause, Ignore). Au sein d'une cellule, les résultats sont évalués de haut en bas, et le premier contexte correspondant l'emporte — placez donc les contextes plus spécifiques au-dessus de l'entrée fourre-tout All contexts.

Info

Les contextes proposés par l'éditeur, ainsi que leurs couleurs/icônes, proviennent de Editor Preferences ▸ Libretto – Dialogue Editor (ULBRDialogueEditorLocalSettings, DialoguePriorityContextTagGroups sous Priority Editor ▸ Context) et des réglages Priority Editor ▸ Theme correspondants (voir la référence des réglages). Les groupes par défaut sont exactement les quatre tags de contexte listés ci-dessus.

Récapitulatif du modèle de données

Symbole	Rôle
ULBRDialoguePriority	Classe de base abstraite pour un niveau de priorité. Surchargez AppliesToSubdialogue, éventuellement GatherContext / FindOutcome / InverseOutcome.
ELBRDialoguePriorityOutcome	L'enum de résultat (Default, Play, PlayMuffled, PlayMuted, Interrupt, Muffle, Mute, Ignore, Pause).
FLBRDialoguePriorityResult	Une paire (Contexte → Résultat).
FLBRDialoguePriorityRelation	La liste ordonnée de résultats pour une paire de priorités.
FLBRDialoguePriorityRelationList	Toutes les relations qu'une priorité définit vers les autres priorités.
ULBRDialogueCoreSettings.DialoguePriorities	La liste ordonnée des niveaux de priorité du projet.
ULBRDialogueCoreSettings.DialoguePrioritiesRelations	Les relations configurées entre niveaux.
ULBRDialogueCoreSettings.RuntimeFlagsToVolumeModifier	Le volume appliqué pour les runtime flags muffle/mute.