Dialogue Tree Editor

Overview

Drafft's Dialogue Tree Editor provides a powerful and flexible way to design branching dialogues for games. With a cleaner UI, improved node management, and deep integration with scripts, it allows for intuitive and efficient dialogue creation.

Features

Intuitive Design

• A redesigned interface with better node management for a streamlined workflow.
• Support for Vertical and Horizontal layouts.
• Scripts can be loaded into sub-tabs within the dialogue editor.

Flexible Node System

• Any node can have multiple input and output ports.
• Context menu for quick actions: Edit, Delete, Clone.
• A configuration drawer for managing node attributes (inputs, outputs, title, metadata).

Script Integration

• Nodes can link to any script in the project, whether autogenerated by the dialogue editor or user-created.
• Shared scripts allow for reuse across multiple dialogues or nodes.
• Editing scripts outside the dialogue editor reflects changes instantly.
• To prevent conflicts, scripts must be locked before editing.(Future update may include an "Auto-lock related scripts" option).
• Adding scripts to dialogue nodes is optional.

Advanced Editing Tools

• Grid snapping for precise node alignment.
• Duplicate nodes to speed up development.
• Undo/Redo support for risk-free experimentation.

tip

You can shift-click to select multiple nodes at once.

Node Types

• Jump: Jump to a specific node.
• Note: Add sticky notes for annotations.
• Script: Embed scripts directly in dialogues.
• Choice: Create branching paths with multiple options.
• Condition: Branch dialogue based on a single boolean expression (true/false).
• Switch: Branch dialogue based on an expression matching multiple case values.
• Start: Define the beginning of a dialogue.
• End: Mark the conclusion of a dialogue.
• Return: Return to the previous choice point.

Output Port Scripts

Each output port (handle) on a dialogue node can include @set directives that execute when a user follows that port. This allows you to track user choices and set variables without creating separate script nodes.

Example Use Case:

Choice Node with 3 outputs:
├─ "Approach Cautiously" → @set variables.approach = "cautious"
├─ "Walk Forward Openly" → @set variables.approach = "bold"
└─ "Observe From Distance" → @set variables.approach = "observant"

All outputs lead to the same Response Node, which reads variables.approach
and responds differently based on the player's choice.

How to Use:

1. Edit a node and expand an output port
2. Enter @set directives (one per line)
3. When the user picks that output, the directives execute automatically
4. A yellow @ badge indicates ports with scripts

Features:

• Supports multiple @set directives per output
• Only @set syntax is processed; other lines are ignored
• Variables update before the next node's script runs
• Error handling logs issues without blocking navigation

Condition and Switch Nodes

Condition and Switch nodes enable powerful dialogue branching based on game state using UAF expressions. They evaluate variables in real-time and automatically route the dialogue to the appropriate path.

Condition Nodes

A Condition node evaluates a boolean expression and branches into exactly two paths: True and False.

Use Case: Check a single variable condition to determine dialogue direction.

Example: If player level >= 10
├─ True  → "Wow, you're quite experienced!"
└─ False → "You're still learning, aren't you?"

How to Use:

1. Create a Condition node in the dialogue editor
2. Edit the node and enter a UAF expression (e.g., variables.player.level >= 10)
3. Connect two output ports: one for True, one for False
4. Optional: Attach a script to the node for dialogue content
5. If no script is attached, the dialogue will auto-advance when Game Simulation is ON

Properties:

• Expression: Any valid UAF boolean comparison (e.g., variables.health > 50)
• True Output: Path taken when expression evaluates to true
• False Output: Path taken when expression evaluates to false
• Script: Optional dialogue content to display before branching

Switch Nodes

A Switch node evaluates an expression and matches it against multiple case values, allowing complex multi-path branching.

Use Case: Route dialogue based on player choice or state matching multiple possible values.

Example: Check player.status
├─ "happy"    → "Great to see you smiling!"
├─ "angry"    → "You seem upset..."
├─ "tired"    → "You look exhausted."
└─ Default    → "How are you feeling today?"

How to Use:

1. Create a Switch node in the dialogue editor
2. Edit the node and enter a switch expression (e.g., variables.player.status)
3. Add case values that the expression might match
4. Connect output ports for each case plus a Default output
5. Optional: Attach a script to the node for dialogue content
6. If no script is attached, the dialogue will auto-advance when Game Simulation is ON

Properties:

