Connecting Nodes

Connections are the links between nodes that define how your story flows. Learn how to create, manage, and organize connections to build complex interactive narratives.

Overview

Connections are the essence of StoryFlow Editor's visual scripting system (also referred to as the node editor). By connecting nodes together, you create the logic and flow of your interactive story without writing any code. Connections determine how execution moves from node to node and how data values are passed between them, creating the narrative paths your players will follow.

Types of Connections:

• Execution Flow (Primary): White connections that determine the order nodes execute in
• Boolean Data: Yellow connections that pass true/false values between nodes
• Integer Data: Cyan connections that pass whole number values between nodes
• Float Data: Lime green connections that pass decimal number values between nodes
• String Data: Pink/Magenta connections that pass text values between nodes
• Enum Data: Teal connections that pass enum values between nodes
• Asset References: Specialized connections for Image (emerald), Character (violet), and Audio (amber) assets

Creating Connections

Creating connections in StoryFlow Editor is intuitive with a simple drag-and-drop interface.

Basic Connection Steps:

1. Locate the output handle on the source node (usually on the right side)
2. Click and hold on the output handle
3. Drag your mouse toward the target node
4. The connection line follows your cursor as you drag
5. Hover over the target node - it will highlight to show it can accept the connection
6. Release the mouse button to create the connection

Quick Node Creation with Auto-Connect:

You can quickly create and connect nodes in one action using edge drop auto-connect:

1. Start dragging from an input or output handle
2. Drop the connection on empty canvas space (instead of an existing node)
3. A pending connection line appears, showing where the connection will attach
4. The context menu opens where you can select a node type
5. The new node is automatically connected to your pending connection

Example: Connecting Dialogue Options

1. Add a Dialogue node with two options: "Accept Quest" and "Decline Quest"
2. Create two more Dialogue nodes for the responses
3. On the first Dialogue node, find the output handle next to "Accept Quest"
4. Drag from that handle to the "Accept" response Dialogue node
5. Repeat for the "Decline Quest" option, connecting to the other response node

Now when the player clicks "Accept Quest", the story will flow to the acceptance dialogue. If they click "Decline Quest", it goes to the decline dialogue instead.

Connection Types

StoryFlow Editor uses color-coded connection types, each with its own purpose. Here are the main types you will encounter.

Primary Handles (Execution Flow)

Visual: White with play icon (triangle)

Purpose: Controls the order of execution. When a node finishes executing, it follows its primary connections to determine which node runs next.

Found On:

• Start node (output)
• Dialogue node (input at top, outputs per option and element, plus a header output for click-to-advance when no options or elements exist)
• Run Script node (input, default output, plus exit route outputs from target script)
• Branch node (input, True output, False output)
• Random Branch node (input, multiple weighted outputs)
• Set nodes for variables (input and output)
• End node (input only)

Boolean Handles (Data Flow)

Visual: Yellow circle with play icon overlay

Purpose: Passes true/false values between nodes for conditional logic.

Found On:

• Boolean Get nodes (output)
• Boolean Set nodes (input and output)
• Logic nodes: And, Or, Not (inputs and outputs)
• Comparison nodes: >, < (output)
• Branch node condition input
• Dialogue option condition inputs

Integer Handles (Data Flow)

Visual: Cyan circle with play icon overlay

Purpose: Passes whole number values between nodes for calculations and comparisons.

Found On:

• Integer Get nodes (output)
• Integer Set nodes (input and output)
• Arithmetic nodes: Plus, Minus (inputs and output)
• Comparison nodes: >, < (inputs)

Float Handles (Data Flow)

Visual: Lime green circle

Purpose: Passes decimal number values between nodes for precise calculations.

Found On:

• Float Get/Set nodes (input and output)
• Float arithmetic nodes: Plus, Minus, Multiply, Divide, Random (inputs and output)
• Float comparison nodes (inputs)

String Handles (Data Flow)

Visual: Pink/Magenta circle

Purpose: Passes text values between nodes for string manipulation and comparison.

Found On:

• String Get/Set nodes (input and output)
• String operation nodes: Concatenate, Contains, Length (inputs and output)
• Type conversion nodes (input or output)

Enum Handles (Data Flow)

Visual: Teal circle

