NPC Dialogs

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:

/npc dialog bob_talk

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

/npc dialog none

You can also set dialog: bob_talk directly in the NPC’s yaml. 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:

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

Here’s a complete one:

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.
`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: <player.name> for the talking player, <var.x> for 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:

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

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

Where to go

Dialog Conditions: every condition you can gate a node or choice on.
Dialog Files: organizing big conversations across multiple files.

Getting Started

Commands

Effects

Models

NPCs

API

API

Assigning a dialog

How a conversation is built

Node fields

Ending a conversation

Text and placeholders

Remembering things

Where to go

​Assigning a dialog

​How a conversation is built

​Node fields

​Ending a conversation

​Text and placeholders

​Remembering things

​Where to go

Assigning a dialog

How a conversation is built

Node fields

Ending a conversation

Text and placeholders

Remembering things

Where to go