Links¶
In Visual Scripting, a link is the connection between ports and allows nodes to talk to each other. Similar to Ports, links cannot exist by themselves, and have to always be connected to a port on both ends. Depending on whether a link connects Flow Ports or Value Ports together, a link may carry either a flow signal or a value between ports.
Note: Check out the Flow: Advanced section to learn more.
Link Rules¶
Outlined below are all the rules about creating a link between ports.
1. An In Port cannot be connected to itself or other In Ports, and an Out Port cannot be connected to itself or other Out Ports.¶
This is the most basic rule that concerns In Ports and Out Ports, the most general categories of ports. This rule is added to keep the Flow of the Script in one direction.
However, there is an exception. The In Ports of a Script -- found on the left side of the Script View -- can be connected to the In Ports of a node. Similarly, the Out Ports of a Script -- found on the right side of the Script View -- can be connected to the Out Ports of a node. This exception is done solely for ease of use. Although, this rule still applies the same way for Script's In Ports and Out Ports.
2. A Node cannot have any outgoing links connecting to its own In Ports.¶
This rule is added to prevent a node looping into itself and possibly accomplishing nothing. If looping is needed in your Scripts, please check out the For Each Node, which will loop through a List provided as input.
Note: It is still possible to loop between nodes, albeit with some limitations. Check out Flow Looping for more details.
3. A Flow Port cannot be connected to a Value Port, and a Value Port cannot be connected to a Flow Port.¶
This rule is added to prevent connections between Flow and Value Ports. These two types of ports differ in a lot of ways, and a connection between them do not make sense and may even break how Scripts work. If you ever require connecting some of your Flow and Value Ports together, please check out the Flow section first, and it may help you do whatever you need in your Scripts.
4. An Out Flow Port can connect to only one In Flow Port, but an In Flow Port can connect to multiple Out Flow Ports.¶
Note: An Out Flow Port is a Flow Port that is also an Out Port, while an In Flow Port is a Flow Port that is also an In Port.
This rule is added to enforce the concept of Link Direction in Scripts, and make it so the Script, when executed, will cause nodes to Flow between each other in a predictable way.
If an Out Flow Port can connect to multiple In Flow Ports, it is not determinable which node runs next, or if all of the connected nodes run at once, or if any nodes run at all.
If you need to run all connected nodes at the same time after a node finishes executing, please check out the Parallel Node. Here is an example of a Parallel Node being used to run multiple nodes at the same time.
Similarly, if an In Flow Port can connect to only one Out Flow Port, it may be inconvenient, if not impossible, to create a Script with branching paths that all lead to the same node. This will also require duplicating nodes repeatedly to reproduce the same behavior.
5. An Out Value Port can connect to multiple In Value Ports, but an In Value Port can connect to only one Out Value Port.¶
Note: An Out Value Port is a Value Port that is also an Out Port, while an In Value Port is a Value Port that is also an In Port.
Similar to rule #4, this rule is added to enforce the concept of Link Direction in Scripts, and make it so the Script, when executed, makes sure the nodes retrieve the values it needs from other nodes properly.
If an Out Value Port can connect to only one In Value Port, it will limit a node to send a value to only one destination at a time. This will require duplicating nodes repeatedly to reproduce the same behavior.
Similarly, if an In Value Port can connect to multiple Out Value Ports, it is not determinable which source the node should retrieve the value from, or if the node should retrieve the value from all the sources at once, or if the node should retrieve the value from any of the sources at all.
Link Rules for Ports with Value Types¶
As mentioned in the Value Types section of Ports, there are also some rules when creating a connection between ports with Value Types. These rules only apply when connecting an Out Value Port with an In Value Port, and may not always work the other way.
For quick reference, below is a table showing which Out Value Ports can be connected to which In Value Ports.
Number Value Type (green)¶
Number-typed ports can be connected to ports of these value types:
- Number
- Long
- String
- Object
Long Value Type (dark green)¶
Long-typed ports can be connected to ports of these value types:
- Number
- Long
- String
- Object
Note: Both Long and Number values are converted to the Decimal (128-bit) type in the C# plugin, so there shouldn't be any precision loss or number overflow when creating a connection from a Long port to a Number port.
String Value Type (yellow)¶
String-typed ports can be connected to ports of these value types:
- String
- Object
Boolean Value Type (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)¶
Object-typed ports can be connected to ports of these value types:
- Object
- Number
- String
- Boolean
- Document
Flow: Advanced¶
Link Direction¶
Links can send flow signals or values in only one direction. Knowing about link direction, along with understanding the Flow of the Script, will help you truly understand how your Scripts will execute.
Link Direction for Flow Ports¶
When two Flow Ports are connected, the flow signals between them always travel from the Out Flow Port to the In Flow Port. Therefore, if a source node contains the Out Flow Port and a destination node contains the In Flow Port, and the Out Flow Port is connected to the In Flow Port, the destination node will always execute after the source node, and never before.
Note: There is an exception to this rule: if the destination node connects to the source node, a loop is created and the source node will execute after the destination node finishes executing. Check out the Flow Looping section for more details.
Link Direction for Value Ports¶
Similarly, when two Value Ports are connected, the values between them always travel from the Out Value Port to the In Value Port. Therefore, if a source node contains the Out Value Port and a destination node contains the In Value Port, and the Out Value Port is connected to the In Value Port, these steps are followed:
- When the destination node executes, the destination node will request the source node for the value of its Out Value Port.
- The source node then executes and sends back the value to the destination node.
- The destination node receives and processes that value, finishing its execution.
In a way, the link direction between Value Ports seem to be bi-directional, but the value only travels in one direction.
Note: Unlike with Flow Ports, if the source node is connected to the destination node through their Value Ports, the destination node cannot connect to the source node or somehow create a loop through their Value Ports. Check out the Flow Looping section for more details.
Flow Looping¶
Flow Looping, also known as Cyclic Flow, happens when the nodes are connected in such a way that, if you start in one node and follow its connections, you will end up on the same node you started at.
Do note that when following the connections from a starting node, follow the connections from only one level of flow at a time. That is, if you start following Control Flow connections -- connections that link Out Flow Ports to In Flow Ports -- only follow Control Flow connections across the Script. The same goes for Value Flow connections. Flow loops found by following both Control Flow and Value Flow connections interchangeably do not count as Flow Looping, and are perfectly fine in Scripts.
Between the Control Flow and the Value Flow, only the Control Flow is allowed to have loops. This is so it will still be possible to create logical loops without the use of the For Each Node. The Value Flow is not allowed to have loops for these reasons:
- There are no nodes that can control the Value Flow. If loops were allowed, it may be possible that execution when evaluating the values of Value Ports may infinitely go on without achieving anything.
- A value has to end up somewhere. It is not a particularly useful outcome if the value ends up on the same node that first sent the value. However, a similar behavior is still possible through the Control Flow.