dialogue
stableBranching dialogue tree engine for games and interactive applications, supporting node-based conversations, player choices, variable substitution, and runtime state management.
use plugin dialogue::{DialogueTree.new, add_node, add_choice, …} Functions (19)
- DialogueTree.new Creates a new empty dialogue tree
- add_node Appends a new dialogue node with the given text and returns its integer node ID.
- add_choice Adds a player choice to an existing node.
- current_text Returns the text of the current node.
- current_choices Returns a table of available choices at the current node.
- advance Advances the dialogue by selecting a choice at the current node.
- is_finished Returns true if the dialogue has reached a terminal state (no more choices and no further nodes).
- set_variable Stores a named string variable in the dialogue tree's context.
- get_variable Returns the value of a stored variable, or nil if it has not been set.
- substitute_variables Replaces {variable_name} placeholders in a string with their stored values.
- reset Resets the dialogue tree to node 0 and clears the finished flag, allowing the conversation to be replayed.
- node_count Returns the total number of nodes in the tree (including tombstoned nodes).
- get_node_text Returns the text of the node at the given ID.
- set_node_text Updates the text of an existing node.
- set_current Jumps the dialogue to a specific node ID without resetting the finished flag check logic.
- current_node_id Returns the ID of the currently active node, or nil if the dialogue is finished.
- remove_node Tombstones a node (clears its text and choices) while preserving index stability for other nodes.
- remove_choice Removes a choice from a node by its 0-based index.
- clear_variables Removes all stored variables from the dialogue context.
Classes
DialogueTree
A stateful dialogue tree built from nodes and choices. Created with DialogueTree.new().
Creates a new empty dialogue tree
Creates a new empty DialogueTree handle. Add nodes and choices, then use current_text and advance to drive the conversation.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
let n0 = tree.add_node("Hello! Who are you?")
let n1 = tree.add_node("Nice to meet you, traveller.")
let n2 = tree.add_node("Farewell, stranger.")
tree.add_choice(n0, "I am a traveller.", n1)
tree.add_choice(n0, "None of your business.", n2)
print(tree.current_text())
Appends a new dialogue node with the given text and returns its integer node ID.
Appends a new dialogue node with the given text and returns its integer node ID. Node IDs are sequential starting from 0.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
let id = tree.add_node("What do you seek?")
print(id) // 0
Adds a player choice to an existing node.
Adds a player choice to an existing node. When the player selects this choice, the tree advances to target_node_id.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
let n0 = tree.add_node("Go left or right?")
let n1 = tree.add_node("You went left.")
let n2 = tree.add_node("You went right.")
tree.add_choice(n0, "Go left", n1)
tree.add_choice(n0, "Go right", n2)
Returns the text of the current node.
Returns the text of the current node. Returns nil if the dialogue has finished or the tree is empty.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
tree.add_node("Welcome, adventurer!")
print(tree.current_text()) // "Welcome, adventurer!"
Returns a table of available choices at the current node.
Returns a table of available choices at the current node. Each entry has text and target (the target node ID). Returns an empty table if there are no choices (end of branch) or the tree is finished.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
let n0 = tree.add_node("Choose your path.")
tree.add_choice(n0, "North", 1)
tree.add_choice(n0, "South", 2)
let choices = tree.current_choices()
print(choices[1]["text"]) // "North"
Advances the dialogue by selecting a choice at the current node.
Advances the dialogue by selecting a choice at the current node. choice_index is 0-based. If the current node has no choices, the dialogue ends.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
let n0 = tree.add_node("Continue?")
let n1 = tree.add_node("Good. Moving on.")
tree.add_choice(n0, "Yes", n1)
tree.advance(0)
print(tree.current_text()) // "Good. Moving on."
Returns true if the dialogue has reached a terminal state (no more choices and no further nodes).
Returns true if the dialogue has reached a terminal state (no more choices and no further nodes).
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
tree.add_node("The end.")
tree.advance(0)
print(tree.is_finished()) // true
Stores a named string variable in the dialogue tree's context.
Stores a named string variable in the dialogue tree's context. Variables can be substituted into text using substitute_variables.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
tree.set_variable("player_name", "Aria")
Returns the value of a stored variable, or nil if it has not been set.
Returns the value of a stored variable, or nil if it has not been set.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
tree.set_variable("quest", "dragon")
print(tree.get_variable("quest")) // "dragon"
Replaces {variable_name} placeholders in a string with their stored values.
Replaces {variable_name} placeholders in a string with their stored values. Useful for personalizing dialogue text at runtime.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
tree.set_variable("player_name", "Aria")
tree.set_variable("item", "sword")
let line = "Welcome, {player_name}. You found a {item}!"
print(tree.substitute_variables(line))
// "Welcome, Aria. You found a sword!"
Resets the dialogue tree to node 0 and clears the finished flag, allowing the conversation to be replayed.
Resets the dialogue tree to node 0 and clears the finished flag, allowing the conversation to be replayed.
use plugin dialogue::{DialogueTree}
let tree = DialogueTree.new()
tree.add_node("Hello again!")
tree.reset()
print(tree.current_text()) // "Hello again!"
Returns the total number of nodes in the tree (including tombstoned nodes).
Returns the total number of nodes in the tree (including tombstoned nodes).
Returns the text of the node at the given ID.
Returns the text of the node at the given ID.
Updates the text of an existing node.
Updates the text of an existing node.
Jumps the dialogue to a specific node ID without resetting the finished flag check logic.
Jumps the dialogue to a specific node ID without resetting the finished flag check logic.
Returns the ID of the currently active node, or nil if the dialogue is finished.
Returns the ID of the currently active node, or nil if the dialogue is finished.
Tombstones a node (clears its text and choices) while preserving index stability for other nodes.
Tombstones a node (clears its text and choices) while preserving index stability for other nodes.
Removes a choice from a node by its 0-based index.
Removes a choice from a node by its 0-based index.
Removes all stored variables from the dialogue context.
Removes all stored variables from the dialogue context.