Dialog Editor#

The Dialog Editor builds conversation trees — the NPC lines and player choices that drive a TALK interaction. A dialog is a set of nodes, each with an NPC line and a list of choices; picking a choice can jump to another node, end the conversation, gate itself behind a flag, or fire effect tokens. It saves to the project's dialogs.json, keyed by the dialog's own id.

You reach it from the Hub (dev server running). The TREE panel on the left lists every node in the loaded dialog; the center panel opens in the ◇ Visual graph of the whole tree by default and toggles to the single-node ✎ Advanced form; the right panel holds VALIDATE and PREVIEW.

Anatomy of a node#

• Node ID — the node's key inside the tree, shown as the section title. It's what goto targets reference, so renaming a node (via the tree panel's rename action) rewrites every choice that points at it — the editor keeps those in sync for you. Renaming a node (or retyping a Choice ID) also carries the saved translations of its line and every choice under it to the new address. If that address already holds translations — usually an orphan left by something deleted — the editor shows you the parked text, locale by locale, and asks whether to use it (your own source-language wording still wins) or discard it; cancelling changes nothing. One case doesn't stop to ask: a choice still wearing its placeholder id gets slugged automatically as you type its text, so the move happens mid-sentence. There the editor keeps what you typed and tells you the old address held on to its translations, rather than interrupting an edit you were in the middle of.
• NPC line — the line the NPC speaks when this node is current. It's authored monolingually in the project's defaultLocale (content i18n): you type it once, in one language, and translations are filled later in the Translation Editor, not inline here.
• Start node — one node per dialog is the entry point (tree.start); the tree panel marks it with a badge, and any node can be promoted with the ★ action.

Choices#

Each node holds an ordered list of choice cards, reorderable with ↑ / ↓:

• Choice ID — a stable key for the choice, auto-slugged from its text the first time you type it (edit it directly to override). It's what the once-seen bookkeeping and the validator's duplicate check key off of.
• Text — the player-facing line, same monolingual-authoring rule as the NPC line.
• Goto — the node this choice leads to, or END to close the conversation. Leaving it blank is only valid on an END-equivalent choice — the validator flags a goto pointing at a node that no longer exists.
• showIf / hideIf — flag names that gate the choice's visibility at preview/runtime — showIf requires the flag to be set, hideIf hides it once the flag is set. The autocomplete offers three sources at once: every flag the project already uses anywhere (the same server-side scan the effect editor's flag pickers read), the flags typed into this dialog but not saved yet, and the reserved engine flags — names the engine maintains itself, like the live party size, which no project scan can find and you would otherwise have to know by heart. It stays free text on purpose: a flag is created by being written, so a name nobody has used yet has to be typeable.
• once — hides the choice again after it's been picked the first time (per dialog, tracked internally as a seen-flag).
• Effects — the shared effect-token widget (same one used across rules and cutscenes), with every ID-bearing argument (room, item, flag, hotspot…) as a typed picker rather than free text. These run through applyEffects() when the choice is picked, so SETFLAG, GIVEITEM:<item>|<char>, SAY, and every other token behave exactly as they do in a rule or cutscene. Each token carries a ⠿ grip on the left: drag it to reorder the chain, and drop it into or out of an if-block — a token can move from the main list into a THEN branch, or back out, without retyping it. (The grips live in the ✎ Advanced view; the Visual view shows the graph, not the node form.)

Visual view (the default)#

The center panel opens in ◇ Visual, an interactive map of the whole conversation, and toggles to the classic single-node form with ✎ Advanced. Visual is where you'll usually work: every node is a card, every choice a cable to the node it leads to, so you see the shape of a dialog — its branches, dead ends, and loops — and edit it in the same place.

The map reads by colour and line:

• The start node is green (the conversation's single entry point) and the END sink is red (where every closing choice lands). Ordinary nodes are neutral, each labelled with its id, its NPC line, and how many choices it holds.
• A conditional choice — one gated by showIf or hideIf — draws its cable dashed amber instead of a solid line, so the branches that only open under the right flag stand out from the ones always on offer.
• A once choice is prefixed 1× on its label; a choice that points back at its own node (a self-loop) is listed as a ↩ annotation under the node rather than a cable curling back on itself.

It's a working surface, not just a picture:

• A palette across the top adds pieces in the order you build a dialog — START (mark the selected node as the entry point), NODE (a new NPC line), CHOICE and END (add a choice, or a conversation-closing choice, to the selected node), and ADV. (flip to the Advanced form).
• Each card's NPC line is editable in place — click the speech bubble and type, no modal needed.
• Drag a card's ○ connect port onto another node to wire a choice's goto by hand.
• Double-click a card, or click its ✎, opens the full node form in a modal — the same editor the Advanced view mounts, so every field (choice text, showIf/hideIf, once, effects) is there without leaving the graph.

Navigation is the usual graph handling: scroll to zoom, drag the background to pan, drag a node to reposition it; your layout is remembered per dialog, and ⊡ Reset view clears those tweaks and re-runs the automatic top-to-bottom layout.

VALIDATE tab#

Runs on every edit and blocks Save to Game while errors remain. It checks: the tree has an id and a start node, the start node exists, every node is reachable from start (a graph walk over gotos), every choice has a non-empty unique id and non-empty text, and every goto points at a real node or END. It also warns (non-blocking) when a flag is set by SETFLAG/CLEARFLAG somewhere in the tree but never read by any showIf/hideIf — usually a sign the flag is meant to be read elsewhere (a room rule, another dialog) rather than a mistake.

PREVIEW tab#

Runs the real dialog runtime (core/dialog.js — openDialog/visibleChoices/choose) against a scratch, in-editor game state, so what you click behaves exactly like it will in-game: showIf/hideIf filtering, once bookkeeping, and node transitions all go through the same functions the shipped engine calls. The flags row lets you toggle any flag the tree references (or add an arbitrary one) to walk different branches; ES/EN switches which language the preview renders in; ↺ Restart resets the conversation to its start node. The ENGINE EFFECTS LOG at the bottom lists every effect token a chosen choice fired, in order — it doesn't execute them (there's no live room to affect), but it's the fastest way to confirm a choice fires the tokens you expect before wiring it into the game.

Workflow#

1. New… and give the dialog a stable id; a root node is created for you as the start.
2. Write the NPC line, then + Add Choice for each player response.
3. Set each choice's text, goto (or END), and any showIf/hideIf gating.
4. Add effects through the shared widget for anything the choice should do beyond moving the conversation forward.
5. Add more nodes from the tree panel and link them up with goto; check VALIDATE stays clean as you go.
6. Walk the tree in PREVIEW, toggling flags to exercise every branch.
7. ⚡ Save to Game to write dialogs.json.

Dialog text is monolingual; translations live in the Translation Editor. The NPC line and every choice's text are authored once, in the project's defaultLocale — there's no ES/EN pair to fill in here. Each line gets a stable lid behind the scenes (dialogVoiceLid/dialogChoiceLid) the moment you save, and that's the row the Translation Editor's Diálogos section fills in for every other configured locale. Don't hand-author a {es, en} object in a choice's text — the editor already writes the monolingual literal plus the lid slot for you.

Deleting a node or a choice now offers to take its rows with it. The ask comes when you press Save, not when you press the ✕ — until then the node is only gone from the screen. A deleted node carries its choices' rows along with it in the same question, since nothing can reach them either. The dialog shows the text of every row in every language it holds, and dismissing it means keep: a parked row is what lets a re-created node adopt its old translations, and the Project Doctor can sweep it later if it never comes back.