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.

Assigning a dialog

Dialogs live in plugins/LodeEntities/Dialogs/. Point an NPC at one with its dialog field:

bob:
  type: npc
  base: villager
  ai: false
  dialog: bob_talk

Right-clicking Bob now starts the conversation. You can also set it from the Entities menu editor (Dialog). Dialogs reload with /le reload. A dialog doesn’t have to belong to an NPC: an addon can start one for any player, from an item, a region or a quest step. See NPCs & Dialogs.

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

Mobs

Spawning

Commands

Effects

Models

Compatibility

NPCs

Pets

Configuration

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