Dialog Files

Big conversations get unwieldy in one file. NMEntities lets you split a dialog’s nodes across a folder, one file per node, called like functions.

The simple form

A .yml in Dialogs/ with everything inline. Fine for short conversations:

# Dialogs/bob.yml
bob_talk:
  start: [greet]
  greet:
    say: "&fHello!"

Nodes can also be wrapped in a nodes: key if you prefer the extra structure. Both parse the same.

One file per node

For anything bigger, register the dialog in a file directly in Dialogs/, then put its nodes in a subfolder named after the dialog id. A goto: greet then calls bob_talk/greet.yml like a function:

Dialogs/
  dialogs.yml        # registers the dialog: bob_talk: { start: [night_greet, greet] }
  bob_talk/
    night_greet.yml  # the node "night_greet"
    greet.yml
    who.yml
    trade.yml

Each node file holds that node’s fields at the top level, no wrapping key:

# Dialogs/bob_talk/greet.yml
say:
- "&fWell hello, <player.name>!"
- "&fWhat can I do for you?"
choices:
- text: "Who are you?"
  goto: who
- text: "Bye."

Now each conversation branch is its own file: easy to find, easy to diff, easy to hand to someone else to write.

Mixing both

Inline nodes and folder files merge freely. Keep the common nodes inline and split out the long branches, or the other way around. If the same node name exists in both, the file wins and a warning is logged.

A folder with no declaration

A subfolder works on its own, with no entry in any Dialogs/*.yml. The entry node is picked in this order:

A dialog.yml meta file in the folder, if it declares start:.
A start.yml node file.
The alphabetically first file in the folder.

So the quickest possible dialog is a folder with a single start.yml in it.

YAML gotcha: conditions with braces

Conditions that take attributes use braces, and braces mean something else in YAML’s inline list syntax. Write conditions as block lists:

conditions:
- hasitem{item=diamond}

Or quote them. This is invalid YAML and will fail to load:

conditions: [hasitem{item=diamond}]   # ✗ breaks

Inline lists are fine for conditions without braces: conditions: [isnight] works.

Getting Started

Commands

Effects

Models

NPCs

API

API

The simple form

One file per node

Mixing both

A folder with no declaration

YAML gotcha: conditions with braces

​The simple form

​One file per node

​Mixing both

​A folder with no declaration

​YAML gotcha: conditions with braces

The simple form

One file per node

Mixing both

A folder with no declaration

YAML gotcha: conditions with braces