RouteObject

• Methods • Method Details •

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);
});
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);
});
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.

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.

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.