Branching talk with player choices that hand out items, take payment, and move quests.
NPC Conversations
A conversation is what an NPC actually does when a player talks to them. It is a set of nodes — each with text pages and player choices — and a choice can carry actions: hand over an item, take payment, set a flag, start a quest, teleport the player, open a shop. This is how you move a world's townspeople off event scripts and onto the NPCs themselves.
Everything here is authored in Database → NPCs → (your NPC) → Conversation.
Where it fits
- A node with pages and no choices is exactly the old Dialogue Variant — every NPC you have already written keeps working untouched, and opens in this editor as a one-node conversation.
- The NPC's standing services (Trade, Open Bank, Train, quest offers, Goodbye) are added automatically on the last page. You never author those.
- Choices are shown on a node's last page. Multi-page nodes play in order through "(Continue)" first.
- A node with no pages is a silent step: it runs and moves on by itself, and only stops when it has two or more choices to offer. See Steps with no text below.
- Every page can also direct portrait art over the window — who stands where, who is talking. See Dialogue Busts.
Build a conversation
1. Open Database → NPCs, pick an NPC, and scroll to the 🗨️ Conversation card. 2. Click + Add node. The first node you add can open a conversation; every node after it is created as a follow-up (Can open unticked) so it can only be reached from a choice. 3. Give the node a name (editor-only) and write its Pages. Each page is one screen of text; players advance with "(Continue)". 4. Add Conditions if this node should only play sometimes — "Quest is active", "Player silver ≥ 50", "Time of day is night". All conditions on a node must hold. 5. Click + Add choice and write what the player says. Pick where it leads under the dropdown: another node, ↩ Back to this NPC's menu, or ✖ End the conversation. 6. Open the choice's Details to add its own conditions, its actions, and the once-per-player and locked-display options. 7. Save. A broken conversation is refused with a message naming the node and the problem — a choice pointing at a deleted node, two choices sharing an id, an action missing its target.
The NPC reloads on the running server as soon as you save; a player already mid-conversation restarts it the next time they talk.
Which node plays
The first node that can open a conversation and whose conditions all match is the one shown. Order matters: put your most specific node (a quest is active, a flag is set) above the general one. If no node matches, the NPC falls back to its Greeting Text.
A node reached through a choice's next has its own conditions re-checked on arrival. If they no longer hold, the conversation falls back to the NPC's menu rather than dead-ending.
A node's conditions decide whether the player may arrive on it — they are not checked again while the player is there. Its choices stay clickable even when its On entering this node actions change what it was gated on (the Flag is OFF + Set flag ON pattern below). Every click still checks that the player is on that node, on its last page and near the NPC, plus the choice's own conditions and its once-per-player guard.
Steps with no text
A node with no pages is never drawn as an empty window. The server runs it and decides where the player goes next, every time the conversation arrives on it:
1. Its On entering this node actions run, as for any node. 2. If the player can take exactly one of its choices (its conditions hold and it isn't a spent Only once per player choice) and no greyed-out choice is on show, the server takes that choice for them — the same checks and the same actions as a click — and follows Leads to: the next node, the NPC's menu, or the end. A run of silent steps is passed through the same way, until the conversation reaches a node with text. 3. With two or more choices (or a greyed-out one on show), it stops: the choices are shown as a menu under the NPC's Greeting Text (or "Hello, traveler." if the greeting is blank). Nothing is picked for the player. 4. With no choice the player can take: if a choice led here, the conversation ends. If it is the conversation's opening node, the NPC answers as it would with no conversation — its Greeting Text and its services (Trade, Bank, quests).
A conversation that opens silently never hides the NPC's services. When talking starts on a silent step and the path ends before anything reached the screen — a converted page that only flips a self switch, say — the NPC answers with its Greeting Text and its standing offers whenever it has any: quests to take or hand in, Trade, Bank, Train, crafting stations, an instance to enter, the guild registrar, and so on. The silent actions have already run, and accepting a quest from that menu doesn't run them again. Nothing opens only when the NPC has nothing of its own to offer, or when the silent steps opened a shop or crafting station (the player is looking at that).
| What the silent step has | What the player sees |
|---|---|
| One choice they can take | Nothing — they land wherever it leads. |
| Two or more choices | A menu under the NPC's greeting. |
| No choice they can take, reached from a choice | The window closes. |
| No choice they can take, as the opening node | The NPC's greeting and services. |
| A silent opening that ends, on an NPC with services or quests | The NPC's greeting and services. |
| A silent opening that ends, on an NPC with nothing to offer | No window. |
This is how a gate works: a silent node with two opposite choices (Flag is ON → one node, Not · Flag is ON → another) sends every player straight to the text that fits, because only one of the two is ever open to them.
- A silent step's Take item / Take silver still refuses the whole step when the player can't pay. They are told why, and the conversation stops on that step: its choice is shown under the greeting, so they can take it once they can pay.
- Every silent step counts toward the 40-node loop cap. Two silent steps that lead to each other would never show anything, so they end with "That conversation has gone in circles." — and their actions run on every pass until then.
- Silent steps are range-checked like clicks. If one step teleports the player away from the NPC, the next step does not run and the NPC's windows close.
- Ending a conversation leaves its windows open. A silent step whose choice opens the shop (or a crafting station) and then ends the conversation closes only the conversation — the shop stays up. Walking away still closes everything.
Node fields
| Field | What it does |
|---|---|
| Name | Editor label only. Never shown to players. |
| Can open | Whether this node may be chosen as the conversation's opening node. Untick it for follow-ups so a node with no conditions can't steal the greeting. |
| Conditions | All must match for this node to play. None = always matches. |
| Pages | The text, in order. Supports \{playerName}\ and \{npcName}\. Leave it empty to make a silent step — see Steps with no text. |
| Choices | What the player can say, on the last page. |
| On entering this node | Actions that run once per conversation, the first time this node opens. Use it sparingly — a player sees it before they have chosen anything, and walking away and talking again is a new conversation, so it runs again. For once-ever, have it set a flag and give the node a Flag is OFF condition (its choices stay clickable — the node's conditions are only checked on arrival), or put the actions on a choice with Only once per player. |
Choice fields
| Field | What it does |
|---|---|
| Label | The button. Supports \{playerName}\ / \{npcName}\. |
| Leads to | Another node, Back to this NPC's menu (the greeting and its services), or End the conversation (closes the window). |
| Only once per player | The choice can be taken once, ever. See below. |
| Show greyed out when conditions fail | Off (default): the choice is hidden when its conditions fail. On: it is shown disabled with your reason — good for "You need 50 silver". |
| Conditions | All must match for the choice to be offered. |
| Actions | What the server does when the choice is taken, in order. |
Conditions
| Condition | What it checks |
|---|---|
| Quest is active | The player holds this quest and has not handed it in. |
| Quest is completed | The player has handed this quest in. |
| Quest not started | The player has never accepted it. |
| Flag / switch is ON / OFF | A numbered core-event switch, or a named flag a dialogue action set. One store — see Flags. |
| Player faction is | Exact faction name. |
| Player level ≥ | The player's level. |
| Player has item | How many of an item are in the bag (count 1 = "has any"). |
| Player silver ≥ | The player's silver. |
| Quest objective is | One objective of a quest: Complete, Not complete, or Count ≥ a number. |
| Time of day is | Tick every phase the line should play in. Conditions are AND-ed, so one row lists them all. |
| Skill level ≥ | A named skill's level. |
| Variable ≥ / Variable = | One of the player's own numbered variables — the same ones a core event's Control Variables writes. Pick it from the dropdown (only player variables are listed). |
Tick Not on a condition to invert it: Not · Quest is active holds while the quest is not in the log. A condition that can't be checked at all — an objective that no longer exists, a variable your project declares global — never holds, ticked or not.
Actions
Everything a choice does runs on the server. The client only reports which choice was clicked; the server re-derives the node, re-checks range and conditions, and runs the actions you authored — nothing the player's game sends can add, change or skip one.
| Action | What it does |
|---|---|
| Give item | Puts count of an item in the bag. |
| Take item | Takes count. If the player doesn't have them the whole choice fails and nothing runs. |
| Give silver | Adds silver. |
| Take silver | Takes silver. If they can't pay, the whole choice fails. |
| Set flag ON / Set flag OFF | Writes a per-player flag. |
| Set variable / Add to variable | Sets, or adds to (a negative amount subtracts), one of the player's own numbered variables. A variable your project declares with any other scope is skipped — a conversation never writes a world-global value. |
| Start quest | Same as accepting the quest from its offer — level, prerequisites and quest-log limits all still apply. |
| Advance quest objective | Moves one objective by amount. The only way to move Escort, Timer/Survival and Composite objectives. |
| Complete quest | Hands the quest in, rewards and all. Its objectives must already be done. |
| Teleport player | Moves the player to a tile, in this zone or another. Clamped to a walkable tile; if there is nothing walkable near your coordinates the teleport is skipped rather than dropping them in a wall. |
| Open shop | Opens this NPC's shop, or another authored shop you pick. The conversation ends there — see Shops and stations take over below. |
| Open crafting station | Opens one of this NPC's authored stations (0 = the first). The conversation ends there, as for Open shop. |
| Apply status effect | Applies an authored status effect to the player. |
| Play VFX | Plays a VFX definition on the player, for everyone nearby to see. |
| System message | A line in the player's chat log. |
Actions are all-or-nothing. Everything a choice takes is checked before anything is given, so a choice can never half-run and leave a player paid but empty-handed — or robbed and unpaid. When it fails the player is told why and the conversation stays exactly where it was, with the choice still there for when they can afford it.
Shops and stations take over
A shop or crafting station never opens beside the conversation. The moment one opens — from the NPC's own Show me your wares. or crafting option, or from a choice's Open shop / Open crafting station action (or an On entering this node one) — the conversation window closes and the shop is the only NPC window on screen. So:
- A choice's other actions still run (they happen together), but where it leads to is skipped: the conversation ends at the shop. Put anything the player should read before the choice that opens the shop.
- Closing the shop doesn't bring the conversation back. To talk again, the player talks to the NPC again — which closes an open shop.
- When the NPC's own Show me your wares. can't open the shop (closed for the night, too far away), the conversation stays where it was and the reason shows in chat. A choice's Open shop action ends the conversation either way — if the shop keeps hours, gate that choice on Time of day is so it only shows while the shop is open.
- Walking away from the NPC closes the shop, as it closes the conversation.
The once-per-player rule
Tick Only once per player on any choice that hands something out. Without it a choice that gives an item is farmable: walk away, talk again, take it again, forever.
- The choice is spent only after its actions actually ran — a choice the player could not afford is still waiting when they come back with the money.
- Once spent, the choice is hidden, not greyed out. It is gone, not locked.
- The guard is per player and permanent: it is stored as a flag named \
dlg1:<npc>:<node>:<choice>\in the same place every other flag lives, so it persists with the character and survives a server restart. - It is keyed by the NPC definition, so every copy of that NPC in the world shares one answer.
- You can read it yourself: a Flag / switch is ON condition on \
dlg1:<npc id>:<node id>:<choice id>\answers "have they already taken this?".
Flags: one store, not two
Dialogue flags and core-event switches are the same per-player store. That means:
- A flag a conversation sets can be read by a core event's conditional, and vice versa.
- A whole number flag (\
17\) is that numbered core-event switch. Anything else (\met_the_elder\) is a named flag of your own. - A flag written
ss:<zone id>:<event id>:<A–F>is that map event's own self switch for the player — the very value the event's pages check. Conversations converted from events use it, so a player who already finished an event keeps their progress. See Converting Events to Conversations. - Flags are per player and persist with the character.
Gotchas
- A map event bound to this NPC takes the whole conversation. If you have placed an event on the map and set its NPC binding, that event runs instead and this window never opens. Unbind the event to use the NPC's own conversation. (The same is true of a generated NPC whose template names a "talk" common event.)
- Choices only appear on the last page. A three-page node shows "(Continue)" twice, then the choices.
- A node with no pages never waits for a click. Its one open choice is taken for the player. To make them press a button, give the node a line of text.
- A loop is allowed, but it is capped. "Ask again" chains are legitimate content, so a conversation may cycle — but one conversation may enter at most 40 nodes before the server closes it with "That conversation has gone in circles." If players see that line, a choice chain has no exit.
- Order is everything in node selection. A node with no conditions, placed above a conditional one, always wins. Untick Can open on follow-ups.
- Teleport is clamped. The tile you type is a guess at the map; the server lands the player on the nearest walkable tile, or skips the teleport entirely if there isn't one.
- No feature flag. Conversations are part of the core dialogue system and are always on. Individual actions still respect their own systems' flags — Open crafting station does nothing with \
crafting\off, and an authored shop needs \npcShops\.
Authoring with AI
The \npc-dialogue-author\ tool writes this same model. Pass a \conversation\ array of the exact node shape above and it is validated against the identical rules the editor uses; pass the simpler \nodes\ form (id, text, labelled options) and it is converted for you. Either way the result lands on the NPC's Conversation, not on the legacy dialogue tree.