Ports

In Visual Scripting, a port is found on a node and functions as a point of connection that other nodes can connect into. Ports cannot exist by themselves, and are always attached to nodes. Ports can be connected to other ports using Links. Once connected, a port can only receive values from, or be flowed into, its connecting port.

Note: There are rules about connecting ports to each other. Some ports can only connect to one other port, while some can connect to many ports. Check out the Link Rules for more details.

In Ports and Out Ports

There are two kinds of ports:

• In Ports - ports going into a node
• Out Ports - ports going out of a node

It is easy to tell them apart by checking which side of the node the ports are in. In Ports are always found on the left side of a node, while Out Ports are always found on the right side of a node. This also holds true for the Script itself; the Script's In Ports are always on the left side of the Script View, while the Script's Out Ports are always on the right side of the Script View.

The In Ports include Enter Ports and Input Ports, while the Out Ports include Exit Ports and Output Ports.

Note: One rule about connecting ports to each other is that, generally, In Ports cannot be connected to other In Ports. Similarly, Out Ports cannot be connected to other Out Ports. However, there is an exception. Check out the Link Rules for more details.

Flow Ports and Value Ports

Besides the two kinds of ports, there is one other differentiating aspect of ports: whether a port is a Flow Port or a Value Port.

Flow Ports

Flow Ports are ports that facilitate the Flow of the Script. Whenever you see Flow Ports attached to a node, you can expect that node to be able to control the Flow of the Script in some way. The two types of Flow Ports are Enter Ports and Exit Ports.

Note: Flow Ports cannot be connected to Value Ports. Check out the Link Rules for more details.

Value Ports

Value Ports are ports that facilitate the transfer of values between nodes. Whenever you see Value Ports attached to a node, you can expect that node to retrieve a value, process that value, and pass it to the next node. The two types of Value Ports are Input Ports and Output Ports.

Note: Value Ports cannot be connected to Flow Ports. Check out the Link Rules for more details.

Enter Ports and Exit Ports

Besides facilitating the Flow of the Script, the Enter and Exit Ports don't do anything else. However, there are some details related to these ports that are worth pointing out.

Placement of the Ports

Some nodes have their Enter or Exit Ports next to the node name. These Enter or Exit Ports function the same way as any other Enter or Exit ports; their placement is made to keep the node compact. These ports usually act as the default Enter or Exit Ports of the node. Connecting into the default Enter Port is needed to activate the node itself. Conversely, connecting from the default Exit Port is needed if there are any other Exit Ports; this default Exit Port will activate only when the other Exit Ports do not activate.

Not Connected Exit Ports

If some node has its Exit Port not connected to another node or script's Exit Port, the Control Flow will stop at this point. If it is the only path, the whole script will stop, but not exit. It will keep occupying memory but not using CPU.

Name of the Ports

Enter and Exit Ports are usually named as Enter and Exit, respectively. They may also be called as node Entries or Exits in some parts of the app and this documentation. Please note that they are all talking about the same Enter and Exit Ports.

Port Visuals

As can be seen on the left and right sides of the Script View, the Enter and Exit Ports of a Script is visually different from the Enter and Exit Ports of a node. While they may look different, they function exactly the same when the Script is run.

Note: The Enter Ports of a Script can only be connected to the Enter Ports of a node or the Exit Ports of the Script, while the Exit Ports of a Script can only be connected to the Exit Ports of a node or the Enter Ports of the Script. This is the exception mentioned in the note under the In Ports and Out Ports section. Check out the Link Rules for more details.

Input Ports and Output Ports

The Input Ports and Output Ports -- not to be confused with In Ports and Out Ports -- are ports that facilitate the transfer of values between nodes.

Input Port Default Values

Between the Input and Output Ports, only the Input Ports have assignable default values for all value types. If an Input Port is not connected to any other nodes, the node containing that Input Port will use that Input Port's default value when activated.

Usually, the default value of an Input Port is located to within the node's borders, to the right of the Input Port. However, for some nodes, the default value is instead located outside of the node's borders, to the left of the Input Port.

Value Types

Unlike Flow Ports, the Input and Output Ports have value types associated to them. These value types determine which type of value these ports provide, as well as which ports can be connected to each other. Each value type also has an associated colored port to better differentiate it from other value types at a glance. Detailed below are all the value types that Value Ports can have.

Warning: The connection rules for each value type, as listed below, applies when creating the Link from the Output Port of a node to the Input Port of another node. It may not always work when going the other way. Check out the Link Rules for more details about the connection rules for each value types.

Tip: You can hover over the Value Ports to see its Value type.

Number Value Type (green)

The number value type represents both integer and decimal values. Number-typed ports are colored green. Number-typed ports can be connected to ports of these value types:

• Number
• Long
• String
• Object

Long Value Type (dark green)

The long value type represents long values. Long-typed ports are colored dark green. Long-typed ports can be connected to ports of these value types:

• Number
• Long
• String
• Object

String Value Type (yellow)

The string value type represents string or text values. String-typed ports are colored yellow. String-typed ports can be connected to ports of these value types:

• String
• Object

Boolean Value Type (purple)

The boolean value type represents boolean values -- either true or false. Boolean-typed ports are colored purple. Boolean-typed ports can be connected to ports of these value types:

• Boolean
• String
• Object

Document Value Type (red)

The document value type represents Documents created in your Balancy game. When setting the default value for some ports, selecting a Template first may be required before being able to select a Document. Document-typed ports are colored red. Document-typed ports can be connected to ports of these value types:

• Document
• String
• Object

Object Value Type (blue)

The object value type represents any other types not represented by any of the value types above. This includes any objects, SmartObjects, and even Lists. Object-typed ports can also accept and give values with unknown types. Object-typed ports are colored blue. Object-typed ports can be connected to ports of these value types:

• Object
• Number
• String
• Boolean
• Document

Value Flow: With Value Ports

Unlike the Control Flow, which focuses on the order of execution of nodes within a Script, the Value Flow dives into how nodes request values between each other, and how values travel between nodes. While you can think of nodes connected through their Flow Ports as a flowchart, you can think of nodes connected through their Value Ports as a dependency chart, where each node depends on the values of other nodes.

The Value Flow is facilitated through Value Ports. Connecting nodes to each other through their Value Ports is similar to creating connections between nodes in a dependency chart.

Chaining Nodes through Value Ports

The Value Flow is simpler than the Control Flow in a sense that, unlike the Control Flow, which can be controlled by special nodes, there are no special nodes that can control the Value Flow. When a node executes and requests a value from another node, the other node executes and provides that value. If the other node also needs to request a value from a third node, that third node also executes and provides that value. This process chains along all nodes directly connected through their value ports, until the first node gets the value it needs successfully.

However, if one of the nodes in the chain has its execution controlled by the Control Flow -- that is, if that node has any Flow Ports -- then it won't execute if another node requires its values. Instead, when it executes through the Control Flow, it stores the values it outputs, and this stored value is what it sends to the nodes once requested.