Skip to main content

​
Overview

Dialogue Engine structures conversations as dialogue trees - sequences of dialogue entries that flow from one to another. Each tree is composed of individual entries that can be text-based or conditional, allowing you to create both linear and branching conversations.

​
Dialogue Entries

Every piece of dialogue in the engine is represented by a DialogueEntry. Each entry contains:
  • Entry ID: A unique identifier assigned automatically when the entry is created
  • Branch ID: Identifies which branch the entry belongs to (default is 0)
  • Content: Either dialogue text or a conditional callable
  • Metadata: Optional custom data attached to the entry

​
Creating Text Entries

Text entries are the most common type of dialogue entry: 
var dialogue_engine = DialogueEngine.new()

# Add a simple text entry
dialogue_engine.add_text_entry("Hello, traveler!")
dialogue_engine.add_text_entry("Welcome to our village.")
dialogue_engine.add_text_entry("Press <Enter> to continue.")

​
Accessing Entries

You can retrieve entries by their ID or by name: 
# Get entry by ID
var entry = dialogue_engine.get_entry(0)

# Get entry by name
var named_entry = dialogue_engine.add_text_entry("Important dialogue")
named_entry.set_name("greeting")
var retrieved = dialogue_engine.get_entry_with_name("greeting")

​
Tree Structure

Dialogue trees are stored internally as an array of dictionaries, with each entry accessible through its unique ID. The engine maintains a read needle that tracks the current position in the tree.

​
Entry Properties

Each DialogueEntry provides access to: 
var entry = dialogue_engine.add_text_entry("Sample text")

# Get the entry's unique ID
var id = entry.get_id()

# Get the entry's branch ID
var branch_id = entry.get_branch_id()

# Get the entry's text
var text = entry.get_text()

# Check if entry has text
if entry.has_text():
    print(text)

​
Advancing Through the Tree

The engine walks through the dialogue tree using the advance() method: 
var dialogue_engine = DialogueEngine.new()
dialogue_engine.add_text_entry("First line")
dialogue_engine.add_text_entry("Second line")

# Connect to the signal to receive dialogue
var print_dialogue = func(dialogue_entry: DialogueEntry) -> void:
    print(dialogue_entry.get_text())

dialogue_engine.dialogue_continued.connect(print_dialogue)

# Advance through the dialogue
dialogue_engine.advance() # prints "First line"
dialogue_engine.advance() # prints "Second line"
dialogue_engine.advance() # dialogue finishes, resets automatically

​
Dialogue Signals

The engine emits several signals as it traverses the tree:
  • dialogue_started: Emitted when the first entry is read
  • dialogue_continued: Emitted when a text entry is visited
  • entry_visited: Emitted when any entry (text or conditional) is visited
  • dialogue_about_to_finish: Emitted before the dialogue ends
  • dialogue_finished: Emitted when the dialogue completes
  • dialogue_canceled: Emitted if the dialogue is interrupted or encounters an error
dialogue_engine.dialogue_started.connect(func() -> void:
    print("Dialogue has started!")
)

dialogue_engine.dialogue_finished.connect(func() -> void:
    print("Dialogue complete!")
)

​
Managing the Tree

The engine provides several utility methods for managing the dialogue tree: 
# Check tree size
var entry_count = dialogue_engine.size()

# Check if tree is empty
if dialogue_engine.is_empty():
    print("No dialogue entries")

# Reset the read position
dialogue_engine.reset()

# Clear all entries
dialogue_engine.clear()

# Get current entry
var current = dialogue_engine.get_current_entry()
if current:
    print(current.get_text())

​
Example: Simple Dialogue Tree

Here’s a complete example from the demos: 
extends DialogueEngine

func _setup() -> void:
    add_text_entry("Hey...")
    add_text_entry("Have you seen the code for this sample?")
    add_text_entry("It's beautiful!")
    add_text_entry("You won't believe it!")
    add_text_entry("Press <Enter> or <Space> to exit.")

​
Best Practices

Always connect to dialogue_continued or entry_visited signals before calling advance() to ensure you receive the dialogue content.
The dialogue tree automatically resets when it finishes. If you need to restart dialogue, simply call advance() again - it will start from the beginning.

​
Next Steps

Branching

Learn how to create branches with different IDs

Conditions

Add conditional logic to your dialogue

Build docs developers (and LLMs) love

Get started for freeTalk to us