Purpose: Passes enum values between nodes for selection-based logic.

Found On:

• Enum Get/Set nodes (input and output)
• Equal Enum, Switch On Enum (inputs)
• Type conversion nodes: Enum to String, String to Enum, Int to Enum

Asset Handles (Data Flow)

Visual: Emerald (Image), Violet (Character), Amber (Audio)

Purpose: Passes asset references between nodes for media and character operations.

Found On:

• Image Get/Set nodes (emerald handles)
• Character Get/Set and Character Variable nodes (violet handles)
• Audio Get/Set nodes (amber handles)

Type Safety

StoryFlow Editor enforces strict type safety to prevent logic errors. Connections are validated automatically to ensure compatibility.

Connection Rules:

• Primary to Primary: Execution flow handles can only connect to other execution flow handles
• Boolean to Boolean: Yellow boolean handles can only connect to other yellow boolean handles
• Integer to Integer: Cyan integer handles can only connect to other cyan integer handles
• Float to Float: Lime green float handles can only connect to other lime green float handles
• String to String: Pink string handles can only connect to other pink string handles
• Enum to Enum: Teal enum handles can only connect to other teal enum handles
• Asset to Asset: Image, Character, and Audio handles can only connect to handles of the same asset type
• No Self-Connections: A node cannot connect to itself
• Max Connections: Some handles have connection limits (e.g., Branch outputs can only have 1 connection each)

Why Type Safety Matters:

• Prevents connecting a number to a boolean input (which would cause errors)
• Ensures execution flow is always valid
• Catches mistakes immediately during editing rather than at runtime
• Makes the visual graph self-documenting (colors indicate data types)

Editing Connections

Managing existing connections is just as important as creating them. StoryFlow Editor provides several ways to edit and delete connections.

Selecting and Deleting Connections:

• Select a Connection: Click once on any connection line to select it. The selected connection will highlight to show it's selected
• Delete Selected: After selecting a connection, press Delete or Backspace to remove it
• Quick Delete: Double-click any connection line to delete it instantly without selecting first
• Delete Node: Deleting a node automatically removes all its connections

Connection Limits:

Different handles have different connection limits based on their purpose:

• Multiple Connections Allowed: Some handles (like inputs) can accept multiple connections - you can create as many as needed
• Max Connection Limit Reached: Handles with limits (like Branch True/False outputs) can only have one connection each. If a connection already exists, you won't be able to drag from that handle to create a new connection. You must delete the existing connection first

Organizing Connections:

• Move Nodes: Drag nodes around to organize your graph - connections automatically redraw to follow
• Arrange Left-to-Right: Place earlier story events on the left, later events on the right
• Group Related Nodes: Keep connected nodes close together to minimize long connection lines
• Use Comments: Add Comment nodes to label sections and explain connection purposes

Best Practices

Follow these best practices to create clear, maintainable node graphs with well-organized connections.

Visual Organization:

• Left-to-Right Flow: Arrange nodes so the story flows from left to right (Start on left, End on right)
• Minimize Crossing Lines: Rearrange nodes to reduce connection lines crossing each other
• Group by Function: Keep related logic nodes (e.g., variable calculations) grouped together
• Vertical Spacing: Use vertical space to separate different story branches

Connection Clarity:

• Label Dialogue Options: Use descriptive option text so it's clear which output does what
• Branch Labels: Branch nodes clearly show "True" and "False" outputs - use this to create readable logic
• Avoid Long Connections: If a connection spans many nodes, consider using Run Script to break the graph into multiple files

Common Patterns:

1. Simple Option:

Start → Dialogue (with options) → Response Dialogues → End

2. Conditional Branch:

Start → Get Boolean → Branch → (True: Dialogue A, False: Dialogue B) → End

3. Variable Update:

Execution → Get Integer → Plus → Set Integer → Continue

4. Complex Condition:

Get Bool 1 ↘
              AND → Branch → Result
Get Bool 2 ↗

Debugging Connections:

• Test Often: Use the Play Window frequently to test your story flow
• Follow the Connections: If an option doesn't work as expected, trace the connection visually
• Check Variable Scope: Ensure variables are global if they need to persist across scripts
• Verify Conditions: Make sure boolean conditions are connected correctly to Branch nodes