• Switch Expression: Expression to evaluate (e.g., variables.player.status)
• Cases: List of possible values to match against
• Default Output: Fallback path if no cases match
• Script: Optional dialogue content to display before branching

Game Simulation Mode

When Game Simulation is enabled in the dialogue player:

• Condition and Switch nodes automatically evaluate and take the appropriate path without user interaction
• Scriptless nodes auto-advance to the next dialogue
• Only speech lines are displayed (non-speech content is hidden)
• Perfect for testing dialogue flow with variable conditions

When Game Simulation is disabled:

• Nodes behave like manual exploration
• You can navigate backward to explore different branches
• Useful for reviewing all possible dialogue paths during development

Scripting on Condition/Switch Nodes

Condition and Switch nodes support optional scripts for dialogue content:

• The script runs before branching occurs
• You can use @set directives to track player interactions
• Control-flow blocks (@if/@else/@endif) work normally
• If the script has @set lines at the start, they execute when the node is reached

Example with Script:

@set variables.branch_taken = "condition"
Let me think about this for a moment...

When this node is reached, the @set line executes, then the dialogue displays, then the condition branches based on the expression.

Learn more about UAF scripting

tip

Condition and Switch nodes are evaluated using the Live Scenario state, allowing real-time interaction with game variables. ScriptPlayer shows detailed information about expression evaluation in the Meta Box.

Dialogue Output Schema

The dialogue system generates structured JSON output that represents the entire dialogue tree. Here's an overview of the schema structure:

Root Properties

• name: String - The name of the dialogue
• type: String - Usually "Dialogue"
• parent: String - ID of the parent element
• icon: String - Icon identifier
• color: String - Color code in hexadecimal
• path: String - Path to the dialogue
• collection: String - Collection type, typically "Dialogue"
• Various metadata fields like created, modified, locked, etc.

Content Structure

The dialogue content is organized in a tree structure under content.tree with two main components:

Nodes

Each node represents a point in the dialogue flow and includes:

• id: Unique identifier
• position: X and Y coordinates in the editor
• type: Node type (typically "base")
• data: Contains node-specific information:
  • label: Display name (e.g., "1 - Start")
  • handles: Connection points for edges
  • nodeType: Type of node ("start", "script", "choice", "end", etc.)
  • scriptId: Reference to associated script content

Jump Node

A Jump node redirects dialogue flow to another node without branching.

Properties:

• id: Unique identifier
• position: X and Y coordinates in the editor
• type: Node type (typically "base")
• data: Contains node-specific information:
  • label: Display name (e.g., "Jump to Start")
  • nodeType: "jump"
  • targetNodeId: ID of the node to jump to
  • handles: Input and output connection points

Key Properties:

• nodeType: "jump"
• targetNodeId: ID of the node to jump to
• Single input and output handle (no branching)

Choice Node

A Choice node presents multiple options to the user, each leading to a different path.

Properties:

• id: Unique identifier
• position: X and Y coordinates in the editor
• type: Node type (typically "base")
• data: Contains node-specific information:
  • label: Display name (e.g., "What do you do?")
  • nodeType: "choice"
  • scriptId: Optional reference to dialogue content script
  • handles: Input handle plus one output handle per choice option

Key Properties:

• nodeType: "choice"
• scriptId: Optional reference to dialogue content script
• Multiple output handles (one per choice option)
• Each output can have port scripts with @set directives

Condition Node

A Condition node evaluates a boolean expression and branches into True/False paths.

Properties:

• id: Unique identifier
• position: X and Y coordinates in the editor
• type: Node type (typically "base")
• data: Contains node-specific information:
  • label: Display name (e.g., "Check Level")
  • nodeType: "condition"
  • expression: Valid UAF boolean expression (evaluated at runtime)
  • scriptId: Optional reference to dialogue content script
  • handles: One input handle plus True and False output handles

Key Properties:

• nodeType: "condition"
• expression: Valid UAF boolean expression (evaluated at runtime)
• scriptId: Optional reference to dialogue content script
• Exactly 2 output handles: one for True, one for False
• Uses Live Scenario state for variable evaluation

Edges

Edges define connections between nodes:

• edgeId/id/key: Unique identifier
• source/target: IDs of connected nodes
• sourceHandle/targetHandle: IDs of specific connection points
• points: Array of coordinate points defining the edge path
• Visual properties like width, color, curvyness

Learn More

For a detailed breakdown of how to use the Dialogue Tree Editor, check out our blog post: Easier Ways to Write Game Dialogue.