90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# Dialogue System
|
|
|
|
All authored text — NPC conversations, item pickup messages, battle narration — is written in `.dialogue` files and played back via `DialogueManager` (godot_dialogue_manager v3.10.4).
|
|
|
|
## Plugin
|
|
|
|
- Autoload: `DialogueManager` (registered in `project.godot`)
|
|
- Plugin must be enabled in Godot → Project Settings → Plugins → Dialogue Manager
|
|
- `.dialogue` files are imported as `DialogueResource` once the plugin is active
|
|
- Dialogue files live in `dialogue/` organised by category (`npc/`, `item/`, `battle/`)
|
|
|
|
## DialogueAction — the Cutscene bridge
|
|
|
|
[cutscene/dialogue/DialogueAction.gd](../../cutscene/dialogue/DialogueAction.gd) is the glue between the `Cutscene` queue and `DialogueManager`. It runs a `.dialogue` file through `VNTextbox` line-by-line and returns `CUTSCENE_CONTINUE` when the last line is dismissed.
|
|
|
|
```gdscript
|
|
# Add a dialogue step to any Cutscene
|
|
cutscene.addCallable(DialogueAction.getDialogueCallable(
|
|
load("res://dialogue/npc/test.dialogue"),
|
|
"start", # title to begin from
|
|
[entity] # extra_game_states: objects/dicts accessible in the .dialogue file
|
|
))
|
|
```
|
|
|
|
Movement is blocked automatically while dialogue runs because `VNTextbox` is open (`EntityMovement._canMove()` checks `UI.TEXTBOX.isClosed`).
|
|
|
|
## Writing .dialogue files
|
|
|
|
```
|
|
~ title_name # entry point / jump target
|
|
|
|
Speaker: Line of dialogue.
|
|
Another line with no speaker.
|
|
|
|
~ another_section
|
|
Speaker: Variables resolve inline: {{some_property}}.
|
|
=> END # end this dialogue
|
|
```
|
|
|
|
**Key syntax:**
|
|
- `~ title` — section anchor; use as the `title` argument to `DialogueAction`
|
|
- `=> title` — jump to another section; `=> END` ends the dialogue
|
|
- `{{variable}}` — resolves a property from any autoload or `extra_game_states` object
|
|
- `do AUTOLOAD.method()` — call a method on any autoload (e.g. `do PARTY.BACKPACK.addStack(stack)`)
|
|
- `set AUTOLOAD.property = value` — set a property
|
|
- `- Option text` — response branch (indented lines handle each branch)
|
|
- `[if condition]` — conditional line or response
|
|
|
|
**Mutations fire automatically** before the next dialogue line is returned — you do not handle them manually in GDScript.
|
|
|
|
## Passing runtime data to dialogue
|
|
|
|
Use `extra_game_states` to expose GDScript objects to `{{variable}}` tokens:
|
|
|
|
```gdscript
|
|
class ItemDialogueState:
|
|
var item_name:String
|
|
var quantity:int
|
|
|
|
DialogueAction.getDialogueCallable(resource, 'start', [ItemDialogueState.new("Potato", 1)])
|
|
```
|
|
|
|
Then in the `.dialogue` file:
|
|
```
|
|
Obtained {{item_name}} x{{quantity}}.
|
|
```
|
|
|
|
## NPC entities
|
|
|
|
Set these two exports on an Entity node whose `interactType = CONVERSATION`:
|
|
|
|
| Export | Purpose |
|
|
|---|---|
|
|
| `dialogueResource:DialogueResource` | The `.dialogue` file to run |
|
|
| `dialogueTitle:String` | Title (section) to start from (default `"start"`) |
|
|
|
|
After first enabling the plugin and reimporting, assign `dialogueResource` directly in the Inspector. Until then, assign it in code (see [TestMap.gd](../../overworld/map/TestMap.gd) for the pattern).
|
|
|
|
## Dialogue files
|
|
|
|
| File | Used by |
|
|
|---|---|
|
|
| `dialogue/npc/test.dialogue` | TestMap NPC (NotPlayer) |
|
|
| `dialogue/item/pickup.dialogue` | `ItemAction` — item pickup text with `{{item_name}}` and `{{quantity}}` |
|
|
| `dialogue/battle/narration.dialogue` | `BattleCutsceneAction` — move announcements, victory/defeat |
|
|
|
|
## Response branching (current limitation)
|
|
|
|
`DialogueAction` auto-selects the **first allowed response** when a line has multiple options. There is no in-game response UI yet. To add one, replace the auto-select block in `DialogueAction.dialogueCallable` with a call to your response menu and `await` its selection signal.
|