Special Actions
Special actions are used for controlling logic and execution within the CyanTrigger. These are concepts taken from other programming languages and may be more complicated for beginners.
A Block action is a way to organize a section of your actions. Actions can be dragged into the Block action to allow them to be included in the Block. Actions here will still be executed in order. Blocks can be minimized so that all actions within the block can be hidden from the action list view. Any local variables declared within the block can only be used within the Block. Blocks can be nested inside other Blocks. In terms of Programming, Blocks can be thought of as a set of curly braces, { }, which will define scope within a program.
Example view of a set of blocks.
Example of the same view with the top most block collapsed.
Condition is a special action that cannot be created directly, but is created from other special actions. The Condition action is always paired with a ConditionBody action directly after. Actions that use the Condition and ConditionBody actions:
- If
- Else If
- While
The Condition action is a special Block action that defines a local bool variable. This local variable can be renamed in the interface. The Condition Block will execute nested actions in order with the goal of setting the local variable to True or False. You must set this local variable, otherwise it will always be false. At the end of the Condition Block, the value of the bool variable will be checked:
- If the value is False, the ConditionBody following this Condition will not be executed at all.
- If the value is True, the ConditionBody following this Condition will be executed. By default, all actions within the Condition will be executed. The actions ConditionPassIfTrue and ConditionFailIfFalse can be used to complete the Condition early if the answer is already determined, preventing actions after from executing.
Example usage of a condition. In this case, the condition variable is named “countZero”. The nested action sets the condition variable to the results of _count equalling 0.
ConditionPassIfTrue is a special action that must be used within a Condition. In programming terms, this action helps with Condition Short Circuiting. ConditionPassIfTrue has only one bool input value:
- If the value is False, nothing happens and the remaining condition actions will execute in order as expected.
- If the value is True, all actions in the Condition following this action will not be executed. The Condition itself will evaluate to True and the next action executed will be the ConditionBody ConditionPassIfTrue is helpful in constructing large conditional checks. In programming terms, it could be compared to the Conditional Or. If the first half is true, then you don’t need to check the later half as True Conditionally Or’ed with anything will still evaluate to True.
Example usage of PassIfTrue. In the example, the first action will check if the value variable is less than 0. The PassIfTrue will check the results. If it was true, then the condition is finished and it will jump directly to the condition body. If the condition was false, the int.GreaterThan action will then execute, continuing the Condition.
ConditionFailIfFalse is a special action that must be used within a Condition. In programming terms, this action helps with Condition Short Circuiting. ConditionFailIfFalse has only one bool input value:
- If the value is False, all actions in the Condition following this action will not be executed. The Condition itself will evaluate to False and the ConditionBody will also be skipped. The next action to execute will be the one after the ConditionBody block.
- If the value is True, nothing happens and the remaining condition actions will execute in order as expected. ConditionFailIfFalse is helpful in constructing large conditional checks. In programming terms, it could be compared to the Conditional And. If the first half is false, then you don’t need to check the later half as False Conditionally And’ed with anything will still evaluate to False.
Example usage of FailIfFalse. In the example, a GameObject is checked if it is valid and then checked if it is active. Without the FailIfFalse, when the GameObject is not valid (null), then the GameObject.Get activeSelf action will throw an error as you cannot execute it on invalid GameObjects. The FailIfFalse will break out of the condition early to ensure that the next action is not executed and does not crash the Udon Program.
The ConditionBody Action is a special action that cannot be created directly, but is created from other special actions. The ConditionBody action is always directly after a Condition action. ConditionBody is a special Block action that, depending on the results of the Condition action, may or may not execute actions within its Block. See Condition for more details
The If action is a special action that creates Condition and ConditionBody actions. This is the method for gating actions within your CyanTrigger to only execute if some condition has been met.
Example usage of an If action. As you can see, the If action contains both a Condition and a ConditionBody. In this example, the Condition will pass when “This GameObject” is active. If the condition passes, then the ConditionBody will execute, sending a custom event to “DoTheThing”.
The Else action is a special Block action that must be directly after an If or Else If Action. When the Condition inside of the previous If action evaluates to False, then this Else action will execute instead.
Example using Else action. In the example, an AudioSource is checked if it is playing. If it is playing, it is stopped. If it is not playing, it is told to play.
The Else If action is a special Block action that must be directly after an If or another Else If Action. The Else If action is a combination of both the Else action and the If action. Just with the Else action, when the Condition inside of the previous If action evaluates to False, then this If Else action will execute instead. The Else If action will create the Condition and ConditionBody actions just like an If action.
Example usage of ElseIf that checks if a value is 0, 1, 2, or other.
The While action is a special action that creates Condition and ConditionBody actions. This is the method for looping over a Block of actions while a condition has been met. The condition will be evaluated on every iteration. A while loop will try to execute in a single frame. It is important that the values change between every iteration. If not, you may have an infinite loop and freeze Unity or VRChat. If you would like to do per frame operations, use the Update event instead.
Example usage of a While action. In this example, the while will loop through each transform parent for an object until it gets to the root.
The For action is a special action that is similar to the While action in that it will loop over a list of action. Instead of checking a Condition action, the For action will loop through numbers from a start point to an end point. The For action takes in three inputs:
- Start - The value to start looping
- End - The value to check if we have reached to end the loop. This value is exclusive in that it will not iterate on this value.
- Step - The value to be added every iteration to move towards the end value. This can be negative, but make sure that End is less than Start! The For action also provides an Index variable to know what iteration of the loop you are currently on. For loops are typically used to iterate over elements in an array, using the index to access each element.
Example usage of a For action. In this example, there is an int array and the for loop is used to iterate over each element in it.
The ForEach action is a special action that is similar to the While and For action in that it will loop over each element in an array of items. The ForEach action is an extension of the For action, but it handles the start, end, and step values for you. The ForEach action takes one input:
- Array - The array to loop over all elements The ForEach action also provides two variable outputs while looping. These can be new variables or existing variables. The values will be updated on each iteration of the loop.
- Index - The current index into the array
- Value - The value at the current index in the array.
The Break action is a special action that must be used within a Loop action’s body. Current loop actions include the While action and the For action. Using the Break action will stop all execution of the Loop and move to the next action after.
Example usage of Break within a For action. The example goes through an array of integers and checks for which one is equal to the special value. If the value is found, the loop will break out of the loop and execute the rest of the actions in the Event.
The Continue action is a special action that must be used within a Loop action’s body. Current loop actions include the While action and the For action. Using the Continue action will jump directly to the loop’s Condition to see if it should continue looping.
Example usage of Continue within a For action. The example gets all players and iterates through each of them. The Continue action is used when checking if the current player is valid or not. If it is not valid, we do not want to execute actions on it, so we continue the loop to the next player.
The Return action is a special action that will stop all execution of the current event. The Return action can be used anywhere, but is typically used within an If action to know when the event should finish early.
The ReturnIfDisabled action is similar to the Return action, but it will conditionally return based on the state of the GameObject and UdonBehaviour. If the GameObject is disabled, either directly or indirectly because a parent object is disabled, or if the UdonBehaviour is disabled, then this will return, finishing the event early. This action is meant to simulate the behaviour for SDK2 Events in that they would only execute if both the object and the component were enabled. When using this, it is best to put it at as the first action, but this is not a requirement.
