---
name: dialogue-manager
description: Use when using the Dialogue Manager addon — .dialogue files with cues, responses, conditions and mutations, runtime balloons, actionable nodes, and C# support
title: dialogue-manager
canonical_url: https://skilld.dev/gh/jame581/godotprompter/dialogue-manager
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/migrating-from-3.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/dialogue-manager/references/migrating-from-3.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/dialogue-manager`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/dialogue-manager`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/dialogue-manager) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/dialogue-manager`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/dialogue-manager --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/dialogue-manager --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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 `v4.2.0` · Godot 4.6+ (built for 4.7; Godot 4.4–4.5 → v3.10, 4.3 → v3.3, see §7) · MIT · source: https://github.com/nathanhoad/godot_dialogue_manager · GDScript with official C# support.

> **Godot 4.8:** not yet confirmed by the addon. v4.2.0 is released "for Godot 4.7", and no open issue mentions 4.8 (checked 2026-11-12).

---

## 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 translation
templates for free. If you need dialogue as strongly-typed Resources you fully own, use
`dialogue-system` instead. It is not a quest or adventure framework.

---

## 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** (**Project Settings → Addons → Plugins** on 4.8) → enable "Dialogue Manager". This adds a **Dialogue** main-screen
   tab and registers the `DialogueManager` autoload automatically — no manual autoload step.
3. `addons/dialogue_manager/plugin.cfg`:

```ini
[plugin]
name="Dialogue Manager"
description="A powerful branching dialogue system"
author="Nathan Hoad"
version="4.2.0"
script="plugin.gd"
```

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

---

## 3. `.dialogue` syntax

Lines are `Character: text` or bare `text` (narrator). Godot's RichTextLabel BBCode works, plus
`[[A|B|C]]` (random inline pick), `[wait=N]` / `[wait="ui_accept"]`, `[speed=N]`, `[next=auto]`.

**Cues and jumps** — `~ name` marks a **cue** (3.x called it a "title"); `=> name` jumps to it;
`=> END` ends the flow; `=> END!` force-ends past pending jump-and-returns; `=>< name` jumps and returns
here once that branch hits `END`. `import "res://other.dialogue" as other` then `=>< other/cue`.
Do not indent the line directly after a cue.

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

~ another_cue
Nathan: Another one?
=> END
```

**Responses** (`- `) nest by indentation. A response condition is **self-closing** — `[if cond /]` —
and any jump goes *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_cue
```

A response whose condition fails is still returned, with `is_allowed == false` — your UI filters it.

**Conditions** — `if` / `elif` / `else`, `and`/`or`/`()` (short-circuiting), and `match`/`when`/`while`:

```
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 inside a line are *not* self-closing: `Nathan: I have done this [if already_done]once again[/if]`,
with an optional `[else]`. Null-safe member access uses `?.`.

**Mutations** — `$>` assigns state or calls a method/emits a signal; inline `[$> wave()]` awaits,
`[$>> wave()]` does not. `set` / `do` / `[do!]` still parse but are deprecated:

```
if SomeGlobal.has_met_nathan == false
	$> SomeGlobal.animate("Nathan", "Wave")
	Nathan: Hi, I'm Nathan.
	$> SomeGlobal.has_met_nathan = true
```

Built-ins: `$> wait(1.0)`, `$> debug(...)`. Signals: `$> SomeGlobal.some_signal.emit("arg")`.

**State** — autoloads first; a `DialogueStateContext` node (`alias` + `target`) exposes a scene node while it
is in the tree; `extra_game_states` (pass **instances**, never bare classes) is the last resort.
`$> locals.asked = true` is a per-conversation variable implemented by the *example balloon*, not core.

**Randomised lines** — `%` (equal weight) or `%N` (relative weight); a blank line separates groups. A
condition on a random line is self-closing too: `% [if cond /] Nathan: Only sometimes.`

