Custom Node: Difference between revisions

From RoboPad Wiki
Jump to navigation Jump to search
(→‎Programming Tips and API: Adds warning about this.inputs.)
(Adds Example, further clarifies behaviour.)
 
(6 intermediate revisions by the same user not shown)
Line 15: Line 15:
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.
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.
*'''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.
*'''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.
*'''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 '''must''' emit this node's default value (for example, something like the [[Number Node]] would simply emit it's numeric value here).
*'''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.
*'''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 ==
== 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:
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.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''': ''this.inputs'' is an array of floats that relates to the respective indices of the input ports (as defined in the Input Labels). '''Note: Currently, this list can have null elements or not be the complete length of the inputs.'''
* '''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''': Only available in the ''Trigger Script'', this value is the index of the Input Port that triggered this call to the "Trigger Script".
* '''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''.

Latest revision as of 16:38, 10 March 2023

← Return to Node Catalogue

Custom Node
Inputs
  • [User configurable...]
Outputs
  • [User configurable...]
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.