Skip to content

Blueprint API Reference

A compact index of the main Blueprint-callable entry points a game programmer needs to drive Libretto at runtime. This is a reference, not a tutorial — for the narrative version (staging modes, how to wire a trigger, end-of-dialogue patterns) read Playing Dialogues at Runtime. For GPVars and conditions, see GPVars and Conditions.

The palette is the source of truth

This page lists the key functions only. Every function below is a real UFUNCTION; the exact node names, tooltips, and the many secondary helpers are best browsed from the in-editor Blueprint palette (search Libretto, Dialogue, or GPVar) or the details panel of a Dialogue Instance / the Dialogue Manager.

The entry points live on three classes across three modules:

Class Module Kind Role
ALBRDialogueInstance LBRCore Actor The placed (or spawned) instance you start a dialogue on.
ULBRDialogueManager LBRCore World subsystem Registers, stops, and lists running dialogues; broadcasts global events.
ULBRGPVarSubsystem LBRTags Engine subsystem Reads/writes GPFlags and GPCounters.
ILBRDialogueCharacter LBRCore Interface Implemented by any character that takes part in a dialogue.
ULBRCondition LBRConditions Object Base class for dynamic conditions.
ULBRDialogueReadingLibrary LBRCore Function library Reads a Dialogue outside of the Sequencer (2D interfaces).

Starting dialogues

You start a dialogue by calling a StartDialogue* function on the ALBRDialogueInstance. They differ only in how the target subdialogue is chosen (see Subdialogue selectors). Every one takes an EndEvent (FDialogueEndEventDelegate) that fires when that playthrough ends — see End events.

On a placed Dialogue Instance — ALBRDialogueInstance

Function Purpose Key params Returns
StartDialogueInstance Start without specifying a subdialogue (first playable one). EndEvent bool (started)
StartDialogueWithSelector Pick the subdialogue by a single selector tag. Selector : FGameplayTag, EndEvent bool
StartDialogueWithSelectors Match a set of selectors the subdialogue must carry. Selectors : FLBRGameplayTagFlags, EndEvent bool
StartDialogueWithSelectorQuery Match an exact selector query (e.g. A and B but not C). SelectorQuery : FGameplayTagQuery, EndEvent bool
StartDialogueWithAnySelector Combine tag + selectors + query at once. Selector, Selectors, SelectorQuery, EndEvent bool

StartDialogue(SubdialogueName) is deprecated

The old StartDialogue(FName SubdialogueName, EndEvent) on the instance (and the manager) is marked DeprecatedFunction. Prefer the selector-based functions above.

Recompile if selector tags look stale

The selector pins are populated from the dialogue's tags. If they are out of date on a node, recompile the Blueprint.

Generic dialogues — static on ALBRDialogueInstance

A generic dialogue plays without a placed instance (voice-mail, phone voice, unbound audio). The same selection variants exist as static functions; you pass a spawn transform and get back the spawned ALBRDialogueInstance.

Function Purpose Key params Returns
StartGenericDialogue Start from a generic entry-point struct. WorldContextObject, EntryPoint : FLBRGenericDialogueEntryPoint, EndEvent ALBRDialogueInstance*
StartGenericDialogueWithSelector Generic start, single selector tag. WorldContextObject, Dialogue, Selector : FGameplayTag, Transform, EndEvent ALBRDialogueInstance*
StartGenericDialogueWithSelectors Generic start, selector set. WorldContextObject, Dialogue, Selectors : FLBRGameplayTagFlags, Transform, EndEvent ALBRDialogueInstance*
StartGenericDialogueWithSelectorQuery Generic start, selector query. WorldContextObject, Dialogue, SelectorQuery : FGameplayTagQuery, Transform, EndEvent ALBRDialogueInstance*

Warning

The dialogue must have been generated as a generic dialogue first (right-click the asset ▸ generate as generic).

Don't know which you hold? — static on ALBRDialogueInstance

Function Purpose Key params Returns
StartDialogueWithAnyEntryPoint Start a placed instance or a generic dialogue from a single entry-point value. WorldContextObject, EntryPoint : FLBRAnyDialogueEntryPoint, EndEvent ALBRDialogueInstance*

FLBRAnyDialogueEntryPoint carries a Dialogue or a DialogueInstance, plus a spawn transform and selectors — the recommended entry point for designer-placed triggers. See Triggering a dialogue from your own objects.

Entry-point dropdown helper

To populate the selector dropdown on your own FLBRAnyDialogueEntryPoint property, call the static helper ALBRDialogueInstance::GetSubdialogueSelectorsCategoriesFromAnyEntryPoint(EntryPoint) from your GetGPTagRootFilter / GetSubdialogueSelectorsCategories override.

On the Dialogue Manager — ULBRDialogueManager

