Branching Dialogue

Create non-linear dialogue flows using gotos and branch IDs

Branching dialogue allows you to create non-linear conversations where the dialogue flow can jump to different parts of your dialogue tree.

Understanding Branches

The Dialogue Engine uses two concepts to manage dialogue flow:

• Branch IDs: Logical groups of dialogue entries (like chapters or conversation topics)
• Goto IDs: Explicit jumps to specific dialogue entries

Branch IDs

Each dialogue entry belongs to a branch ID. By default, all entries use branch ID 0 (the default branch).

enum { DEFAULT_BRANCH = 0, DIFFERENT_BRANCH_ONE, DIFFERENT_BRANCH_TWO }

add_text_entry("This is on the default branch")  # Branch 0
add_text_entry("This is on branch one", DIFFERENT_BRANCH_ONE)
add_text_entry("This is on branch two", DIFFERENT_BRANCH_TWO)

The DialogueEngine will only advance through entries in the current branch unless you use gotos to jump between branches.

Using Gotos Within the Same Branch

1. Create entries and store references

   Store references to entries you want to jump to:

   extends DialogueEngine
   
   func _setup() -> void:
       var first_entry: DialogueEntry = add_text_entry("This is an example of...")
       add_text_entry("This text will be skipped!")
       var target_entry: DialogueEntry = add_text_entry("a skipped dialogue!")
       add_text_entry("Press <Enter> or <Space> to exit.")
   
2. Set the goto

   Use set_goto_id() to jump directly to another entry:

   first_entry.set_goto_id(target_entry.get_id())
   

   Now the dialogue will jump from “This is an example of…” directly to “a skipped dialogue!”, skipping the middle entry.

Jumping Between Different Branches

You can jump to entries in different branches to organize your dialogue into logical sections:

extends DialogueEngine

enum { DEFAULT_BRANCH = 0, BRANCH_ONE, BRANCH_TWO, BRANCH_THREE }

func _setup() -> void:
    # Start on default branch
    var first_entry: DialogueEntry = add_text_entry("This is an example of...", DEFAULT_BRANCH)
    
    # Jump to a different branch
    var branch_two_start: DialogueEntry = add_text_entry(
        "how gotos work against different branch IDs", 
        BRANCH_TWO
    )
    first_entry.set_goto_id(branch_two_start.get_id())
    
    # Continue on branch two
    add_text_entry(
        "Once you jump to a different branch ID, the DialogueEngine will only consider entries in that branch ID.",
        BRANCH_TWO
    )
    
    # This entry won't be reached (no goto points to it)
    add_text_entry(
        "This text will be shown in the debugger but not in the dialogue.",
        BRANCH_ONE
    )
    
    add_text_entry("Press <Enter> or <Space> to exit.", BRANCH_TWO)

When you jump to a different branch, the DialogueEngine automatically updates its internal branch ID tracker, so subsequent advance() calls will only consider entries in the new branch.

Default Flow (No Goto)

If you don’t set a goto, the DialogueEngine automatically advances to the next entry in the same branch:

enum { TOPIC_A = 0, TOPIC_B = 1 }

add_text_entry("First entry in topic A", TOPIC_A)   # Entry 0
add_text_entry("Second entry in topic A", TOPIC_A)  # Entry 1
add_text_entry("First entry in topic B", TOPIC_B)   # Entry 2
add_text_entry("Second entry in topic B", TOPIC_B)  # Entry 3

If you start on branch TOPIC_A, the dialogue will flow: Entry 0 → Entry 1 → Finished (Entry 2 is skipped because it’s in a different branch).

Complete Examples

Same Branch Goto

extends DialogueEngine

func _setup() -> void:
    var first_entry: DialogueEntry = add_text_entry("This is an example of...")
    add_text_entry("This text will be shown on the debugger connected to branch ID 0")
    add_text_entry(
        "This text will be shown on the debugger as a separate graph node not connected to branch id 0",
        1
    )
    var first_entry_goto: DialogueEntry = add_text_entry(
        "a skipped dialogue! Check the debugger out!"
    )
    first_entry.set_goto_id(first_entry_goto.get_id())
    add_text_entry("Press <Enter> or <Space> to exit.")

extends DialogueEngine

enum { DEFAULT_BRANCH = 0, DIFFERENT_BRANCH_ONE, DIFFERENT_BRANCH_TWO, DIFFERENT_BRANCH_THREE }

func _setup() -> void:
    var first_entry: DialogueEntry = add_text_entry(
        "This is an example of...",
        DEFAULT_BRANCH
    )
    
    first_entry.set_goto_id(
        add_text_entry(
            "how gotos work against different branch IDs",
            DIFFERENT_BRANCH_TWO
        ).get_id()
    )
    
    add_text_entry(
        "Once you jump to a different branch ID, the DialogueEngine will only consider entries in that branch ID unless you jump to a different one.",
        DIFFERENT_BRANCH_TWO
    )
    
    add_text_entry(
        "For example, this text will be shown on branch ID %d in the debugger and not connected to anything. It won't show up in the interaction either." % DIFFERENT_BRANCH_ONE,
        DIFFERENT_BRANCH_ONE
    )
    
    add_text_entry(
        "You can also create full branches in a different branch ID",
        DIFFERENT_BRANCH_THREE
    )
    
    add_text_entry(
        "But since there's no jump to this branch (i.e. no goto set to this branch ID)",
        DIFFERENT_BRANCH_THREE
    )
    
    add_text_entry(
        "It won't show up in the interaction",
        DIFFERENT_BRANCH_THREE
    )
    
    add_text_entry(
        "See the auto-generated graph in Debugger/DialogueEngine.",
        DIFFERENT_BRANCH_TWO
    )
    
    add_text_entry("Press <Enter> or <Space> to exit.", DIFFERENT_BRANCH_TWO)

Visualizing Your Dialogue

The built-in debugger automatically generates a graph visualization of your dialogue tree, showing:

• All dialogue entries as nodes
• Goto connections between entries
• Branch IDs for each entry
• Disconnected entries (unreachable dialogue)

Use the debugger to verify your dialogue flow is correct! It will show you any unreachable entries or broken connections.

Best Practices

Use enums for branch IDs

Define branch IDs as enums for better readability:

enum DialogueBranch {
    MAIN_STORY = 0,
    SIDE_QUEST = 1,
    ROMANCE_PATH = 2,
}

Store entry references when you need to jump to them

var important_entry: DialogueEntry = add_text_entry("Important text")
# Later...
some_entry.set_goto_id(important_entry.get_id())

Check the debugger for unreachable entries

The debugger will show disconnected nodes for entries that can never be reached. This helps you catch dialogue flow bugs.

Next Steps

• Add player choices to let players influence the dialogue flow
• Use conditional branching to branch based on game state
• Learn about save/load to preserve dialogue state