The dialogue subsystem stores authored conversations as DialogueTree objects.
Each tree has a startNodeId, an NPC owner, a priority, optional start
conditions, and a Map<number, DialogueNode> keyed by node ID.
Node Types#
TEXT: spoken line. UsenextNodeIdto continue, or omit it for a terminal line.CHOICE: player-facing choices. EachDialogueChoicetargets another node and can carry conditions, actions, relationship deltas, and consequence tags.CONDITION: routing node withcondition,trueBranchId, andfalseBranchId.ACTION: executes actions and can route withnextNodeId.BRANCH: generic routing node. It can use a condition, or fall through tonextNodeId.RANDOM: weighted routing throughrandomBranches.
Run validateDialogueTree on authored trees. Errors catch missing start nodes,
missing targets, empty choice nodes, invalid random weights, and incomplete
condition branches. Warnings identify unreachable nodes.
Conditions#
Conditions use a ConditionOperator, key, value, and optional scope.
- Session variables: default
variablesmap. - Local variables:
DialogueVariableScope.LOCAL, resettable per conversation. - NPC variables:
DialogueVariableScope.NPCplusnpcIdfor persistent per-character state. - Global story variables:
DialogueVariableScope.GLOBAL.
The runtime supports comparisons, inventory flags, quest state, relationship
thresholds, player stats, time-of-day windows such as 21-5, and prior choice
checks with CHOICE_MADE.
Actions#
Actions are deterministic state updates. Existing actions handle items, quests, gold, experience, flags, relationships, combat, teleport, and sound. The extended runtime also supports scoped variables, animation commands, and spawn commands:
SET_LOCAL_VARIABLE,SET_NPC_VARIABLE,SET_GLOBAL_VARIABLEPLAY_ANIMATION: writeslastAnimationandanimation_<key>SPAWN_ENTITY: writeslastSpawnedEntityandspawn_<key>
Downstream presentation/gameplay systems can consume these command variables and flags after dialogue traversal.
Localization and Voice#
Use stable textId values on nodes and choices. Add tree-level stringTable
entries with default text, per-locale translations, and per-locale voice-over
asset paths. Use localizeDialogueNode and localizeDialogueChoices at
presentation boundaries.
Tags and Typewriter#
Inline tags use square brackets, for example:
Hold[pause=500][happy] the line.
parseDialogueTags strips tags from visible text and returns structured tag
metadata. createTypewriterState, advanceTypewriter, and skipTypewriter
provide deterministic typewriter behavior over the stripped text.
Save/Load and Runtime Flow#
Use serializeDialogueState for save data and restoreDialogueState with the
available tree registry to resume mid-conversation. Snapshots persist current
tree ID, current node ID, history, quest state, flags, variables, scoped
variables, choice consequences, queue state, bark cooldowns, and elapsed turns.
Dialogue requests can be queued with enqueueDialogueRequest, started with
dequeueNextDialogueRequest, or routed through interruptOrQueueDialogue.
Higher-priority requests interrupt lower-priority active conversations.
Barks and Imports#
Barks are context-triggered one-liners with contexts, weights, conditions, and
cooldowns. Select with selectDialogueBark and apply cooldowns with
applyDialogueBarkCooldown.
Simple Ink and Yarn Spinner text can be imported with importInkDialogue and
importYarnDialogue. Imported trees should still pass validateDialogueTree
before shipping.