RouteObject - Vircadia API Docs

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts

A route in a MappingObject used by the Controller API.

Create a route using MappingObject methods and apply this object's methods to process it, terminating with RouteObject#to to apply it to a Standard control, action, or script function. Note: Loops are not permitted.

Some methods apply to routes with number data, some apply routes with Pose data, and some apply to both route types.

Methods

Name	Return Value	Summary
`clamp`	RouteObject	Filters numeric route values to lie between two values; values outside this range are not passed on through the route.
`constrainToInteger`	RouteObject	Filters numeric route values such that they are rounded to `-1`, `0`, or `1`. For example, this enables you to use an analog input as if it were a toggle or, in the case of a bidirectional axis, a tri-state switch.
`constrainToPositiveInteger`	RouteObject	Filters numeric route values such that they are rounded to `0` or `1`. For example, this enables you to use an analog input as if it were a toggle.
`deadZone`	RouteObject	Filters numeric route values such that they're sent only when the input value is outside a dead-zone. When the input passes the dead-zone value, output is sent starting at `0.0` and catching up with the input value. As the input returns toward the dead-zone value, output values reduce to `0.0` at the dead-zone value.
`debug`	RouteObject	Enables or disables writing debug information for a route to the program log.
`exponentialSmoothing`	RouteObject	Filters Pose route values to be smoothed by an exponential decay filter. The filter's rotation and translation values are calculated as: `filterConstant * currentValue + (1 - filterConstant) * previousValue`. Values near 1 are less smooth with lower latency; values near 0 are more smooth with higher latency.
`hysteresis`	RouteObject	Filters numeric route values such that they are rounded to `0` or `1` without output values flickering when the input value hovers around `0.5`. For example, this enables you to use an analog input as if it were a toggle.
`invert`	RouteObject	Filters numeric and Pose route values to have the opposite sign, e.g., `0.5` is changed to `-0.5`.
`logicalNot`	RouteObject	Filters numeric route values such that a value of `0.0` is changed to `1.0`, and other values are changed to `0.0`.
`lowVelocity`	RouteObject	Filters Pose route values to be smoothed by a low velocity filter. The filter's rotation and translation values are calculated as: `(1 - f) * currentValue + f * previousValue` where `f = currentVelocity / filterConstant`. At low velocities, the filter value is largely the previous value; at high velocities the value is wholly the current controller value.
`peek`	RouteObject	Processes the route without marking the controller output as having been read, so that other routes from the same controller output can also process.
`postTransform`	RouteObject	Filters Pose route values to have a post-transform applied.
`pulse`	RouteObject	Filters numeric route values to send at a specified interval.
`rotate`	RouteObject	Filters Pose route values to have a pre-rotation applied.
`scale`	RouteObject	Filters numeric and Pose route values to be scaled by a constant amount.
`to`	None	Terminates the route with a standard control, an action, or a script function. The output value from the route is sent to the specified destination.
`toQml`	None	Terminates the route with a standard control, an action, or a script function. The output value from the route is sent to the specified destination. This is a QML-specific version of to: use this version in QML files.
`transform`	RouteObject	Filters Pose route values to have a pre-transform applied.
`translate`	RouteObject	Filters Pose route values to have a pre-translation applied.
`when`	RouteObject	Processes the route only if a condition is satisfied. The condition is evaluated before the route input is read, and the input is read only if the condition is `true`. Thus, if the condition is not met then subsequent routes using the same input are processed.
`whenQml`	RouteObject	Processes the route only if a condition is satisfied. The condition is evaluated before the route input is read, and the input is read only if the condition is `true`. Thus, if the condition is not met then subsequent routes using the same input are processed. This is a QML-specific version of when: use this version in QML files.

Method Details

clamp( min, max ) → {RouteObject}
Returns: The route object with the clamp filter added.

Filters numeric route values to lie between two values; values outside this range are not passed on through the route.

Parameters

Name	Type	Description
`min`	number	The minimum value to pass through.
`max`	number	The maximum value to pass through.

Example

