Dialogue Tree Editor

Every shop runs on a dialogue tree. The tree decides what the shopkeeper says, which choices the player sees, when the shelf opens, and how a visit ends. The archetypes ship with finished trees, and this editor is how you change them or write your own.

Where trees live

Trees are stored on journal entry pages. Opening a tree page shows an Edit dialogue tree button that launches the editor. In the Journal directory, a New dialogue tree button creates a fresh page and opens it for editing. Both buttons appear only on your client. A shop points at its tree from shop settings, so several shops can share one tree.

The editor

The editor lists every node as a row that expands into its full detail. It has a Nodes tab, an Overview tab, and a Help tab with a reference for the node types. Shift-click selects multiple rows, and right-clicking a row offers copy, copy sub-tree, duplicate, paste, and delete. Note that nothing is written to the page until you press Save Configuration. The editor is inert while a vignette is open on your client.

Overview tab

The Overview tab picks the entry node, the node a visit starts at, from a dropdown of every node in the tree. It also sets what happens when a buyer tries to enter the shop outside its opening hours: post a message, redirect to another node, or let them in anyway. Author, target systems, and tags are free-text metadata for the tree. The tab lists the tree’s validation errors and warnings, each with a jump-to-node link.

Node types

A tree is a set of nodes joined by choices. A visit starts at the entry node and follows choices until it reaches an End node. There are eight node types.

• Dialogue speaks lines to the player and presents each choice as a button. Individual lines can carry conditions. A Dialogue node either speaks every line that passes its condition or draws one of them at random.
• Browse opens the shelf with a filtered slice of the shop’s stock and the cart. A mode setting picks whether the node shows buying or selling. It requires a query, a checkout choice, and a leave choice. Item path and value suggestions in the query builder are sampled from the shop’s tradable items.
• Inventory asks the player to pick one of their own items and stores it in a named variable for later nodes. An item filter narrows what it accepts. It requires a picked choice and a leave choice.
• Transaction commits the cart, moving items and currency, then branches by outcome. It requires a choice for the cancelled outcome.
• RollTable rolls a Foundry roll table, stores the result in a variable, and branches on conditions against the roll.
• Auto branches silently on conditions without showing the player anything. Auto and RollTable nodes each require one unconditional choice as the fallback.
• Goto jumps to another node, or to another tree by its page UUID.
• End closes the visit and can run a final batch of effects.

Dialogue lines

The Lines header on a Dialogue node carries a picker with two modes. Speak Every Line plays each line whose condition passes, in order. Speak One at Random filters the pool by condition first, then draws a single line from what is left, avoiding the line drawn on the previous visit. The drawn line is held for the rest of that visit; a resumed session hears the same line. A node set to draw at random is replayable, so a return visit draws again instead of falling back to the revisit line.

Choices

A choice carries its button text, a target node, an optional cost, a Show when condition, and a When chosen effect list. Conditions and effects are built from rows in a builder, grouped with AND, OR, and NOT.

Conditions draw from a registry of predicates. They can test the buyer’s wealth, level, attributes, and owned items, shop and world flags and counters, the time of day and season, the last roll result, and the shop’s transaction log, including what a buyer bought before and how often they have visited. One predicate reports whether the shop has travel fares available. The stable and caravan trees use it to hide their passage choice when no destinations are set. Effects can set flags and counters, adjust price modifiers, adjust a numeric field on the buyer’s actor, grant an Active Effect, move currency and items, advance world time, request a travel fare, play a sound, post a chat message, fire a hook, or run a Foundry macro. Macro conditions and macro effects are restricted to you.

Other modules can add their own conditions, effects, and item filters to these lists through the module API.

A choice on a Dialogue node can instead accept free-text input. The player types a word, keywords route matching input to other choices, and a fallback choice catches everything else.

Inventory and Transaction nodes can grant an Active Effect when they complete, applied to either the chosen item or the customer. Service shops use this to sell blessings and repairs. A choice can also grant an Active Effect from its effect list. The actor-field effect takes a field path and an amount, and never drops the field below zero. Drag an Active Effect into the grant field or paste its UUID. The archetypes install their reference effects into a world compendium created on demand, described in System adapters.

Browse nodes can carry a flavor pool. The shopkeeper draws from it as items move in and out of the cart, surfacing as speech bubbles in the vignette.

Validation

The editor validates the tree and lists problems with a jump-to-node link. The footer carries a status badge. A valid tree reads as valid, and a tree with problems shows an issue count badge, plus a separate warning count badge when warnings exist. Hovering a count badge lists the messages, each named by the node it belongs to, and a long list is trimmed with a row counting the rest. Clicking a count badge focuses the first node the badge covers.

Errors cover structural breaks such as missing required choices, dangling targets, and free-text choices outside a Dialogue node. Warnings flag unreachable nodes, cycles between Auto and RollTable nodes, a random line pick set on a node that is not a Dialogue node, and references to unregistered predicates, effects, or filters.

The graph

The Graph button opens a read-only map of the tree. It pans, zooms, and redraws live as you edit. Clicking a node in the graph focuses that node’s row in the editor.