A game about forced loneliness, made by TACStudios
tacstudios.tngl.sh
1# Control nodes
2
3> [!NOTE]
4> For versions 2019/2020 LTS, download the Visual Scripting package from the [Unity Asset Store](https://assetstore.unity.com/packages/tools/visual-bolt-163802).
5
6Control nodes branch, loop and merge the flow.
7
8## Branching
9
10Branching nodes split the control flow based on a value.
11
12### If
13The common if node uses a boolean condition. Consider them as an "if the condition is true, do something, otherwise, do something else."
14
15
16
17### Switch
18
19Branch on the value of an enum, a string, or an integer. These nodes are called Switch nodes.
20
21To switch on an enum, decide on the type of the enum. The branch output ports appears.
22
23
24
25To switch on a string or number, create each branch option in the graph inspector.
26
27
28
29The node is updated with each output port.
30
31For strings, optionally choose to ignore the case of the selector.
32
33> [!NOTE]
34> A Default port is always added. It is the path that the control flow should take if the input selector does not correspond to any other option.
35
36### Select
37
38Select nodes are the opposite of switch nodes. You can select a single value from a set of options based on a selector.
39
40For example, a Select On Integer node that chooses a color based on a player number.
41
42
43
44
45>[!NOTE]
46> In the above example predictive debugging warns of a crash if playerNo is not within 1, 2, 3, or 4, because the Default port is not connected.
47
48## Looping
49
50Loops repeats logic for a certain number of iterations before moving on.
51
52The logic to be repeated is called the body of the loop. After the loop is over, the exit port is called.
53
54>[!NOTE]
55> The body of every loop is called synchronously, not over the course of multiple frames. Co-routine-like behaviours are achieved by listening to the update event manually.
56
57### While Loop
58
59The while loop is the simplest form of loop. It repeats its body while its condition remains true. Only when the condition becomes false does the loop terminate.
60
61For example, the following graph generates a new random name until the result isn't contained in the names application variable.
62
63
64
65> [!WARNING]
66> Do not create an infinite loop. If the condition is always true, the editor hangs. As loop bodies are synchronous, not parallel, there are few uses for while loops in visual scripting.
67
68### For Each Loop
69
70For Each iterates over every element of a collection. It outputs the current index and item that is being looped over.
71
72For example, the following graph outputs four messages to the console:
73
74* *I love my cat*
75* *I love my dog*
76* *I love my bird*
77* *I love my fish*
78
79
80
81To access the key and value from dictionaries in the loop, check the Dictionary box.
82
83### For Loop
84
85For is a numeric loop and requires three integers: a start index, an end index, and a step. The loop starts at the first index, then increments towards the last index via increments of the step. It outputs the current index.
86
87For example, this graph counts to ten by skipping odd numbers because of its step. In other words, its output is 0, 2, 4, 6, then 8.
88
89
90
91The For loop can also be very useful when combined with the Get List Item and Count Items nodes.
92
93For example, the following graph is very similar to the last graph as the output to the console is "I like {animal}s".
94
95Instead of using the For Each node that outputs each item, the graph outputs each item manually by its index in the list. This graph outputs the following messages:
96
97* *I like cats*
98* *I like dogs*
99* *I like birds*
100* *I like horses*
101
102
103
104### Break Loop
105
106A loop can finish early by using the Break Loop node. As soon as this node is entered, the exit port of the loop is called, no matter how many more iterations remain.
107
108For example, even though this for loop is supposed to count to 10, it stops at 5 because of the break. Its output is 0, 1, 2, 3, then 4.
109
110
111
112## Exception Handling
113
114### Try Catch
115
116The Try Catch node handles [Exceptions](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/exceptions/) that occur. It prevents your game from crashing in case you suspect some code might fail.
117
118Anything that gets executed in the Try branch is considered "safe": the script continues from the Catch branch instead if it fails. The Exception port captures information about the failure when that happens. A common way of handling this is to log a warning with the exception message.
119
120
121
122> [!NOTE]
123> By default, this node catches all exceptions. Be specific in your handling by changing the exception type in the dropdown.
124
125The Finally branch is optional. It is always called after Try or Catch, regardless of whether the operation succeeded or not. It is usually used to dispose or destroy any resources that must be freed. This port can be disconnected if there is no need to destroy any resources.
126
127### Throw
128
129The Throw node allows you to raise your own exceptions that stop the flow. These are caught with Try Catch.
130
131It is good practice to "fail early" by throwing as soon as something unexpected happens. It helps catch bugs early in the chain, instead of letting them trickle down and have unexpected side effects that are hard to debug.
132
133For example, to ensure damage is positive before applying it:
134
135
136
137If the Custom checkbox is selected, you can pass a custom Exception object that contains more data than a simple message. Most often, this is not required. By default, the thrown exception is of type `System.Exception`.
138
139## Toggles
140
141Toggle nodes are similar in principle to light-switches: they can be turned on and off to impact either the script or values. Think of them as "gates" that can be opened and closed.
142
143### Toggle Flow
144
145The Toggle Flow node gates the flow of control. When on, the flow passes through; when off, the flow does not.
146
147There are many inputs and outputs that allow fine grained control over the logic. In the previous example, Toggle is used to show how the same event (a keypress) turns the toggle on and off. Instead you can use On and Off with two different events to get the same results.
148
149On the output side, the Is On boolean port indicates the toggle status, that is turned on or off. The control outputs are triggered according to the table below:
150
151| Port | Triggered When |
152|------------|--------------------|
153| On | Flow enters the toggle via the unmarked input while it is on. |
154| Off | Flow enters the toggle via the unmarked input while it is off. |
155| Turned On | The toggle gets turned on, either via the On or Toggle inputs. |
156| Turned Off | The toggle gets turned off, either via the Off or Toggle inputs. |
157
158### Toggle Value
159
160The Toggle Value node selects between two different input values depending on whether it is on or off. Its ports work exactly like the Toggle Flow node.
161
162Another way of implementing the same logic as the previous example: clicking Space toggles the object to move up. This time a value of 1 or 0 is provided as the vertical velocity.
163
164> [!NOTE]
165> Turn on relations in the toolbar as a means to visualize the flow between the toggle ports.
166
167
168
169## Once
170
171The Once node executes different logic the first time it is traversed from any subsequent times.
172
173
174
175It can be reset by entering the Reset port.
176
177## Cache
178
179The Cache node saves the result of an expensive operating and reuses it instead of fetching it again each time you need it.
180
181For example, using this graph, the formula is calculated twice:
182
183
184
185By using the Cache node, the result is saved and calculated only once, optimizing performance.
186
187
188
189
190> [!NOTE]
191> It is important to note that caching only lasts within the scope of the current flow. The value of the cache is not shared or available from another event.