```
%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. `[#happy, #mood=calm]`
attaches tags, read with `line.has_tag("happy")` / `line.get_tag_value("mood")`.

---

## 4. Runtime API — balloons and manual traversal

Either let `DialogueManager` open a balloon, or pull lines with
`await DialogueManager.get_next_dialogue_line(resource, cue_or_id)`. At the end it returns `null` (and
emits `dialogue_ended`) — test `while line:` / `if not line:` in GDScript, `line != null` in C#.

### GDScript

```gdscript
# npc.gd
extends Node2D

@export var dialogue_resource: DialogueResource

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

func _manual_walk() -> void:
	# Manual traversal for a fully custom UI.
	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 allowed: Array = line.responses.filter(func(r: DialogueResponse) -> bool: return r.is_allowed)
			if allowed.is_empty():
				break  # nothing selectable; end the walk
			var chosen: DialogueResponse = allowed[0]  # replace with real UI selection
			line = await DialogueManager.get_next_dialogue_line(dialogue_resource, chosen.next_id)
```

### C#

```csharp
// Npc.cs
using System.Linq;
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.FirstOrDefault(r => r.IsAllowed); // replace with real UI selection
                if (chosen == null) break; // nothing selectable; end the walk
                line = await DialogueManager.GetNextDialogueLine(DialogueResource, chosen.NextId);
            }
        }
    }
}
```

Other methods (the `cue` parameter; C# names it `key`): `show_dialogue_balloon_scene(balloon_scene, resource, cue)`,
`show_example_dialogue_balloon(resource, cue)`, `set_default_balloon(scene)` (runtime override of Balloon
Path), `create_resource_from_text(text)`. C#: `ShowDialogueBalloonScene`, `ShowExampleDialogueBalloon`,
`SetDefaultBalloon`, `CreateResourceFromText`. `get_next_dialogue_line`'s `mutation_behaviour` is
`DMConstants.MutationBehaviour` (C# `MutationBehaviour`): `Wait` (default), `DoNotWait`, `Skip`. Leave it
`Wait` — the example balloon only supports `Wait`.

---

## 5. Actionable nodes ("press to talk")

`DialogueActionable2D` / `DialogueActionable3D` (an `Area2D` / `Area3D`; the upstream docs shorten them to
`Actionable2D`) hold `dialogue_resource` + `dialogue_cue`. `action()` opens the balloon, passing
`{actionable = self}` and the node's `owner` as extra game states; `dialogue_ended` fires when that resource
ends. The picker adds the GDScript nodes — attach the C# scripts by hand to get the C# classes.

### GDScript

```gdscript
# player.gd
extends CharacterBody2D

func _unhandled_input(event: InputEvent) -> void:
	if event.is_action_pressed("ui_accept"):
		var nearest: DialogueActionable2D = DialogueActionable2D.get_nearest_actionable_to(global_position)
		if nearest:
			nearest.action()
```

### C#

```csharp
public override void _UnhandledInput(InputEvent @event)
{
    if (@event.IsActionPressed("ui_accept"))
    {
        // Finds only nodes running the C# DialogueActionable2D script.
        DialogueActionable2D.GetNearestActionableTo(GlobalPosition)?.Action();
    }
}
```

Both languages scan the shared `dialogue_actionables` group; the GDScript `get_nearest_actionable_to()` uses a
typed loop, so it errors in a mixed project where C# actionables are in that group too.

---

## 6. Signals, typed access, saving

`DialogueLine`: `id`, `next_id`, `character`, `text`, `tags`, `static_id`, `responses` (untyped `Array` of
`DialogueResponse`), `concurrent_lines`. `DialogueResponse` adds `is_allowed` and `condition_as_text`.
Treat `id`/`next_id` as opaque strings (they can be `<uid>@<id>`).

### GDScript

```gdscript
func _ready() -> void:
	DialogueManager.dialogue_started.connect(_on_dialogue_started)
	DialogueManager.dialogue_ended.connect(_on_dialogue_ended)
	DialogueManager.got_dialogue.connect(_on_got_dialogue)
	DialogueManager.passed_cue.connect(func(cue: String) -> void: print("cue ", cue))

func _on_dialogue_started(resource: DialogueResource) -> void:
	pass

func _on_dialogue_ended(resource: DialogueResource) -> void:
	pass  # tell the HUD the conversation is over

func _on_got_dialogue(line: DialogueLine) -> void:
	print(line.character, ": ", line.text, " id=", line.static_id)

# Save/restore the current line (persisted .dialogue files only).
func save_line(line: DialogueLine) -> String:
	return line.to_serialized()

func load_line(data: String) -> DialogueLine:
	return await DialogueLine.new_from_serialized(data)
```

### C#

```csharp
using System.Threading.Tasks;
using Godot;
using DialogueManagerRuntime;

public override void _Ready()
{
    DialogueManager.DialogueStarted += (Resource resource) => { };
    DialogueManager.DialogueEnded += (Resource resource) => { /* tell the HUD */ };
    DialogueManager.GotDialogue += (DialogueLine line) => GD.Print($"{line.Character}: {line.Text} id={line.StaticId}");
    DialogueManager.PassedCue += (string cue) => GD.Print($"cue {cue}");
}

// No C# serializer: store Id and NextId, then re-fetch the line by Id.
public async Task<DialogueLine> LoadLine(Resource resource, string id, string nextId)
{
    var line = await DialogueManager.GetNextDialogueLine(resource, id);
    if (line != null) line.NextId = nextId;
    return line;
}
```

`mutated(mutation)` / `Mutated` fires before a non-assignment mutation runs (calls, emits, `wait`) — not
assignments. Also new: `waiting_for_input` / `waited_for_input`.

> ⚠️ The C# events are bridged to the Godot signals lazily, on the **first access to
> `DialogueManager.Instance`**. A project that subscribes from C# but drives dialogue from GDScript never
> touches `Instance`, so the handlers never fire — add `_ = DialogueManager.Instance;` first.

The C# `DialogueResponsesMenu` script exposes `ResponseSelected` as a C# event. The GDScript node from
the picker does not, and its argument is the GDScript `RefCounted`, not the C# wrapper — connect with
`Connect("response_selected", Callable.From((RefCounted r) => { var response = new DialogueResponse(r); }))`.

**Translations.** Text goes through `tr()`. With **Use Static IDs as Translation Keys** (default on), a
line's static ID (`Nathan: Hi! [ID:HI_IM_NATHAN]`) is the key and `"dialogue"` the context; `##` comments
become translator notes. Export templates (PO or CSV) via **Project Settings → Localization → Template
Generation**, or **Project → Tools → Dialogue → Simple CSV export…**. Locale switching and RTL: **localization**.

---

## 7. Migrating from 3.x

| 3.x | 4.x |
|---|---|
| "title", `passed_title`, `titles`/`get_titles()`, C# `PassedTitle` | "cue", `passed_cue`, `cues`/`get_cues()`, C# `PassedCue` (`~ name` unchanged) |
| `- Text [if cond]`, `% [if cond] Line` | `- Text [if cond /]`, `% [if cond /] Line` |
| `set x = 1`, `do f()`, `[do f()]`, `[do! f()]` | `$> x = 1`, `$> f()`, `[$> f()]`, `[$>> f()]` |
| `translation_key` / C# `TranslationKey` | `static_id` / C# `StaticId` |
| `DialogueManager.translation_source`, Dialogue-tab CSV import/export | removed — Template Generation / Simple CSV export |
| Godot 4.3+ | Godot 4.6+ |

A 3.x response condition `[if cond]` still compiles in 4.x with **no error**: the response is always
allowed and `[if cond]` shows up in its text. Upgrade checklist and the full rename list:
[references/migrating-from-3.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/dialogue-manager/references/migrating-from-3.md).

---

## Implementation checklist

- [ ] Dialogue Manager plugin enabled (registers the `DialogueManager` autoload); Godot 4.6+ for v4
- [ ] `.dialogue` resources loaded via `load()`/`preload()`, not parsed by hand
- [ ] Every `get_next_dialogue_line` / `GetNextDialogueLine` call is `await`ed
- [ ] Manual loops detect the end via the `null` return (`while line:` / `line != null`), never `{}`
- [ ] Response conditions are self-closing `[if condition /]`, placed before any `=> cue` jump
- [ ] Custom UIs skip responses whose `is_allowed` is `false`
- [ ] Mutations use `$>` / `[$> …]`; `[$>> …]` when the caller shouldn't block
- [ ] Scene state exposed with `DialogueStateContext`; `extra_game_states` entries are **instances**
- [ ] C# state properties that dialogue reads/writes carry `[Export]`
- [ ] C# uses `using DialogueManagerRuntime;` and PascalCase (`GetNextDialogueLine`, `DialogueEnded`, `PassedCue`, `StaticId`)
- [ ] Custom balloons set **Balloon Path** (or `set_default_balloon`) rather than forking call sites
- [ ] Static line IDs (`[ID:KEY]`) on any line needing voice-over or stable translation keys
