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 (Secondary): Yellow connections that pass true/false values between nodes
• Integer Data (Secondary): Cyan connections that pass numeric values between nodes

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

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 three distinct connection types, each with its own color and purpose.

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)
• Run Script node (input and output)
• Branch node (input, True output, False output)
• 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 numeric 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)

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
• 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