The manager also exposes a couple of start functions (handy when you already hold the subsystem):

Function Purpose Key params Returns
StartDialogueInstance Start a placed instance (no subdialogue selection). DialogueInstance : ALBRDialogueInstance* bool
StartDialogueWithEntryPoint Start from an FLBRDialogueEntryPoint. EntryPoint : FLBRDialogueEntryPoint bool
StartDialogueAtTime Start the instance's sequence player at a given time (seconds). DialogueStartTime : float, DialogueInstance —

Manager access

ULBRDialogueManager is a World subsystem — get it via Get Subsystem (World Subsystem) on a world-context object.

Stopping & querying — ULBRDialogueManager

To stop a running dialogue you pass the instance and an end reason (FLBRGameplayTagFlags).

Function Purpose Key params
StopDialogue Stop one running instance. DialogueInstance, EndReason : FLBRGameplayTagFlags
StopDialogueInstancesForDialogue Stop every running instance of a given Dialogue asset. Dialogue : ULBRDialogue*, EndReason
StopDialogueInstancesInvolving Stop every running instance involving a given character. DialogueCharacter : TScriptInterface<ILBRDialogueCharacter>, EndReason
StopAll Stop every running dialogue. EndReason
PauseDialogue Pause a running dialogue (⚠️ not all dialogues support pausing). DialogueInstance, PauseReason : FLBRGameplayTagFlags
Read-only property Type Purpose
RunningDialogues TArray<ALBRDialogueInstance*> Every currently running dialogue.
FocusedDialogue ALBRDialogueInstance* The dialogue currently holding focus.

End events & delegates

There are three ways to react to a dialogue ending — pick by scope.

Mechanism Where Type Fires…
End Event pin (EndEvent) Argument of every StartDialogue* FDialogueEndEventDelegate (ULBRSubdialogue*, EndReason) Only for this StartDialogue* call.
DialogueEndEvent Property on ALBRDialogueInstance FDialogueEndEventMulticastDelegate (multicast) On every exit of that instance.
OnDialogueEnd Property on ULBRDialogueManager FOnDialogueEnd (ALBRDialogueInstance*, EndReason) On every dialogue end, globally.

Warning

The End Event pin only fires for the playthrough you started. If the same dialogue is later launched another way (a trigger, say), that pin is not called — use DialogueEndEvent or OnDialogueEnd for a persistent hook.

In Blueprint, add the instance event via Actor menu ▸ Add Event ▸ DialogueEndEvent. Internally the per-start pin is the instance's one-shot DialogueEndOnce delegate.

Other manager delegates (BlueprintAssignable)

ULBRDialogueManager also broadcasts OnDialogueStarted, OnSubdialogueStarted, OnSubdialogueEnd, OnSubtitleDisplayed, OnSubtitleHidden, OnDialogueSetTags, and OnDialogueRemoveTags. See the manager in the palette for their signatures.

Characters — ILBRDialogueCharacter (interface)

Any actor/object that takes part in a dialogue implements ILBRDialogueCharacter (module LBRCore). All members are BlueprintNativeEvent (override in C++ or Blueprint). The two most commonly overridden:

Function Purpose Signature
LBRGetCharacterName Localized display name (subtitles, UI). Defaults to the class name. FText LBRGetCharacterName() const
LBRGetCharacterGender Drives TTS voice selection. ELBRCharacterGender LBRGetCharacterGender() const
Full interface (all BlueprintNativeEvent)
Function Returns Purpose
LBRGetBodyComponent USkeletalMeshComponent* Body mesh to bind in generated sequences.
LBRGetHeadComponent USkeletalMeshComponent* Head (face) mesh for facial generation.
SetLookAtTarget — Point the character at a target actor.
RequestStartDialogue — The instance needs this character ready; call ULBRDialogueManager::OnDialogueCharacterReadyForDialogue when done (supports walk-to before ready).
RequestEndDialogue bool The instance asks the character to finish.
DialogueSwitch — Called when switching from one dialogue to another.
FindWorldInstance UObject* Resolves the instance to use to play a dialogue in a world (called on the CDO).
SetupEditorPreview — Set up the character for animation preview in editor/Sequencer.
GetIgnoredTracks / GetGenerationFlags FLBRGameplayTagFlags Skip certain tracks at generation (e.g. lipsync in FPS).
GetLipsyncModel FString Model identifier for lipsync generation.
GetStageRoles FGameplayTagContainer Staging roles used to match this character to a stage slot.

Ready-made bases

ALBRSimpleDialogueCharacter (mesh) and ULBRIntangibleCharacter (voice-only: narrator, phone) already implement the interface — implement LBRGetCharacterName once in your base class from a Name/CharacterName property.

GPVars — ULBRGPVarSubsystem (module LBRTags)

