/dialogue-manager

name: dialogue-manager
description: Use when using the Dialogue Manager addon — .dialogue files with titles, responses, conditions and mutations, runtime balloons, and C# support

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

| Approach | Best for | |---|---| | **dialogue-system** skill (hand-rolled `Resource` data) | Full control over data shape, no addon dependency, small dialogue trees | | **Dialogue Manager** | Script-like `.dialogue` text format, branching responses, conditions/mutations, translation pipeline, visual editor tab, official C# wrapper | | Full adventure-game framework | Point-and-click games needing rooms/inventory/actors bundled with dialogue — Dialogue Manager only owns the dialogue layer |

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](https://github.com/nathanhoad/godot_dialogue_manager) 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` o