MappingObject - Vircadia API Docs

Description

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

A Controller mapping object that can contain a set of routes that map:

Controller.Standard outputs to Controller.Actions actions or script functions.
Controller.Hardware outputs to Controller.Standard outputs, Controller.Actions actions, or script functions.

Create by one of the following methods:

Use Controller.newMapping to create the mapping object, add routes using from or makeAxis, and map the routes to actions or functions using RouteObject methods.
Use Controller.parseMapping or Controller.loadMapping to load a Controller.MappingJSON.

Enable the mapping using enable or Controller.enableMapping for it to take effect.

Mappings and their routes are applied according to the following rules:

One read per output: after a controller output has been read, it can't be read again. Exception: You can use RouteObject#peek to read a value without marking that output as having been read.
Existing mapping routes take precedence over new mapping routes: within a mapping, if a route is added for a control output that already has a route the new route is ignored.
New mappings override previous mappings: each output is processed using the route in the most recently enabled mapping that contains that output.

Methods

Name	Return Value	Summary
`disable`	MappingObject	Disables the mapping. When disabled, the routes in the mapping have no effect. Synonymous with Controller.disableMapping.
`enable`	MappingObject	Enables or disables the mapping. When enabled, the routes in the mapping take effect. Synonymous with Controller.enableMapping.
`from`	RouteObject	Creates a new RouteObject from a controller output, ready to be mapped to a standard control, action, or function.
`fromQml`	RouteObject	Creates a new RouteObject from a controller output, ready to be mapped to a standard control, action, or function. This is a QML-specific version of from: use this version in QML files.
`makeAxis`	RouteObject	Creates a new RouteObject from two numeric Controller.Hardware outputs, one applied in the negative direction and the other in the positive direction, ready to be mapped to a standard control, action, or function.
`makeAxisQml`	RouteObject	Creates a new RouteObject from two numeric Controller.Hardware outputs, one applied in the negative direction and the other in the positive direction, ready to be mapped to a standard control, action, or function. This is a QML-specific version of makeAxis: use this version in QML files.

Method Details

disable( ) → {MappingObject} Returns: The mapping object, so that further routes can be added.
Disables the mapping. When disabled, the routes in the mapping have no effect. Synonymous with Controller.disableMapping.

disable( ) → {MappingObject}
Returns: The mapping object, so that further routes can be added.

Disables the mapping. When disabled, the routes in the mapping have no effect.

Synonymous with Controller.disableMapping.

enable( enable ) → {MappingObject}
Returns: The mapping object, so that further routes can be added.

Enables or disables the mapping. When enabled, the routes in the mapping take effect.

Synonymous with Controller.enableMapping.

Parameters

Name	Type	Default Value	Description
`enable`	boolean	true	If `true` then the mapping is enabled, otherwise it is disabled.

from( source ) → {RouteObject}
Returns: A route ready for mapping to an action or function using RouteObject methods.

Creates a new RouteObject from a controller output, ready to be mapped to a standard control, action, or function.

Parameters

Name	Type	Description
`source`	Controller.Standard \| Controller.Hardware \| function	The controller output or function that is the source of the route data. If a function, it must return a number or a Pose value as the route data.

fromQml( source ) → {RouteObject}
Returns: A route ready for mapping to an action or function using RouteObject methods.

Creates a new RouteObject from a controller output, ready to be mapped to a standard control, action, or function.

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

Parameters

Name	Type	Description
`source`	Controller.Standard \| Controller.Hardware \| function	The controller output or function that is the source of the route data. If a function, it must return a number or a Pose value as the route data.

makeAxis( source1, source2 ) → {RouteObject}
Returns: A route ready for mapping to an action or function using RouteObject methods. The data value passed to the route is the combined value of source2 - source1.

Creates a new RouteObject from two numeric Controller.Hardware outputs, one applied in the negative direction and the other in the positive direction, ready to be mapped to a standard control, action, or function.

Parameters

Name	Type	Description
`source1`	Controller.Hardware	The first, negative-direction controller output.
`source2`	Controller.Hardware	The second, positive-direction controller output.

Example

Make the Oculus Touch triggers move your avatar up and down.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping
    .makeAxis(Controller.Hardware.OculusTouch.LT, Controller.Hardware.OculusTouch.RT)
    .to(Controller.Actions.Up);
Controller.enableMapping(MAPPING_NAME);

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

makeAxisQml( source1, source2 ) → {RouteObject}
Returns: A route ready for mapping to an action or function using RouteObject methods. The data value passed to the route is the combined value of source2 - source1.

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

Parameters

Name	Type	Description
`source1`	Controller.Hardware	The first, negative-direction controller output.
`source2`	Controller.Hardware	The second, positive-direction controller output.