Clamp right trigger values to between 0.3 and 0.7.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.RT).clamp(0.3, 0.7).to(function (value) {
    print("Value: " + value);
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

constrainToInteger( ) → {RouteObject} Returns: The `RouteObject` with the filter applied.
Filters numeric route values such that they are rounded to `-1`, `0`, or `1`. For example, this enables you to use an analog input as if it were a toggle or, in the case of a bidirectional axis, a tri-state switch. Example Round the right joystick forward/back values to `-1`, `0`, or `1`. `var MAPPING_NAME = "com.vircadia.controllers.example.newMapping"; var mapping = Controller.newMapping(MAPPING_NAME); mapping.from(Controller.Standard.RY).constrainToInteger().to(function (value) { print("Value: " + value); // -1, 0, or 1 }); Controller.enableMapping(MAPPING_NAME); Script.scriptEnding.connect(function () { Controller.disableMapping(MAPPING_NAME); });`

constrainToInteger( ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric route values such that they are rounded to -1, 0, or 1. For example, this enables you to use an analog input as if it were a toggle or, in the case of a bidirectional axis, a tri-state switch.

Example

Round the right joystick forward/back values to -1, 0, or 1.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.RY).constrainToInteger().to(function (value) {
    print("Value: " + value);  // -1, 0, or 1
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

constrainToPositiveInteger( ) → {RouteObject} Returns: The `RouteObject` with the filter applied.
Filters numeric route values such that they are rounded to `0` or `1`. For example, this enables you to use an analog input as if it were a toggle. Example Round the right joystick forward/back values to `0` or `1`. `var MAPPING_NAME = "com.vircadia.controllers.example.newMapping"; var mapping = Controller.newMapping(MAPPING_NAME); mapping.from(Controller.Standard.RY).constrainToPositiveInteger().to(function (value) { print("Value: " + value); // 0, or 1 }); Controller.enableMapping(MAPPING_NAME); Script.scriptEnding.connect(function () { Controller.disableMapping(MAPPING_NAME); });`

constrainToPositiveInteger( ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric route values such that they are rounded to 0 or 1. For example, this enables you to use an analog input as if it were a toggle.

Example

Round the right joystick forward/back values to 0 or 1.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.RY).constrainToPositiveInteger().to(function (value) {
    print("Value: " + value);  // 0, or 1
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

deadZone( min ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric route values such that they're sent only when the input value is outside a dead-zone. When the input passes the dead-zone value, output is sent starting at 0.0 and catching up with the input value. As the input returns toward the dead-zone value, output values reduce to 0.0 at the dead-zone value.

Parameters

Name	Type	Description
`min`	number	The minimum input value at which to start sending output. For negative input values, the negative of this value is used.

Example

Apply a dead-zone to the right joystick forward/back values.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.RY).deadZone(0.2).to(function (value) {
    print("Value: " + value);  // 0.0 - 1.0 values once outside the dead-zone.
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

debug( enableopt ) → {RouteObject}
Returns: The RouteObject with debug output enabled or disabled.

Enables or disables writing debug information for a route to the program log.

Parameters

Name	Type	Attributes	Default Value	Description
`enable`	boolean	<optional>	true	If `true` then writing debug information is enabled for the route, otherwise it is disabled.

Example

Write debug information to the program log for a right trigger mapping.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);

mapping.from(Controller.Standard.RT).debug().to(function (value) {
    print("Value: " + value);
});

// Information similar to the following is written each frame:
[DEBUG] [hifi.controllers] Beginning mapping frame
[DEBUG] [hifi.controllers] Processing device routes
[DEBUG] [hifi.controllers] Processing standard routes
[DEBUG] [hifi.controllers] Applying route  ""
[DEBUG] [hifi.controllers] Value was  5.96046e-07
[DEBUG] [hifi.controllers] Filtered value was  5.96046e-07

Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

exponentialSmoothing( rotationConstant, translationConstant ) → {RouteObject}
Returns: The RouteObject smoothed by an exponential filter.

Filters Pose route values to be smoothed by an exponential decay filter. The filter's rotation and translation values are calculated as: filterConstant * currentValue + (1 - filterConstant) * previousValue. Values near 1 are less smooth with lower latency; values near 0 are more smooth with higher latency.

Parameters

Name	Type	Description
`rotationConstant`	number	Rotation filter constant, `0.0–1.0`.
`translationConstant`	number	Translation filter constant, `0.0–1.0`.

hysteresis( min, max ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric route values such that they are rounded to 0 or 1 without output values flickering when the input value hovers around 0.5. For example, this enables you to use an analog input as if it were a toggle.

Parameters

Name	Type	Description
`min`	number	When the input value drops below this value the output value changes to `0`.
`max`	number	When the input value rises above this value the output value changes to `1`.

Example

Round the right joystick forward/back values to 0 or 1 with hysteresis.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.RY).peek().to(function (value) {
    print("Raw value: " + value);  // 0.0 - 1.0.
});
mapping.from(Controller.Standard.RY).hysteresis(0.3, 0.7).to(function (value) {
    print("Hysteresis value: " + value);  // 0 or 1.
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

invert( ) → {RouteObject} Returns: The `RouteObject` with the filter applied.
Filters numeric and Pose route values to have the opposite sign, e.g., `0.5` is changed to `-0.5`. Example Invert the value of the right joystick forward/back values. var MAPPING_NAME = "com.vircadia.controllers.example.newMapping"; var mapping = Controller.newMapping(MAPPING_NAME); mapping.from(Controller.Standard.LY).to(function (value) { print("L value: " + value); // -1.0 to 1.0 values, forward to back. }); mapping.from(Controller.Standard.RY).invert().to(function (value) { print("R value: " + value); // 1.0 to -1.0 values, forward to back. }); Controller.enableMapping(MAPPING_NAME); Script.scriptEnding.connect(function () { Controller.disableMapping(MAPPING_NAME); });

invert( ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric and Pose route values to have the opposite sign, e.g., 0.5 is changed to -0.5.

Example

Invert the value of the right joystick forward/back values.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.LY).to(function (value) {
    print("L value: " + value);  // -1.0 to 1.0 values, forward to back.
});
mapping.from(Controller.Standard.RY).invert().to(function (value) {
    print("R value: " + value);  // 1.0 to -1.0 values, forward to back.
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

logicalNot( ) → {RouteObject} Returns: The `RouteObject` with the filter applied.
Filters numeric route values such that a value of `0.0` is changed to `1.0`, and other values are changed to `0.0`. Example Logical NOT of LSTouch value. `var MAPPING_NAME = "com.vircadia.controllers.example.newMapping"; var mapping = Controller.newMapping(MAPPING_NAME); mapping.from(Controller.Standard.RSTouch).peek().to(function (value) { print("RSTouch: " + value); }); mapping.from(Controller.Standard.RSTouch).logicalNot().to(function (value) { print("localNot of RSTouch: " + value); }); Controller.enableMapping(MAPPING_NAME); Script.scriptEnding.connect(function () { Controller.disableMapping(MAPPING_NAME); });`

logicalNot( ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric route values such that a value of 0.0 is changed to 1.0, and other values are changed to 0.0.

Example

Logical NOT of LSTouch value.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);

mapping.from(Controller.Standard.RSTouch).peek().to(function (value) {
    print("RSTouch: " + value);
});
mapping.from(Controller.Standard.RSTouch).logicalNot().to(function (value) {
    print("localNot of RSTouch: " + value);
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

lowVelocity( rotationConstant, translationConstant ) → {RouteObject}
Returns: The RouteObject smoothed by low velocity filtering.

Filters Pose route values to be smoothed by a low velocity filter. The filter's rotation and translation values are calculated as: (1 - f) * currentValue + f * previousValue where f = currentVelocity / filterConstant. At low velocities, the filter value is largely the previous value; at high velocities the value is wholly the current controller value.

Parameters

Name	Type	Description
`rotationConstant`	number	The rotational velocity, in rad/s, at which the filter value is wholly the latest controller value.
`translationConstant`	number	The linear velocity, in m/s, at which the filter value is wholly the latest controller value.

peek( enableopt ) → {RouteObject}
Returns: The RouteObject with the peek feature enabled.

Processes the route without marking the controller output as having been read, so that other routes from the same controller output can also process.

Parameters

Name	Type	Attributes	Default Value	Description
`enable`	boolean	<optional>	true	If `true` then the route is processed without marking the route's controller source as having been read.

postTransform( transform ) → {RouteObject}
Returns: The RouteObject with the post-transform applied.

Filters Pose route values to have a post-transform applied.

Parameters

Name	Type	Description
`transform`	Mat4	The post-transform to apply.

pulse( interval ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric route values to send at a specified interval.

Parameters

Name	Type	Description
`interval`	number	The interval between sending values, in seconds.

Example

Send right trigger values every half second.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.RT).pulse(0.5).to(function (value) {
    print("Value: " + value);
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

rotate( rotation ) → {RouteObject}
Returns: The RouteObject with the pre-rotation applied.

Filters Pose route values to have a pre-rotation applied.

Parameters

Name	Type	Description
`rotation`	Quat	The pre-rotation to add to the pose.

scale( multiplier ) → {RouteObject}
Returns: The RouteObject with the filter applied.

Filters numeric and Pose route values to be scaled by a constant amount.

Parameters

Name	Type	Description
`multiplier`	number	The scale to multiply the value by.

Example

Scale the value of the right joystick forward/back values by 10.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Standard.LY).to(function (value) {
    print("L value: " + value);  // -1.0 to 1.0 values.
});
mapping.from(Controller.Standard.RY).scale(10.0).to(function (value) {
    print("R value: " + value);  // -10.0 to -10.0 values.
});
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

to( destination )

Terminates the route with a standard control, an action, or a script function. The output value from the route is sent to the specified destination.

Parameters

Name	Type	Description
`destination`	Controller.Standard \| Controller.Actions \| function	The standard control, action, or JavaScript function that the route output is mapped to. For a function, the parameter can be either the name of the function or an in-line function definition.

Examples

Make the right trigger move your avatar up.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);

mapping.from(Controller.Standard.RT).to(Controller.Actions.TranslateY);
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

Make the right trigger call a function.

function onRightTrigger(value) {
    print("Trigger value: " + value);
}

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);

mapping.from(Controller.Standard.RT).to(onRightTrigger);
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

toQml( destination )

Terminates the route with a standard control, an action, or a script function. The output value from the route is sent to the specified destination.

This is a QML-specific version of to: use this version in QML files.

Parameters

Name	Type	Description
`destination`	Controller.Standard \| Controller.Actions \| function	The standard control, action, or JavaScript function that the route output is mapped to. For a function, the parameter can be either the name of the function or an in-line function definition.

transform( transform ) → {RouteObject}
Returns: The RouteObject with the pre-transform applied.

Filters Pose route values to have a pre-transform applied.

Parameters

Name	Type	Description
`transform`	Mat4	The pre-transform to apply.

translate( translate ) → {RouteObject}
Returns: The RouteObject with the pre-translation applied.

Filters Pose route values to have a pre-translation applied.

Parameters

Name	Type	Description
`translate`	Vec3	The pre-translation to add to the pose.

when( expression ) → {RouteObject}
Returns: The RouteObject with the condition added.

Processes the route only if a condition is satisfied. The condition is evaluated before the route input is read, and the input is read only if the condition is true. Thus, if the condition is not met then subsequent routes using the same input are processed.

Parameters

Name Type Description

expression

condition | Array.<condition>

A condition may be a:

A numeric Controller.Hardware property, which is evaluated as a boolean.
! followed by a Controller.Hardware property to use the logical NOT of the property value.
A script function returning a boolean value. This can be either the name of the function or an in-line definition.

If an array of conditions is provided, their values are ANDed together.

Warning: The use of ! is not currently supported in JavaScript .when() calls.

Example

Process the right trigger differently in HMD and desktop modes.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);

// Processed only if in HMD mode.
mapping.from(Controller.Standard.RT)
    .when(Controller.Hardware.Application.InHMD)
    .to(function () { print("Trigger pressed in HMD mode."); });

// Processed only if previous route not processed.
mapping.from(Controller.Standard.RT)
    .to(function () { print("Trigger pressed in desktop mode."); });

Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

whenQml( expression ) → {RouteObject}
Returns: The RouteObject with the condition added.

This is a QML-specific version of when: use this version in QML files.

Parameters

Name Type Description

expression

condition | Array.<condition>

A condition may be a:

A boolean or numeric Controller.Hardware property, which is evaluated as a boolean.
! followed by a Controller.Hardware property, indicating the logical NOT should be used.
A script function returning a boolean value. This can be either the name of the function or an in-line definition.

If an array of conditions is provided, their values are ANDed together.