Authoring Editors

The Dialogue system provides two editing modes for authoring conversation content. Both operate on the same underlying data and can be used interchangeably.

The Flowchart Editor

Open the flowchart editor at BardTreeLtd/Dialogue/Dialogue Editor.

This is a visual node-graph editor where you create and connect dialogue nodes by dragging. It is best for:

• visualising conversation flow and branching
• understanding the structure of complex trees at a glance
• working with requirements on connections
• quick prototyping with drag-and-drop

Basic usage

• Create nodes -- right-click the canvas to add Chat, Start, Reference, or End nodes
• Connect nodes -- drag from a node's output port to another node's input
• Pan and zoom -- middle-click drag to pan, scroll to zoom (0.25x to 2.0x)
• Select multiple -- drag a selection rectangle or Ctrl+click individual nodes
• Delete -- select nodes and press Delete
• Auto-layout -- right-click the canvas and choose Auto Layout to arrange nodes in a readable flow

Node types in the graph

Node	Colour/Shape	Purpose
Start	Entry marker	The single entry point of the tree
Chat	Standard	Contains beat groups with dialogue content
Reference	Link marker	Points to another tree (jump, call, or return)
End	Terminal	Closes the conversation path

Diagnostics

The editor validates your graph in real time and shows warnings when:

• no Start node exists
• dead-end nodes have no outgoing connections
• reference nodes point to missing assets

The Script Editor

The Script Editor is a text-based authoring mode that uses a Markdown-like format. It is best for:

• writing large amounts of dialogue content quickly
• batch-editing multiple nodes at once
• reviewing conversation flow as readable text

Opening the Script Editor

Open it from the Dialogue Editor toolbar or through BardTreeLtd/Dialogue/Dialogue Script Editor.

Format overview

Dialogue scripts use a custom Markdown dialect. A complete example:

markdown

# Dialogue: Blacksmith Introduction

> start: greeting

## Greeting \{#greeting}

Good morning! What brings you to my forge?

> speaker-role: value=0
> progression:group-1: wait-for-line=true

- [I need a sword](#sword-request)
- [Just looking](#browsing)
  > option-effect: scope=Conversation; key=browsing; op=set; type=Bool; value=true

## Sword Request \{#sword-request}

I can forge you a fine blade. It'll cost you {bb.sword_price} gold.

> speaker-role: value=0
> beat:group-1:mood=proud

- [I'll take it](#purchase)
  > option: requirements=preserved
- [Too expensive](#farewell)

## Browsing \{#browsing}

Take your time. Let me know if anything catches your eye.

> speaker-role: value=0

## Purchase \{#purchase}

Excellent choice! Come back tomorrow to collect it.

> speaker-role: value=0
> node-effect: scope=Agent; key=sword_ordered; op=set; type=Bool; value=true
> node: type=end

## Farewell \{#farewell}

Come back when you have the coin, then.

> speaker-role: value=0
> node: type=end

Syntax reference

Element	Meaning
# Dialogue: Name	Document header (the tree's display name)
> start: alias	Declares which node is the entry point
## Heading {#alias}	A dialogue node with a stable alias
Body text	Becomes the primary text beat of the first beat group
- [Text](#alias)	An outgoing connection (dialogue option)
> node: type=X	Node type: start, chat, reference, or end
> speaker-role: value=N	Which participant speaks (0=A, 1=B, etc.)
> beat:group-N:key=value	Additional beat data (mood, animation, audio)
> progression:group-N: key=value	Timing controls (wait-for-line, auto-progress, time-limit)
> option: hidden=true	Hides a connection from player choices
> option: requirements=preserved	Marks that requirement conditions exist on this connection
> option-effect: ...	Blackboard effect when this option is chosen
> node-effect: ...	Blackboard effect when this node is entered
> response-beat:group-N:key=value	Beat that plays when a specific option is chosen
> reference: mode=call	Reference node mode: call, return, or self
> reference: tree=AssetName	Target tree for reference nodes

Blackboard effect syntax

Effects use semicolon-separated key=value pairs:

scope=Agent; key=quest_started; op=set; type=Bool; value=true
scope=Conversation; key=counter; op=increment; value=1
scope=Agent; key=old_flag; op=remove

• Operations: set, increment, remove
• Types: Bool, Int, Float, String
• Scopes: Conversation, Agent

Token syntax in text

You can use token interpolation directly in dialogue text:

markdown

## Greeting

Hello, {other.name}! Welcome to {speaker.name}'s shop.

Editor features

• Undo/Redo -- full history tracking
• Autocomplete -- context-aware suggestions for directives, beat types, node aliases, and token keys
• Real-time validation -- errors and warnings appear in the line gutter
• Click-to-navigate -- click a connection link (#alias) to jump to that node's heading
• Session persistence -- unsaved state is preserved across editor reloads

Validation

The script editor validates your content continuously. Common diagnostics include:

• unresolved link targets (a #alias that does not match any heading)
• dead-end chat nodes with no outgoing connections
• malformed directives (invalid keys, missing required fields)
• reference node conflicts (cannot have both self and tree mode)

Switching between editors

Both editors read and write the same ChatTreeData asset. You can:

1. create a tree in the flowchart editor
2. open it in the script editor to write dialogue quickly
3. switch back to the flowchart editor to verify the visual flow

Node identity is preserved through GUIDs and aliases, so switching does not lose data.

Practical advice

• Use the flowchart editor when designing conversation structure (what connects to what)
• Use the script editor when writing dialogue content (what characters actually say)
• Give nodes explicit {#alias} names in scripts -- this makes links readable and prevents breakage when nodes are reordered
• Start with the flowchart editor to get comfortable with the data model, then try the script editor once you want to write content faster