Dialogue Config

Author branching NPC conversations declaratively — nodes, choices, world-flag conditions, and actions — in dialogue-config.yaml.

An NPC’s conversation can be authored as data instead of Lua. A mob names a dialogue tree by id (dialogue: in mob-config.md); the server then walks the node graph defined in dialogue-config.yaml — showing text, offering choices, following branches, and firing actions — with no per-NPC script. The server-on-dialogue-* Lua hooks remain available for bespoke NPCs; a mob that declares both uses the declarative tree.

All dialogue text is a localization key, resolved on the client at draw time (see the string table in assets/lang/), never a raw string — so every line is translatable and lives with the rest of the game’s text.

File Location

dialogue-config.yaml in your mod root, registered by the dialogue-config: key in your mod manifest.

Structure

dialogues:
  - id: some_survivor                    # referenced by a mob's `dialogue: some_survivor`
    start: [greet_return, greet_first]   # entry candidates; first whose condition passes wins
    nodes:
      greet_first:
        text: dialogue.some_survivor.greet_first   # a localization key
        on-enter:
          - { type: set-flag, flag: met_survivor } # fires when the node is shown
        choices:
          - text: dialogue.some_survivor.ask
            goto: about                             # advance to another node
          - text: dialogue.common.trade
            action: { type: open-trade }            # open this NPC's shop (needs a `vendor:` block)
          - text: dialogue.common.bye
            action: { type: end }                   # close the dialogue
      greet_return:
        text: dialogue.some_survivor.greet_return
        condition: { flag: met_survivor }           # only eligible as the entry when this passes
        choices:
          - text: dialogue.common.bye
            action: { type: end }
      about:
        text: dialogue.some_survivor.about
        choices:
          - text: dialogue.some_survivor.secret
            condition: { flag: knows_secret }        # this choice is hidden unless the flag is set
            goto: about
          - text: dialogue.common.back
            goto: greet_first

Fields

Dialogue

Field	Default	Behavior
`id`	(required)	The dialogue’s id, referenced by a mob’s `dialogue:`. Mod-prefixed at load.
`start`	(required)	The entry node, or an ordered list of candidates — on open, the first whose `condition` passes becomes the entry (a candidate with no condition always passes, so put it last as the fallback). This is how an NPC greets differently on a first meeting vs. a return visit.
`nodes`	(required)	A map of node id → node.

Node

Field	Default	Behavior
`text`	(required)	Localization key for the node’s body text.
`portrait`	(none)	Optional NPC animation name shown in the portrait box.
`condition`	(none)	Consulted only when this node is a `start` candidate (see `start`). Ignored for `goto` targets — a `goto` always lands. See Conditions.
`on-enter`	(none)	Actions fired when the node is shown. Only `set-flag` is valid here (state effects); `end` / `open-trade` are choice actions.
`choices`	(none)	The buttons offered on this node. A node with no choices is a dead end (the player can only close).

Choice

Field	Default	Behavior
`text`	(required)	Localization key for the button label.
`condition`	(none)	Visibility gate — the choice is only offered when it passes. See Conditions.
`goto`	(one required)	Advance to another node (by id). Mutually exclusive with `action`.
`action`	(one required)	A terminal effect instead of advancing. Mutually exclusive with `goto`. See Actions.

A choice must have exactly one of goto / action.

Conditions

A condition tests a world-flag (the persistent, save-scoped story/progression flag set that also backs recruitment and boss first-kills). Exactly one field:

Form	Passes when
`{ flag: NAME }`	the flag is set
`{ not-flag: NAME }`	the flag is not set

Actions

`type`	Extra fields	Effect
`set-flag`	`flag: NAME`	Set a world-flag (mark met, recruited, a story beat). Only valid in a node’s `on-enter`.
`end`	—	Close the dialogue. (Choice action.)
`open-trade`	—	Close the dialogue and open this NPC’s shop. Requires the mob to have a `vendor:` block (see mob-config.md); the NPC is the vendor. (Choice action.)
`recruit`	—	Close the dialogue and recruit this NPC: they leave the world and travel to the player’s home, arriving after their `arrival-delay-ms`. Requires the mob to have a `survivor:` block (see mob-config.md); on any other NPC it does nothing but log. (Choice action.)

To both set a flag and continue, goto a node whose on-enter sets the flag.

Validation

A structurally broken dialogue is skipped at load (a loud error), leaving the rest of the file usable: a start/goto pointing at a missing node, a choice with neither or both of goto/action, a set-flag used as a choice action (or end/open-trade/recruit in on-enter), or a condition without exactly one of flag/not-flag.

Example

The shipped reference is reference_survivor_dialogue (the reference_survivor NPC), which exercises every feature: a flag-varied entry, an on-enter set-flag, a branch, a condition-gated choice, an open-trade choice (the survivor is also a vendor), and end. See instances/original_copy/mods/Creation/dialogue-config.yaml.

Last updated Sep 29, 2026