Dialogue Manager

Dialogue Manager

Related skills: dialogue-system for hand-rolled dialogue data structures, localization for translating lines, popochiu for full adventure-game workflows.

Addon: Dialogue Manager · version v3.10.4 · Godot 4.6 · MIT · source: https://github.com/nathanhoad/godot_dialogue_manager · GDScript with official C# support.

1. When to use Dialogue Manager

Choose Dialogue Manager when writers want to author branching dialogue as readable script text (not Inspector-edited Resources) and you want built-in conditions, mutations, random lines, and a translation workflow (CSV or PO) for free. If you need dialogue as strongly-typed Resources you fully own, use dialogue-system instead. Dialogue Manager only handles dialogue — it is not a full adventure/quest framework, so a larger point-and-click framework would still own rooms, inventory, and actors around it.

2. Install & setup

1. Godot AssetLib → search "Dialogue Manager" → Download. Or copy addons/dialogue_manager/ from the GitHub repo into res://addons/dialogue_manager/.
2. Project → Project Settings → Plugins → enable "Dialogue Manager". This adds a Dialogue tab to the bottom editor panel and registers the DialogueManager autoload automatically — no manual autoload step needed.
3. addons/dialogue_manager/plugin.cfg:

[plugin]
name="Dialogue Manager"
description="A powerful nonlinear dialogue system"
author="Nathan Hoad"
version="3.10.4"
script="plugin.gd"

4. C# projects need no extra NuGet package — using DialogueManagerRuntime; is enough (§4).
5. Settings live at Project Settings → General → Dialogue Manager: notably State Autoload Shortcuts (autoload names usable in dialogue without a prefix) and Balloon Path (the scene show_dialogue_balloon() opens — leave empty to use the built-in example balloon).

3. .dialogue syntax

Open/create a .dialogue file from the Dialogue editor tab. Lines are Character: text or bare text (narrator). Godot's RichTextLabel BBCode works, plus extras: [[A|B|C]] (random inline pick), [wait=N] / [wait="ui_accept"] (pause typing), [speed=N], [next=auto] (auto-advance).

Titles and jumps — ~ name marks a title; => name jumps to it; => END ends the flow; => END! force-ends past any pending jump-and-returns; =>< name jumps and returns here once that branch hits END:

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

~ another_title
Nathan: Another one?
=> END

Responses (- ) nest by indentation and can carry a condition in [...] — put any jump last:

Nathan: How many projects have you started and not finished?
- Just a couple
	Nathan: That's not so bad.
- A lot [if SomeGlobal.some_property == true]
	Nathan: Maybe you should finish one before another.
- Another one [if SomeGlobal.some_method()] => another_title

Conditions — if / elif / else, boolean and/or/(), and match/while blocks:

if SomeGlobal.some_property >= 10
    Nathan: That property is >= 10.
elif SomeGlobal.some_other_property == "some value"
    Nathan: Or we might be in here.
else
    Nathan: If neither are true, I'll say this.

Inline conditions: Nathan: I have done this [if already_done]once again[/if], with an optional [else]. Null-safe member access uses ?.: if some_node_reference?.name == "SomeNode".

Mutations — set assigns state, do calls a method or emits a signal; both can run inline ([do wave()], suppress the implicit await with [do! wave()]):

if SomeGlobal.has_met_nathan == false
    do SomeGlobal.animate("Nathan", "Wave")
    Nathan: Hi, I'm Nathan.
    set SomeGlobal.has_met_nathan = true

Built-in mutations: do wait(float), do debug(...). Emit a signal from dialogue with do SomeGlobal.some_signal.emit("arg").

Locals vs extra game states — set locals.asked = true creates a per-conversation temp variable (a convention implemented by the example balloon, not a Dialogue Manager core feature). Objects passed in the extra_game_states array are referenced directly by name and their mutations persist after the conversation ends — pass instances, not classes (GameStateClass.new(), never the bare class).

Randomised lines — prefix with % (equal weight) or %N (relative weight); a blank line separates random groups:

Nathan: I will say this.
%3 Nathan: This line has a 60% chance of being picked
%2 Nathan: This line has a 40% chance of being picked

Variables and tags — {{SomeGlobal.some_property}} interpolates state into text (also usable as a character name). [#happy, #mood=calm] attaches tags, readable via line.get_tag_value("mood").

4. Runtime API & example balloon

Load a DialogueResource (.dialogue file) and either let DialogueManager open a balloon for you, or pull lines manually with await DialogueManager.get_next_dialogue_line(resource, title). When there is no next line it returns null — check falsy in GDScript (if not line: / while line:) and line != null in C#. (The tag's API.md prose says "empty dictionary {}", but the v3.10.4 source returns null on every end-of-dialogue path — a line == {} check would never fire.)

GDScript

# npc.gd
extends Node2D

@export var dialogue_resource: DialogueResource

func _on_interact() -> void:
    # Opens the configured balloon (Settings → Balloon Path), or the built-in example balloon.
    DialogueManager.show_dialogue_balloon(dialogue_resource, "start")

func _manual_walk() -> void:
    # Manual traversal — build a totally custom balloon around this loop.
    var line: DialogueLine = await DialogueManager.get_next_dialogue_line(dialogue_resource, "start")
    while line:
        print("%s: %s" % [line.character, line.text])
        if line.responses.is_empty():
            line = await DialogueManager.get_next_dialogue_line(dialogue_resource, line.next_id)
        else:
            var chosen: DialogueResponse = line.responses[0]  # replace with real UI selection
            line = await DialogueManager.get_next_dialogue_line(dialogue_resource, chosen.next_id)

C#

// Npc.cs
using Godot;
using DialogueManagerRuntime;

public partial class Npc : Node2D
{
    [Export] public Resource DialogueResource;

    private void OnInteract()
    {
        DialogueManager.ShowDialogueBalloon(DialogueResource, "start");
    }

    private async void ManualWalk()
    {
        var line = await DialogueManager.GetNextDialogueLine(DialogueResource, "start");
        while (line != null)
        {
            GD.Print($"{line.Character}: {line.Text}");
            if (line.Responses.Count == 0)
            {
                line = await DialogueManager.GetNextDialogueLine(DialogueResource, line.NextId);
            }
            else
            {
                var chosen = line.Responses[0]; // replace with real UI selection
                line = await DialogueManager.GetNextDialogueLine(DialogueResource, chosen.NextId);
            }
        }
    }
}

Other DialogueManager methods: show_dialogue_balloon_scene(balloon_scene, resource, title) (open a specific balloon scene), show_example_dialogue_balloon(resource, title) (force the built-in balloon), create_resource_from_text(text) (compile a .dialogue string at runtime — fails on syntax errors). C# names are identical PascalCase: ShowDialogueBalloonScene, ShowExampleDialogueBalloon, CreateResourceFromText.

get_next_dialogue_line takes a mutation_behaviour param — GDScript DMConstants.MutationBehaviour, C# MutationBehaviour (both: Wait default, DoNotWait, Skip). The enum lives on DMConstants, not on the DialogueManager autoload. Leave it Wait unless you know otherwise; the example balloon only supports Wait.