dialogue-manager
Use when using the Dialogue Manager addon — .dialogue files with titles, responses, conditions and mutations, runtime balloons, and C# support
jame581 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add jame581/GodotPrompter --skill dialogue-managerAbout this skill
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
- Godot AssetLib → search "Dialogue Manager" → Download. Or copy
addons/dialogue_manager/from the GitHub repo intores://addons/dialogue_manager/. - Project → Project Settings → Plugins → enable "Dialogue Manager". This adds a Dialogue tab to
the bottom editor panel and registers the
DialogueManagerautoload automatically — no manual autoload step needed. 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"
- C# projects need no extra NuGet package —
using DialogueManagerRuntime;is enough (§4). - 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