> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Rubonnek/dialogue-engine/llms.txt
> Use this file to discover all available pages before exploring further.

# 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).

```gdscript theme={null}
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)
```

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

## Using Gotos Within the Same Branch

<Steps>
  <Step title="Create entries and store references">
    Store references to entries you want to jump to:

    ```gdscript theme={null}
    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.")
    ```
  </Step>

  <Step title="Set the goto">
    Use `set_goto_id()` to jump directly to another entry:

    ```gdscript theme={null}
    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.
  </Step>
</Steps>

## Jumping Between Different Branches

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

```gdscript theme={null}
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)
```

<Tip>
  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.
</Tip>

## Default Flow (No Goto)

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

```gdscript theme={null}
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

<CodeGroup>
  ```gdscript Same Branch Goto theme={null}
  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.")
  ```

  ```gdscript Different Branch Goto theme={null}
  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)
  ```
</CodeGroup>

## 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)

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

## Best Practices

<AccordionGroup>
  <Accordion title="Use enums for branch IDs">
    Define branch IDs as enums for better readability:

    ```gdscript theme={null}
    enum DialogueBranch {
        MAIN_STORY = 0,
        SIDE_QUEST = 1,
        ROMANCE_PATH = 2,
    }
    ```
  </Accordion>

  <Accordion title="Store entry references when you need to jump to them">
    ```gdscript theme={null}
    var important_entry: DialogueEntry = add_text_entry("Important text")
    # Later...
    some_entry.set_goto_id(important_entry.get_id())
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next Steps

* Add [player choices](/guides/player-choices) to let players influence the dialogue flow
* Use [conditional branching](/guides/player-choices#conditional-branching) to branch based on game state
* Learn about [save/load](/guides/save-load) to preserve dialogue state