CyanTrigger Events and Actions - CyanLaser/CyanTrigger GitHub Wiki
CyanTrigger has some unique events and actions that may not be available to general Udon. For the ones that exist in Udon, CyanTrigger has a modified implementation making it different than Udon. See also Special Actions for control flow actions defined in CyanTrigger.
Note that this action has been removed in Version 0.4. Use UdonBehaviour.SendCustomEvent instead.
This is CyanTrigger’s version of UdonBehaviour.SendCustomEvent. For other objects, this behaves exactly the same. When this is targeting itself, “This CyanTrigger” variable, it will optimize execution by jumping in assembly. In the future, this action may have more options, such as possibly having parameters, but this is not yet implemented.
The Custom Event is a special type of event that will only execute when called through any of the UdonBehaviour.SendCustomEvent actions. This includes:
- SendCustomEvent
- SendCustomNetworkedEvent
- SendCustomEventDelayedSeconds
- SendCustomEventDelayedFrames
These actions can be used in CyanTrigger, other UdonBehaviours, and through Animation Events and UI Events. For Animation Events, the CyanTrigger or UdonBehaviour need to be on the same GameObject as the Animator.
When using the SendCustomEvent action to execute an event on the same CyanTrigger, it is recommended to use the “This UdonBehaviour” variable. It will be auto filled to this on creation.
Note that it is highly recommended to add an underscore to the beginning of every event name. This will prevent the event from being networked and called through questionable clients. If the event is set to a non local broadcast such as Send to Owner or Send to All, then CyanTrigger will handle behind the scenes the event that is broadcasted.
When a Custom Event is set to local broadcast and a delay of 0, it can have parameters to define input and output variables. Parameters allow you to pass information around between this event and the action that called it. You can add parameters by clicking on the plus button on the Parameter list. This will allow you to select the type for the new parameter. Once selected, a new parameter will be added to the list. You can edit the parameter’s name, input or output type, and order in the list. Input means that the calling action will be passing information into the event. Output means that this event will set the value of the output variable to be provided back to the calling action.
Custom Events with parameters must have a unique event name. Event Parameters can only be called from SendCustomEvent and not the networked or delayed versions. Once you have defined the parameters and used it in a SendCustomEvent action, updating the event name, parameter name, parameter input/output type, or the parameter order will break any SendCustomEvent action that called it.
When using SendCustomEvent to call an event with parameters, but the inspector cannot determine the available events, you can manually add parameters used. Make sure to get the parameter type, name, and input type correct or it may not work as expected.
Behind the scenes, these parameters are using UdonBehaviour.SetProgramVariable and UdonBehaviour.GetProgramVariable. Udon itself does not support parameters at this time. Parameters are only supported with CyanTrigger programs. Calling into UdonSharp events with parameters and return values is not supported from CyanTrigger. It is possible for UdonSharp to call into a CyanTrigger event with parameters though.
If a Custom Event is defined in CyanTrigger and it has parameters, another Udon Program (UdonGraph or UdonSharp) can call this event, but you must set the parameters manually using UdonBehaviour.SetProgramVariable. These parameters will have a special name based on the name of the Custom Event:
_arg_<parameter name>_<event name>
For example: if a Custom Event named "MyEvent" has a parameter named "MyVar", the compiled variable name will be _arg_MyVar_MyEvent
.
Here is an example calling this from UdonSharp:
udon.SetProgramVariable("_arg_MyVar_MyEvent", value);
udon.SendCustomEvent("MyEvent");
The OnVariableChanged event is an event that will be called when a global variable’s value has changed, either through an action setting its value, a remote UdonBehaviour or CyanTrigger used SetProgramVariable on this variable, or the value changed through network sync. This action will be called immediately on change of the variable. Inside the OnVariableChanged event, you have access to the previous or old value to see what it used to be.
Note, do not set the value of the variable within the OnVariableChanged event, as this will cause an infinite loop.
If you are using OnVariableChanged to handle synced variable updates, be careful to not depend on any other synced variable’s value. Synced variables are updated in an arbitrary order. If you need to depend on multiple synced variables, then use OnDeserialization instead and manually check for if the value changed.
VRChat’s official documentation for OnVariableChange
This Event is a recreation of the action from SDK2’s VRC_Trigger It takes 4 items as input:
- Repeat
- Reset on Enable
- Low Period Time
- High Period Time
OnTimer is a way to make a cancelable delay in CyanTrigger. When the GameObject or UdonBehaviour is enabled, it will generate a random duration between the low and high period and wait that duration in seconds before firing the actions. If the GameObject or UdonBehaviour is disabled during this time, the actions will not fire. If Reset On Enable is checked, then the timer’s random duration will be generated every time it is enabled. If it is not checked, then the initial random time will be used until it is fired. If Repeat is checked, then after firing actions, a new random time is generated and will wait this new time before firing the actions again. If repeat is not checked, once fired the event will not try to fire again until reset. If OnTimer is used with the “delay in seconds” property, the delay will happen after the timer has fired and cannot be canceled.
OnTimer uses the Update event behind the scenes. This is not the most performant, but it does allow for canceable delays. When multiple OnTimer events are used on the same CyanTrigger, if any have the exact same inputs, these timers will be merged and fired at the same time, rather than generating unique random times per event.
This action is a recreation of the action from SDK2’s VRC_Trigger. It takes three items as inputs:
- GameObjects
- Component Name
- Enabled state
This action will go through each GameObject in the list, find all components with the given name, and set the enabled state. If there are valid GameObjects listed, then the Component Name field will provide a list of available components on the GameObjects that can be selected.
In general, this action is less efficient compared to using the component’s set enabled action directly.
This action is a recreation of the action from SDK2’s VRC_Trigger. It takes two items as inputs:
- GameObjects
- Component Name
This action will go through each GameObject in the list, find all components with the given name, and toggle the enabled state. If there are valid GameObjects listed, then the Component Name field will provide a list of available components on the GameObjects that can be selected.
In general, this action is less efficient compared to using the component’s get and set enabled actions directly to perform your own toggle. Although this would be more actions overall and would require understanding of variables.
String.Get newLine will fill the provided variable with a string that is just a single new line character. In CyanTrigger, all string inputs are single line only. This means you cannot add new lines directly. To add new lines to text you want to display, you will need to use this action to get the new line character and concatenate strings together with it.
The comment action is an action that does nothing. It is only there to allow you to provide notes in your action list. You can add comments by right clicking the action and selecting “Edit Comment”. While selected, you can also start editing or finish editing a comment by pressing shift + enter. Note that any action can have a comment, but this comment action is a dedicated way to add comments that will not change how the CyanTrigger works in game.
The ClearReplay action allows you to clear any replay information for a given event, as if it had never fired. See Event Replay section for more information.
The Set action is a way to set the value of a variable with either a constant value or copying the value of another variable. All supported types in Udon have a Set Action. The Set action is often used to create a new variable for a given type. By selecting “+New” for the output and giving a name, this will create a new local variable.
Some actions take a Type as an input. A type is a way to know what kind of data something is. Type variables are typically used for GetComponent actions as a way to explicitly get a specific component. Most of these also have alternative options that take in a string which would use the type name instead of the type itself.