Custom Node
|
|
Inputs
|
Outputs
|
| Version Introduced 2.1 |
The Custom Node is a powerful node that allows you to directly write the JavaScript that runs within it to perform more complex operations on signal data.
Custom Nodes were introduced in firmware version 2.1 along with all basic nodes.
Settings
The settings found on the Custom Node allow you to configure the Node's input and output ports as well as the code that executes both on node start-up and also when the node recieves data.
- Script Name: Configures the name of this script, cosmetic only - only impacts the title of this node.
- Input Labels: A comma-separated list of the input ports to this node.
- Output Labels: A comma-separated list of the output ports to this node.
- Startup Script: This script is triggered as soon as the node is created, and should emit this node's default value if this node has a default state (for example, something like the Number Node would simply emit its numeric value here, and a Slider Node would emit its starting value here). Any node that has no inputs to trigger an output must emit a value here. Nodes with no Output ports do not need to emit anything.
- Trigger Script: The trigger script is run whenever the node recieves a new signal via an input port. It has access to a special "idx" variable that indicates the index of the input port (in order of their labels) that the incoming signal came from. This script will only trigger when the entire input array consists of valid numbers - namely once every input port has consumed a signal (or, if you want to set default values, if you have explicitly set values in the Startup Script - but this can be risky, as a default value may cause the trigger method to be called prematurely with the default values, rather than ingested values).
Programming Tips and API
By default both the Startup and Trigger scripts are running within the context of the Node object itself, meaning they have access to it via the this keyword. Using this they can access some core functions:
- this.sendDataOnChannel( output_port_index : int, value : float ): This function emits a signal of value on output_port_index (which relates to the Output Labels respective indices). Connected nodes will recieve this value via the connected input port.
- this.inputs: Only available in the Trigger Script, this.inputs is an array of floats that relates to the respective indices of the input ports (as defined in the Input Labels).
- idx [Trigger only]: Only available in the Trigger Script, this value is the index of the Input Port that triggered this call to the "Trigger Script".
Example
To build a simple Node that adds two numbers (like the Math Node), you would configure the Input Labels to "a,b" and the Output Labels to "sum". As the script has no default value (i.e. it can't output a value unless both of its input ports, a and b, have received a signal), the Startup Script can remain empty. Finally, every time a signal is sent to this node via its a or b input ports, it must emit on its sum output port the sum of the two numbers, meaning that the following script could be placed in the Trigger Script:
this.sendDataOnChannel(0, this.inputs[0] + this.inputs[1]);
And that's it! This script will emit on channel 0 (the first output port) the sum of the two input ports a and b.