Flags and counters keyed by an FGPTagPath. Get the subsystem with the static GetGPVarSubsystem (BlueprintPure); every operation below also has a static variant (Static_*, exposed under its plain display name, e.g. RaiseGPFlag) so you can call it without first holding the subsystem. See GPVars for the model.

Flags

Node Purpose Params Returns
RaiseGPFlag Raise one flag. Path bool (false if already raised)
LowerGPFlag Lower one flag. Path bool (false if not raised)
CheckGPFlag Is the flag raised? Path, bExact bool
CheckNotGPFlag Is the flag not raised? Path, bExact bool
RaiseGPFlags / LowerGPFlags Raise / lower several flags in a path. Path, GPFlags, (bExact) FGameplayTagContainer (actually changed)
SetGPFlags / RemoveGPFlags Overwrite / clear all flags in a path. Path, (GPFlags) —
GetGPFlags / GetFilteredGPFlags Read the flags in a path. Path, (Filters, bExact, bInvert) FGameplayTagContainer
CheckAllGPFlags / CheckAnyGPFlag All / at least one flag raised? Path, GPFlags, bExact bool
CheckGPFlagQuery Does a FGameplayTagQuery match? Path, Query bool
RaiseExclusiveGPFlag / GetExclusiveGPFlag Raise a single exclusive flag / read it. Path, (GPFlag) FGameplayTagContainer / FGameplayTag
RaiseCountedGPFlag / LowerCountedGPFlag / ClearCountedGPFlag Reference-counted flag (clears only when raises/lowers balance). Path int

Counters

Node Purpose Params Returns
SetGPCounter Set a counter's value. Path, Value int
AddToGPCounter Increment/decrement a counter. Path, Diff int (new value)
GetGPCounter Read a counter (0 if unset). Path int
IsGPCounterDefined Was it ever set (even to 0)? Path bool
RemoveGPCounter Clear and remove a counter. Path —

Listeners & lifetime

Node Purpose
BindEventToOnGPFlagChangedPerPaths / ...GPCounter... Subscribe to changes on specific paths (and children).
UnbindEventFrom... / UnbindAllEventsFrom... / ...ForObject Unsubscribe a specific event, all events for a path, or all events for an object.
OnGPFlagChanged / OnGPCounterChanged Assignable multicast delegates raised on any change.
ResetGPVars Clear all GPVars (optionally reload defaults).

Reading dialogues — ULBRDialogueReadingLibrary

Static, stateless helpers (module LBRCore, category Libretto ▸ Reading) that walk a Dialogue without playing it, for documents, messaging threads, popups and other 2D interfaces. Lines are designated by their index; FlagFilter keeps only the subdialogues that have a flag (empty = no filter). See Reading dialogues in 2D interfaces.

Function Purpose
FindFirstPlayableSubdialogue / GetPlayableSubdialogues The first / every subdialogue that passes the filter and its condition, in asset order.
GetSubdialogueEntry First step (FLBRReadStep) of a subdialogue.
GetNextStep Step after a displayed line or a chosen reply: If/Else, end of a reply, Goto.
GetValidReplies Replies to offer (FLBRReplyOption: bAvailable, bIsDefault).
GetDefaultReply The default reply, if still valid.
FindReplyMatchingInput The reply matching typed text, or the default reply.
RecordReplyChosen Records the reply in the GPVars.
GetRetainedReply None / Single / Ambiguous: which reply of a choice was taken before.
ApplyLineEffects SetTags, RemoveTags, then actions of a line.
MarkSubdialogueDone / MarkDialogueDone Raise the "done" flags, as a played dialogue does.

Conditions — ULBRCondition (module LBRConditions)

Author a dynamic condition (for a subdialogue, a Reply, or an If-branch) by subclassing ULBRCondition and overriding Evaluate.

Member Kind Purpose
Evaluate BlueprintNativeEvent, protected Override this. Return the condition result. PURE_VIRTUAL on the base.
EvaluateWithCache BlueprintCallable Return the cached result if valid, else Evaluate() and cache.
GetStoredResult / IsStoredResultValid BlueprintCallable Read the cached result / whether it's valid.
InvalidateLastResult BlueprintCallable Force re-evaluation next time.
GetLabel / GetLabelSuccess / GetLabelFail BlueprintNativeEvent, pure Editor labels shown on the Reply / If / Else line.
Property Purpose
bCacheSuccess / bCacheFailure Cache positive / negative results to skip re-checks.
Comment Free author note.

Built-in conditions

Operators AND / OR / XOR / NOT / FALSE ship as ULBRCondition subclasses, along with GPVar conditions and a dedicated ULBRDialogueDoneCondition (prefer it over hand-written "has this dialogue played" GPVar-path checks). See Conditions.

See also