Command node

The Command node enables you to create sequential statements scripts that can be used to perform many tasks.

Supported statements include:

• Statements to create local variables (such as local)

• Statement to set or modify node fields and local variables (such as set, modify)

• Specific statement for specific engine or logic functions (such as log, debug, createnode, createshare, deleteshare)

• Statements to execute other commands or coroutines (such as execute)

• Statements to manage script execution flow (such as if (command), while, break, return)

Platform support

This node is fully supported on XR-Windows, XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-Portable WASM platforms.

Passing data to a command using args field

A Command can specify a list of required mandatory input parameters to be set when using the command. This is done by the args field.

Each argument defined in the args field will be available inside the Command itself as a predefined local variable.

Note: When invoking a command with args field set, all its arguments must be valorized with values of the correct type. If an argument is missing or has an invalid type, an error will be triggered.

Syntax example

The syntax to specify the input parameters is: args="name1=type,name2=type....."

<!-- command with single arg -->

<Command name="cmd_logText" args="text=sstring" >

<log text="received: [@%text%]" />

</Command>

<!-- command with multiple args -->

<Command name="cmd_updateSize" args="w=sfloat,h=sfloat" >

<set name="aNode.size' value="[@%w%] [@%h%]" />

</Command>

Code example with multiple arguments

Commands with multiple arguments can be invoked only by execute statement in other commands or coroutines.

<!-- calling multiple arguments command from another command or coroutine -->

<Command name="test" >

<execute command="cmd_updateSize" w="200" h="40" />

</Command>

Code example with single argument

Commands with single argument can be invoked by execute, set, setfield statements in other commands or coroutines and can be also triggered by route.

<!-- calling single arguments command from another command or coroutine -->

<Command name="test" >

<!-- execute using argument-->

<execute command="cmd_logText" text="Text 1" />

<!-- execute using value -->

<execute command="cmd_logText" value="Text 1" />

<!-- set using value -->

<set name="cmd_logText.execute" value="Text 1" />

</Command>

<!-- calling single command argument by a route -->

<route from="keyA.keyDown" to="cmd_logText.execute" value="key A Pressed" />

<route from="inputText.text" to="cmd_logText.execute" />

Passing data to a command without using args field

When calling a command with no argument set in the args field, it's still possible to pass it a set of comma-separated values that will be accessible within the command script by progressive numbered references using the syntax %N% where %0% is the first parameter.

This older approach is still supported for compatibility reasons; however, it is not recommended for two reasons:

• Numbered parameters are not typed, so you will always need to assign them to a local to access their typed content.

• The parser splits the parameters based on the presence of the (',') character. This makes it hard to properly pass several data types, such as collections (for example, mfloat, mstring, mvec2) or textual content (for example, sstring, dstring, mdstring, sjson).

Code example of no-args command with multiple arguments

<!-- A command that uses the legacy way of taking multiple arguments -->

<Command name="cmd_doSumAndLog" >

<local name="a" type="sfloat" value="%0%" />

<local name="b" type="sfloat" value="%1%" />

<local name="sum" type="sfloat" value="#[@%a%]+[@%b%]#" />

<log text="%0% + %1% = [@%sum%]" />

</Command>

Code example of calling no-args command from another command

These type of commands can be invoked by execute, set, setfield statements in other commands or coroutines and can be also triggered by route.

<!-- calling no-args command from another command or coroutine -->

<Command name="test" >

<!-- execute using value -->

<execute command="cmd_doSumAndLog" value="5,7" />

<!-- set using value -->

<set name="cmd_doSumAndLog.execute" value="8,10.3" />

</Command>

<!-- calling no-args command from a route -->

<route from="keyA.keyDown" to="cmd_doSumAndLog.execute" value="7,32.4" />

Returning a value

Command return functionalities are defined by its returnType field. When returnType is not specified, it is set to its default value of void, and the Command is not required to return any value. By setting the returnType to any existing Field Data Type, the Command needs to end its execution flow by returning a value of the valid type using the return statement.

The result of the command can be accessed by the returnValue field.

<!-- command with no returnType not using return statement -->

<Command name="cmd_one">

<log text="Called cmd one" />

</Command>

<!-- command with no return type using return statement -->

<Command name="cmd_checkWidth" args="width=sfloat">

<return condition="[@%width%]!=25" />

<log text="Reached required width" />

</Command>

<!-- command with return type set to sfloat -->

<Command name="cmd_doSum" args="a=sfloat,b=sfloat" returnType="sfloat" >

<return value="#[@%a%]+[@%b%]#" />

</Command>

<!-- consuming the command result -->

<Command name="cmd_logSum" >

<execute command="cmd_doSum" a="10.5" b="23.7" />

<log text="10.5+23.7=[@cmd_doSum.returnValue]" />

</Command>

Command fields

These are the fields for Command node node.