Eve library

Dialogue Authoring Guide

Guide

Revision 1

On this page

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. Use nextNodeId to continue, or omit it for a terminal line.
  • CHOICE: player-facing choices. Each DialogueChoice targets another node and can carry conditions, actions, relationship deltas, and consequence tags.
  • CONDITION: routing node with condition, trueBranchId, and falseBranchId.
  • ACTION: executes actions and can route with nextNodeId.
  • BRANCH: generic routing node. It can use a condition, or fall through to nextNodeId.
  • RANDOM: weighted routing through randomBranches.

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 variables map.
  • Local variables: DialogueVariableScope.LOCAL, resettable per conversation.
  • NPC variables: DialogueVariableScope.NPC plus npcId for 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_VARIABLE
  • PLAY_ANIMATION: writes lastAnimation and animation_<key>
  • SPAWN_ENTITY: writes lastSpawnedEntity and spawn_<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:

text
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.