> ## 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.

# NPC Dialogs

> Branching NPC conversations: assigning one, node structure, choices, effects and endings.

A dialog is a **branching conversation**: the NPC says something, the player picks a clickable reply, and the conversation moves on. Shopkeepers, quest givers, tutorial guides, lore characters. All of it in YAML, no code.

\[Image here: A player mid-conversation with an NPC, numbered clickable choices in chat]

## Assigning a dialog

Dialogs live in `plugins/NMEntities/Dialogs/`. Point an NPC at one:

```text theme={null}
/npc dialog bob_talk
```

Right-clicking that NPC now starts the conversation. Clear it with:

```text theme={null}
/npc dialog none
```

You can also set `dialog: bob_talk` directly in the NPC's [yaml](npc-files). Dialogs reload with `/nme reload`.

## How a conversation is built

A dialog is a set of **nodes**. Each node does up to three things, in order:

1. **Says** one or more lines.
2. Optionally **runs effect lines** (give items, run commands, set variables).
3. Either shows **choices**, or **continues automatically** to another node.

Here's a complete one:

```yaml theme={null}
bob_talk:
  start: [night_greet, greet]   # first entry whose conditions pass wins
  night_greet:
    conditions: [isnight]
    say: "&7*yawns* Come back in the morning."
  greet:
    say:
    - "&fWell hello, <player.name>!"
    - "&fWhat can I do for you?"
    choices:
    - text: "Who are you?"
      goto: who
    - text: "Want this diamond?"
      conditions:
      - hasitem{item=diamond}   # choice only shows when the player carries one
      goto: trade
    - text: "Bye."              # no goto = conversation ends
  who:
    say: "&fI'm Bob. Anything else?"
    goto: greet                 # loop back to the choices
    delay: 20                   # ticks before auto-continuing (default 30)
  trade:
    say: "&aOoh, shiny! Here, take these."
    effects:                    # caster = the NPC; lines without @targeter act on the player
    - command{c=clear <player.name> diamond 1}
    - command{c=give <player.name> emerald 3}
```

Read it top to bottom: at night Bob brushes you off, otherwise he greets you by name and offers up to three replies. The diamond option only appears if you're actually carrying one. "Who are you?" loops back to the same choices, and the trade node hands over emeralds.

## Node fields

| Field        | What it does                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `say`        | The line or lines the NPC speaks. A single string or a list.                                                        |
| `conditions` | Only enter this node if they pass. A single condition or a list. See [Dialog Conditions](dialog-conditions).        |
| `choices`    | Clickable replies. Each has `text`, an optional `goto`, and optional `conditions`.                                  |
| `goto`       | Continue automatically to another node. `goto: end` ends the conversation.                                          |
| `delay`      | Ticks before auto-continuing (default `30`). Accepts time units like `2s`.                                          |
| `effects`    | Effect lines to run when the node is entered. The NPC is the caster; lines without a `@targeter` act on the player. |

The `start:` key at the top of the dialog lists candidate entry nodes. The **first one whose conditions pass** becomes the opening, which is how the night greeting above wins after dark.

## Ending a conversation

A conversation ends when a node has no `goto` and no `choices`, when a chosen reply has no `goto`, or on `goto: end`. It also ends if the player walks more than 8 blocks away.

One conversation runs per player at a time, and re-clicking the NPC restarts it. Old choice menus stop working once you've answered or restarted, so stale clicks in the chat scrollback are simply ignored.

## Text and placeholders

`say` lines and choice text support legacy `&` colors and [placeholders](variables): `<player.name>` for the talking player, `<var.x>` for [variables](variables), and the rest of the usual set.

## Remembering things

Set variables in a node's `effects`, then check them in later `conditions`. That's persistent quest state across a conversation and between conversations:

```yaml theme={null}
  accept_quest:
    say: "&fBring me five emeralds and we'll talk."
    effects:
    - var{target.quest_stage=1}
```

```yaml theme={null}
  start: [quest_active, first_meeting]
  quest_active:
    conditions: [target.var.quest_stage >= 1]
    say: "&fBack already? Got those emeralds?"
```

## Where to go

* [Dialog Conditions](dialog-conditions): every condition you can gate a node or choice on.
* [Dialog Files](dialog-files): organizing big conversations across multiple files.