Dialogue Graph Editor

Cloud commercial feature. The dialogue graph editor is available on paid StudioBrain plans (Indie+). In the free core edition, dialogue trees are managed through the list-based node CRUD interface.

The Dialogue Graph Editor provides a visual, node-based interface for creating and managing branching dialogue trees. It uses a ReactFlow-powered canvas where each node represents a piece of dialogue and edges represent the flow between nodes.

Accessing the Editor

Navigate to Dialogue Trees in the sidebar, then click on a dialogue entity to open its graph editor. The URL is /dialogue/{entityId}.

The Canvas

The editor renders an interactive graph canvas with:

Pan and zoom — scroll to zoom, drag to pan
Mini-map — overview of the full graph in the top-right corner (nodes are color-coded by type)
Dot grid background — visual reference for node placement
Controls panel — zoom in/out, fit view, and lock pan buttons

Node Types

Each node in the graph represents a step in the conversation. There are five node types, each with a distinct color:

Type	Color	Purpose
Dialogue	Blue	Character speaks a line of dialogue
Choice	Green	Player selects from multiple options
Action	Purple	An action is triggered (e.g., play animation, set flag)
Condition	Amber	Branch based on a game state condition
Ending	Red	Terminal node — ends the conversation

Node Fields

Each dialogue node has the following fields:

Field	Type	Description
Node ID	Text	Unique identifier for the node (e.g., `intro_greeting`)
Type	Dropdown	One of the five node types above
Speaker	Text	Character name who is speaking
Emotion	Dropdown	neutral, happy, sad, angry, surprised, fearful, disgusted
Dialogue Text	Textarea	The spoken line
Condition	Text (optional)	Condition expression (e.g., `has_item(sword)`)
Entry Node	Checkbox	Marks this node as the dialogue entry point (exactly one required)
Loop Marker	Checkbox	Suppresses cycle detection warnings for intentional loops

Player Choices

Dialogue nodes can contain choices — branching options presented to the player. Each choice has:

Field	Description
Choice text	What the player sees
Target node ID	Which node to jump to when selected
Condition (optional)	Condition that must be true for this choice to appear

Adding Nodes

Click Add Node in the toolbar to open the node creation form. Fill in the required fields (Node ID and text) and optionally set the type, speaker, and emotion. The new node appears on the canvas at a random position — drag it into place or use Layout to auto-arrange.

Connecting Nodes

To create a flow between nodes:

Hover over the bottom handle (source) of a node
Click and drag to the top handle (target) of another node
A smooth animated edge with an arrow appears

You can also connect nodes by setting the Target node ID in a choice — the editor will create the corresponding edge.

Editing Nodes

Double-click any node to open the edit modal. All fields are editable here, including the full choice list. Changes are applied immediately to the canvas but are not saved to the backend until you click Save.

Auto-Layout

Click Layout in the toolbar to run the dagre auto-layout algorithm. This arranges all nodes in a clean top-to-bottom hierarchy, minimizing edge crossings. The layout is applied to the canvas and will be saved with your graph.

Validation

Click Validate in the toolbar to check the graph for errors and warnings. The validation panel appears at the bottom-right with results:

Errors (block save)

Check	Description
No entry node	Every dialogue must have exactly one entry node
Multiple entry nodes	Only one node can be marked as Entry
Orphan nodes	Nodes with no incoming edge that are not the entry node
Dangling edges	Edges that reference non-existent source or target nodes

Warnings (save allowed)

Check	Description
Cycle detected	A back-edge cycle was found. Mark affected nodes as Loop Marker if the cycle is intentional.

The Save button is hard-blocked when any error exists. Warnings pass through and save succeeds.

Keyboard Shortcuts

Shortcut	Action
Del / Backspace	Delete selected nodes and edges (only when not typing in an input)
Ctrl+S	Save the graph to the backend (validates first)
Shift+drag	Multi-select nodes

Dirty Guard

The editor tracks whether your graph has unsaved changes. An Unsaved badge appears in the toolbar when the graph is dirty.

Page unload: A browser confirmation dialog appears if you try to close the tab with unsaved changes
In-app navigation: A confirmation dialog appears when navigating away (e.g., clicking the back button)

Saving

Click Save in the toolbar or press Ctrl+S. The editor:

Runs validation on the current graph
If errors exist, shows the validation panel and blocks the save
If valid (or only warnings), saves nodes and edges to the entity’s fields.dialogue via the entity API
Clears the dirty flag and shows a success toast

From left to right:

Button	Action
← Back	Return to the dialogue list
Add Node	Open the node creation form
Delete	Remove selected nodes and edges (or press Del)
Layout	Auto-arrange all nodes with dagre
Validate	Run graph validation
Save	Persist changes to the backend (or press Ctrl+S)

Data Storage

The dialogue graph is stored as part of the entity’s fields object:

{
  "fields": {
    "dialogue": {
      "nodes": [
        {
          "node_id": "intro_greeting",
          "speaker": "Narrator",
          "text": "Welcome to the city.",
          "emotion": "neutral",
          "node_type": "dialogue",
          "choices": [
            { "id": "c1", "text": "Tell me more", "next_node_id": "intro_details" }
          ],
          "is_entry": true,
          "position_x": 100,
          "position_y": 50
        }
      ],
      "edges": [
        { "id": "e1", "source": "intro_greeting", "target": "intro_details" }
      ]
    }
  }
}