Dialogue Manager Documentation

Dialogue Manager supports standard Godot BBCode and provides several custom tags for controlling dialogue flow and presentation:

• [[Option 1|Option 2]]: Picks one option at random from the list (requires double brackets).
• [wait=N]: Pauses typing for N seconds. Use [wait="ui_accept"] to wait for a specific action, or [wait] to wait for any action. You can also pass an array: [wait=["ui_accept","ui_cancel"]].
• [speed=N]: Multiplies the default typing speed by N.
• [next=N]: Waits N seconds before automatically continuing. Use [next=auto] to let the label determine wait time based on text length.

Use tags to attach metadata to dialogue lines. Tags are wrapped in [# and ].

• Simple tags: [#tag1, #tag2] adds tags to the tags property of a DialogueLine.
• Key-value tags: [#key=value] allows you to retrieve specific values using the get_tag_value("key") method on a DialogueLine object.

Nathan: [#happy, #surprised] Oh, Hello!
Nathan: [#mood=happy] Oh, Hello!

You can embed conditional text directly within a dialogue line using [if condition] and [/if] tags. For simple

Nathan: I have done this [if already_done]once again[/if]

Nathan: You have {{num_apples}} [if num_apples == 1]apple[else]apples[/if], nice!

Use match to replace long if/elif chains. You can check a property against specific values or use comparison operators like > in when clauses.

match SomeGlobal.some_property
    when 1
        Nathan: It is 1.
    when > 5
        Nathan: It is less than 5 (but not 1).
    else
        Nathan: It was something else.

To upgrade from version 2.x to 3.x:

1. Remove the addons/dialogue_manager directory.
2. Download a fresh copy of Dialogue Manager 3 from the Godot Asset Library or GitHub.

Requirements and Changes:

• Godot Version: Requires Godot 4.3 or above.
• Failed Responses: The "include failed responses" setting is removed; failed responses are now included by default. It is the responsibility of the balloon to filter them. The DialogueResponsesMenu node includes an option to hide failed responses.
• Character Lines: The "create lines for responses with characters" setting has been removed; this must now be handled manually in your game logic.
• Signal Emitting: The built-in emit mutation is removed. Use standard GDScript signal syntax instead (e.g., some_signal.emit()).

To prevent crashes when referencing properties of objects that might be null, use the ?. null coalescing operator in your conditions.

if some_node_reference?.name == "SomeNode"
    Nathan: Notice the "?." syntax?

To avoid typing full paths like SomeGlobal.some_property and instead use some_property, you can:

1. Set up global state shortcuts in Settings.
2. Add a using SomeGlobal clause at the top of your specific dialogue file.

Dialogue Manager 4 is an addon for Godot 4.6+ that provides a stateless branching dialogue editor and runtime. You can install it using one of the following methods:

1. Asset Library: Search for and install via the Godot Asset Library.
2. Manual Download: Download the latest version from GitHub and add it to your project.

IMPORTANT

Until Dialogue Manager 4 is officially released, you should probably use version 3.

https://github.com/nathanhoad/godot_dialogue_manager/archive/refs/heads/main.zip

Control the flow of dialogue using markers (Cues) and redirection (Jumps):

• Cues: Define a marker using ~ name. Cues cannot contain spaces.
• Jump: Redirect flow to a cue using => name.
• End Flow: Use => END to stop the current dialogue flow, or => END! to force an end regardless of any active 'jump and return' chains.
• Jump and Return: Use =>< name to jump to a cue and automatically return to the original location once the target cue reaches an END or the end of the file.
• Inline Jumps: Jumps can be used directly on response lines: - Response => cue_name.

~ start
Nathan: Well?
- First one
- Another one => another_cue
- Start again => start
=> END

~ another_cue
Nathan: Another one?
=> END

To customize the visual appearance of the dialogue balloon without losing changes during updates, use the built-in tool to copy it into your project:

1. Navigate to the Project > Tools menu in Godot.
2. Select the option to create a copy of the example balloon into your project.

Important: Never edit the original example balloon directly, as updates to the addon will overwrite your changes.

Once copied, you can customize the UI using Godot's UI control nodes. The balloon uses DialogueLabel and DialogueResponsesMenu nodes. The most common way to change the look is by modifying the theme attached to the Balloon panel.

A while block will loop as long as the provided condition remains true.

while SomeGlobal.some_property < 10
    Nathan: The property is still less than 10 - specifically, it is {{SomeGlobal.some_property}}.
    $> SomeGlobal.some_property += 1
Nathan: Now, we can move on.