> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nmentities.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Dialog Files

> Organize conversations: inline nodes, one file per node, folder conventions and the YAML brace gotcha.

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:

```yaml theme={null}
# 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:

```text theme={null}
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:

```yaml theme={null}
# 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:

1. A `dialog.yml` meta file in the folder, if it declares `start:`.
2. A `start.yml` node file.
3. 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**:

```yaml theme={null}
conditions:
- hasitem{item=diamond}
```

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

```yaml theme={null}
conditions: [hasitem{item=diamond}]   # ✗ breaks
```

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