Introduction to Visual Scripting¶

Visual Scripting is a way of creating logic and behaviors using blocks (called nodes) and connections rather than writing traditional lines of code. Instead of typing out functions, loops, and conditionals in a text-based language, you drag and drop nodes in a canvas, then connect them to describe your logic flow.

This system is designed to be more approachable and more visual than regular code, which can be helpful for:

Designers or non-programmers who want to build game logic or application rules.
Rapid prototyping, where you want to see a high-level overview of logic flow without diving into low-level syntax.

Why Use Visual Scripting?¶

Clarity: Instead of lines of text, you see boxes (nodes) that represent small pieces of logic. The lines (connections) between them show how data and execution flow around.
Faster Iteration: You can experiment with logic flows, reorder or reconnect nodes, and see the results quickly without rewriting large portions of code.
Accessibility: People with limited coding experience can often grasp and use the system.

Comparing Visual Scripting to Regular Coding¶

In typical (text-based) code, you might write something like:

if (playerScore > 100) {
    UnlockBonus();
} else {
    ShowWarning();
}

In Visual Scripting, this might appear as:

Node: "Greater Than 100?"
True Flow → Node: "Unlock Bonus"
False Flow → Node: "Show Warning"

You drag lines (connections) from the "if" node's True output pin to the "Unlock Bonus" node, and from the False output pin to the "Show Warning" node. The end result is the same, but the structure is visual instead of textual.

Core Concepts¶

Nodes¶

A node is the basic building block of Visual Scripting. Each node represents a small piece of logic or data operation, such as:

A comparison (Is Score > 100?)
A mathematical operation (Add, ConcatStrings)
A function call (e.g., UnlockBonus())
A wait or delay (e.g., wait 2 seconds)
A branch or condition node (like an if statement)
A parallel node (split or replicate the flow into multiple paths)

Ports (Pins)¶

Nodes have ports (often called pins):

Enter/Exit Ports: These define the flow of execution. A node will run when something connects into its "enter" port, and after the node completes, it activates whatever is connected to its "exit" port(s).
Input/Output Ports: These handle data (e.g., numbers, strings). An input port might need a value (like a number to compare), and an output port might provide the result (e.g., "true" or "false").

Links (Connections)¶

Links are the lines connecting node ports together. They carry either:

Flow (execution order): from an exit port of one node to an enter port of another, or
Data (values, variables, etc.): from an output data port to an input data port.

With these links, you create the graph of how your logic runs and how data travels from node to node.

Flows (Threads of Execution)¶

In a text-based language, you typically have a function call stack. In Visual Scripting, you have flows (sometimes called threads or streams) that move through the connected nodes:

Flow enters a node (triggering that node to run).
The node does its work (like computing a math result or waiting for an event).
The node exits by activating one or more exit ports.
Each exit port leads the flow onward to the connected node(s).

Parallel Flows¶

It's common to have multiple flows active at once. For instance, a node might split the flow into two parallel branches. Each branch (flow) can continue independently. If you need them to come back together, you often have a join node that waits for all branches before moving on.

Example scenarios:

Parallel: You want to play a sound effect while also fading out a UI panel. The script can branch into two flows—one controls audio, the other controls UI transitions.
Synchronizing: Eventually, you use a join or wait node if you want to continue only after both branches finish.

Input and Output Parameters of a Script¶

Each visual script can also be treated like a function that has:

Input Parameters: Provided by whoever starts the script. For instance, if your script is meant to process a "player name," that name is given to the script before it runs.
Output Parameters: The script might compute or gather data (like a final string or an updated variable) and present them when it finishes.

Execution Flow with Script Inputs/Outputs¶

Start: You pass in any input parameters (like "playerName") when starting the script.
Select an Entry Port: The script has a special "enter" port for beginning execution.
Run: The flow(s) proceed through all relevant nodes, possibly splitting or waiting for events.
Reaching an Output Port: Once a flow hits any "exit" port designated as the script's final output, the script is considered done.
Collect Outputs: Just before the script completes, it supplies the final values for the output parameters. The system can then call back or notify that the script is finished, returning those results.

Comparison with Regular Code¶

Similarities: - You still use conditions, loops, function calls, or events, but in a more visual arrangement. - You can have parallel logic.

Differences: - Instead of reading text, you see a graph with boxes and arrows. - Each node is more atomic, focusing on a single piece of logic or a single operation. - Data and flow are visually separated (though they connect within the same graph).

How the Script Runs Internally¶

Scheduling: When you start the script, it creates a "flow" queue.
Nodes:
Each node is triggered in turn.
When a node finishes, it queues up the next node(s).
Parallel: If a node splits into multiple exits, each exit line spawns its own active flow.
Waiting or Events: Some nodes might wait for a user input, a timer, or a game event. During this wait, the flow is paused. When the event triggers, that flow resumes.
Completion: Once a flow reaches a designated script exit, the script is considered finished. If there are multiple flows, you can wait until all flows complete, or treat the first exit as the final outcome—this depends on the script's design.

Best Practices¶

Keep It Forward: Let your script flow forward from inputs to outputs. Avoid trying to compute outputs after everything ends—design your nodes so that final output data is ready when the flow hits the exit.
Use Parallel Wisely: Only branch parallel flows when you truly want simultaneous or independent tasks. Rejoin them if you need a single result.
Name Your Ports Clearly: When you have multiple exit ports from a node, name them ("Success," "Failure," "Timeout," etc.) so it's obvious which path is which.
Keep an Eye on Complexity: A large visual script can become messy if too many nodes are thrown in. Use grouping or sub-scripts to break down big logic.
Debug Often: Many visual scripting tools let you watch the flow highlight as it runs. Use that to confirm your script behaves as expected.

Conclusion¶

Visual Scripting offers a more intuitive approach to logic flow compared to conventional text code, especially for teams with mixed technical backgrounds or for quick iteration. By chaining nodes, connecting flow lines, and mapping out your logic in a graph, you can:

Clearly see what's happening,
Split and merge tasks in parallel,
Start or stop execution at specific ports,
Pass in input parameters at the start,
Gather final results at the output ports.

All of this happens without needing to write traditional code syntax, which can make your logic more accessible and maintainable in many scenarios.

Further Resources¶

Event Handling: How to make nodes wait for an external event (like keyboard input or a game event) and resume flow.
Sub-Scripts: Launching a new script from within a node, sometimes called nested scripting.
Debugging Visual Flows: Step through or watch the active flow highlight, see variable values on each node's output ports.
Variables and Data Storage: Overview of how to store and retrieve data in your script (global vs. local vs. port-based).