RouteObject

Available in: Interface Scripts Client Entity 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
to

Methods

clamp(min, max) → {RouteObject}
Filter 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.
Returns:
The route object with the clamp filter added.
Type: RouteObject
Example

Clamp right trigger values to between 0.3 and 0.7.

var MAPPING_NAME = "com.highfidelity.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}
Filter 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.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

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

var MAPPING_NAME = "com.highfidelity.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}
Filter 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.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

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

var MAPPING_NAME = "com.highfidelity.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}
Filter 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.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

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

var MAPPING_NAME = "com.highfidelity.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}
Enable and disabling writing debug information for a route to the program log.
Parameters:
Name Type Attributes Default Description
enable boolean <optional>
true If true then writing debug information is enabled for the route, otherwise it is disabled.
Returns:
The RouteObject with debug output enabled or disabled.
Type: RouteObject
Example

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

var MAPPING_NAME = "com.highfidelity.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}
Filter 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.
Returns:
The RouteObject smoothed by an exponential filter.
Type: RouteObject
hysteresis(min, max) → {RouteObject}
Filter 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.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

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

var MAPPING_NAME = "com.highfidelity.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}
Filter numeric and Pose route values to have the opposite sign, e.g., 0.5 is changed to -0.5.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

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

var MAPPING_NAME = "com.highfidelity.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}
Filter numeric route values such that a value of 0.0 is changed to 1.0, and other values are changed to 0.0.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

Logical NOT of LSTouch value.

var MAPPING_NAME = "com.highfidelity.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}
Filter 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.
Returns:
The RouteObject smoothed by low velocity filtering.
Type: RouteObject
peek(enableopt) → {RouteObject}
Process 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 Description
enable boolean <optional>
true If true then the route is processed without marking the route's controller source as having been read.
Returns:
The RouteObject with the peek feature enabled.
Type: RouteObject
postTransform(transform) → {RouteObject}
Filter Pose route values to have a post-transform applied.
Parameters:
Name Type Description
transform Mat4 The post-transform to apply.
Returns:
The RouteObject with the post-transform applied.
Type: RouteObject
pulse(interval) → {RouteObject}
Filter numeric route values to send at a specified interval.
Parameters:
Name Type Description
interval number The interval between sending values, in seconds.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

Send right trigger values every half second.

var MAPPING_NAME = "com.highfidelity.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}
Filter Pose route values to have a pre-rotation applied.
Parameters:
Name Type Description
rotation Quat The pre-rotation to add to the pose.
Returns:
The RouteObject with the pre-rotation applied.
Type: RouteObject
scale(multiplier) → {RouteObject}
Filter 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.
Returns:
The RouteObject with the filter applied.
Type: RouteObject
Example

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

var MAPPING_NAME = "com.highfidelity.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)
Terminate 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.highfidelity.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.highfidelity.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)
Terminate 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}
Filter Pose route values to have a pre-transform applied.
Parameters:
Name Type Description
transform Mat4 The pre-transform to apply.
Returns:
The RouteObject with the pre-transform applied.
Type: RouteObject
translate(translate) → {RouteObject}
Filter Pose route values to have a pre-translation applied.
Parameters:
Name Type Description
translate Vec3 The pre-translation to add to the pose.
Returns:
The RouteObject with the pre-translation applied.
Type: RouteObject
when(expression) → {RouteObject}
Process 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.

Returns:
The RouteObject with the condition added.
Type: RouteObject
Example

Process the right trigger differently in HMD and desktop modes.

var MAPPING_NAME = "com.highfidelity.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}
Process 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 to: 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.

Returns:
The RouteObject with the condition added.
Type: RouteObject