Controller

Disables translating and rotating the user's avatar in response to keyboard and controller controls.

Example

Disable avatar translation and rotation for a short period.

Script.setTimeout(function () {
    Controller.captureActionEvents();
}, 5000);

Script.setTimeout(function () {
    Controller.releaseActionEvents();
}, 10000);

Disables Entities.mousePressOnEntity and Entities.mouseDoublePressOnEntity events on entities.

Example

Disable entity click events for a short period.

Entities.mousePressOnEntity.connect(function (entityID, event) {
    print("Clicked on entity: " + entityID);
});

Script.setTimeout(function () {
    Controller.captureEntityClickEvents();
}, 5000);

Script.setTimeout(function () {
    Controller.releaseEntityClickEvents();
}, 10000);

Disables default Interface actions for a joystick.

Deprecated: This function is deprecated and will be removed. It no longer has any effect.

Parameters

Disables default Interface actions for a particular key event.

Parameters

Example

Disable left and right strafing.

var STRAFE_LEFT = { "key": 16777234, isShifted: true };
var STRAFE_RIGHT = { "key": 16777236, isShifted: true };

Controller.captureKeyEvents(STRAFE_LEFT);
Controller.captureKeyEvents(STRAFE_RIGHT);

Script.scriptEnding.connect(function () {
    Controller.releaseKeyEvents(STRAFE_LEFT);
    Controller.releaseKeyEvents(STRAFE_RIGHT);
});

Disables processing of mouse "move", "press", "double-press", and "release" events into Controller.Hardware.Keyboard outputs.

Example

Disable Controller.Hardware.Keyboard mouse events for a short period.

var MAPPING_NAME = "com.vircadia.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);
mapping.from(Controller.Hardware.Keyboard.MouseX).to(function (x) {
    print("Mouse x = " + x);
});
mapping.from(Controller.Hardware.Keyboard.MouseY).to(function (y) {
    print("Mouse y = " + y);
});
Controller.enableMapping(MAPPING_NAME);
Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});

Script.setTimeout(function () {
    Controller.captureMouseEvents();
}, 5000);

Script.setTimeout(function () {
    Controller.releaseMouseEvents();
}, 10000);

Disables processing of touch "begin", "update", and "end" events into Controller.Hardware.Keyboard, Controller.Hardware.Touchscreen, and Controller.Hardware.TouchscreenVirtualPad outputs.

Disables processing of mouse wheel rotation events into Controller.Hardware.Keyboard outputs.

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

Parameters

Enables or disables a controller mapping. When enabled, the routes in the mapping have effect.

Parameters

Finds the ID of an action from its name.

Parameters

Example

Get the ID of the "TranslateY" action. Compare with the property value.

var actionID = Controller.findAction("TranslateY");
print("Action ID = " + actionID);  // 1
print("Property value = " + Controller.Actions.TranslateY);  // 537001728 or similar value.

Finds the ID of a specific controller from its device name.

Parameters

Example

Get the ID of the Oculus Touch.

var deviceID = Controller.findDevice("OculusTouch");
print("Device ID = " + deviceID);

Gets the names of all actions available as properties of Controller.Actions.

Example

Get the names of all actions.

var actionNames = Controller.getActionNames();
print("Action names: " + JSON.stringify(actionNames));
// ["TranslateX","TranslateY","TranslateZ","Roll", ...

Gets the Controller.Actions property tree. Calling this function is the same as using the Controller property, Controller.Actions.

Gets the current value of an action.

Parameters

Example

Periodically report the value of the "TranslateX" action.

var actionID = Controller.findAction("TranslateX");

function reportValue() {
    print(Controller.getActionValue(actionID));
}
reportTimer = Script.setInterval(reportValue, 1000);

Gets a list of all available actions.

Deprecated: This function is deprecated and will be removed. It no longer works.

Gets a list of all available inputs for a hardware device.

Deprecated: This function is deprecated and will be removed. It no longer works.

Parameters

Gets the value of a controller axis output. Note: Also gets the value of a controller button output.

Parameters

Finds the name of a particular controller from its device ID.

Parameters

Example

Get the name of the Oculus Touch controller from its ID.

var deviceID = Controller.findDevice("OculusTouch");
print("Device ID = " + deviceID);

var deviceName = Controller.getDeviceName(deviceID);
print("Device name = " + deviceName);

Gets the names of all currently available controller devices plus "Actions", "Application", and "Standard".

Example

Get the names of all currently available controller devices.

var deviceNames = Controller.getDeviceNames();
print(JSON.stringify(deviceNames));
// ["Standard","Keyboard","LeapMotion","OculusTouch","Application","Actions"] or similar.

Gets the Controller.Hardware property tree. Calling this function is the same as using the Controller property, Controller.Hardware.

Gets the directory in which input recordings are saved.

Gets the value of a controller pose output.

Parameters

Gets the recommended area to position UI on the HUD surface if in HMD mode or Interface's window interior if in desktop mode.

Gets the names of all the active and running (enabled) input devices.

Example

List all active and running input devices.

print("Running devices: " + JSON.stringify(Controller.getRunningInputDeviceNames()));

Gets the Controller.Standard property tree. Calling this function is the same as using the Controller property, Controller.Standard.

Gets the value of a controller button or axis output. Note: Also gets the value of a controller axis output.

Parameters

Example

Report the Standard and Vive right trigger values.

var triggerValue = Controller.getValue(Controller.Standard.RT);
print("Trigger value: " + triggerValue);

if (Controller.Hardware.Vive) {
    triggerValue = Controller.getValue(Controller.Hardware.Vive.RT);
    print("Vive trigger value: " + triggerValue);
} else {
    print("No Vive present");
}

Gets the dimensions of the Interface window's interior if in desktop mode or the HUD surface if in HMD mode.

Loads an input recording, ready for play back.

Parameters

Creates a new controller mapping from a MappingJSON JSON file at a URL. Use enableMapping to enable the mapping for it to take effect.

Warning: This function is not yet implemented; it doesn't load a mapping and just returns null.

Parameters

Creates a new controller mapping. Routes can then be added to the mapping using MappingObject methods and routed to Standard controls, Actions, or script functions using RouteObject methods. The mapping can then be enabled using enableMapping for it to take effect.

Parameters

Example

Create a simple mapping that makes 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);
});

Creates a new controller mapping from a MappingJSON string. Use enableMapping to enable the mapping for it to take effect.

Parameters

Example

Create a simple mapping that makes the right trigger move your avatar up.

var mappingJSON = {
    "name": "com.vircadia.controllers.example.jsonMapping",
    "channels": [
        { "from": "Standard.RT", "to": "Actions.TranslateY" }
    ]
};

var mapping = Controller.parseMapping(JSON.stringify(mappingJSON));
mapping.enable();

Script.scriptEnding.connect(function () {
    mapping.disable();
});

Enables translating and rotating the user's avatar in response to keyboard and controller controls that were disabled using captureActionEvents.

Re-enables Entities.mousePressOnEntity and Entities.mouseDoublePressOnEntity events on entities that were disabled using captureEntityClickEvents.

Re-enables default Interface actions for a joystick that has been disabled using captureJoystick.

Deprecated: This function is deprecated and will be removed. It no longer has any effect.

Parameters

Re-enables default Interface actions for a particular key event that has been disabled using captureKeyEvents.

Parameters

Enables processing of mouse "move", "press", "double-press", and "release" events into Controller.Hardware.Keyboard outputs that were disabled using captureMouseEvents.

Enables processing of touch "begin", "update", and "end" events into Controller.Hardware.Keyboard, Controller.Hardware.Touchscreen, and Controller.Hardware.TouchscreenVirtualPad outputs that were disabled using captureTouchEvents.

Enables processing of mouse wheel rotation events into Controller.Hardware.Keyboard outputs that wer disabled using captureWheelEvents.

Saves the current recording to a file. The current recording may have been recorded by startInputRecording and stopInputRecording, or loaded by loadInputRecording. It is saved in the directory returned by getInputRecorderSaveDirectory.

Enables or disables the virtual game pad that is displayed on certain devices (e.g., Android).

Parameters

Sets the amount of extra margin between the virtual game pad that is displayed on certain devices (e.g., Android) and the bottom of the display.

Parameters

Shows or hides the virtual game pad that is displayed on certain devices (e.g., Android).

Parameters

Plays back the current recording from the beginning. The current recording may have been recorded by startInputRecording and stopInputRecording, or loaded by loadInputRecording. Playback repeats in a loop until stopInputPlayback is called.

Example

Play back a controller recording.

var file = Window.browse("Select Recording", Controller.getInputRecorderSaveDirectory());
if (file !== null) {
    print("Play recording: " + file);
    Controller.loadInputRecording("file:///" + file);
    Controller.startInputPlayback();

    // Stop playback after 20s.
    Script.setTimeout(function () {
        print("Stop playing recording");
        Controller.stopInputPlayback();
    }, 20000);
}

Starts making a recording of currently active controllers.

Example

Make a controller recording.

// Delay start of recording for 2s.
Script.setTimeout(function () {
    print("Start input recording");
    Controller.startInputRecording();
}, 2000);

// Make a 10s recording.
Script.setTimeout(function () {
    print("Stop input recording");
    Controller.stopInputRecording();
    Controller.saveInputRecording();
    print("Input recording saved in: " + Controller.getInputRecorderSaveDirectory());
}, 12000);

Stops play back of a recording started by startInputPlayback.

Stops making a recording started by startInputRecording.

Triggers a haptic pulse on connected and enabled devices that have the capability.

Parameters

Example

Trigger a haptic pulse on the right hand.

var HAPTIC_STRENGTH = 0.5;
var HAPTIC_DURATION = 10;
var RIGHT_HAND = 1;
Controller.triggerHapticPulse(HAPTIC_STRENGTH, HAPTIC_DURATION, RIGHT_HAND);

Triggers a haptic pulse on a particular device if connected and enabled and it has the capability.

Parameters

Example

Trigger a haptic pulse on an Oculus Touch controller.

var HAPTIC_STRENGTH = 0.5;
var deviceID = Controller.findDevice("OculusTouch");
var HAPTIC_DURATION = 10;
var RIGHT_HAND = 1;
Controller.triggerHapticPulseOnDevice(deviceID, HAPTIC_STRENGTH, HAPTIC_DURATION, RIGHT_HAND);

Triggers a 250ms haptic pulse on connected and enabled devices that have the capability.

Parameters

Triggers a 250ms haptic pulse on a particular device if connected and enabled and it has the capability.

Parameters

Deprecated: This function is deprecated and will be removed.

Parameters

Triggered when an action occurs.

Parameters

Example

Report action events as they occur.

var actionNamesForID = {};
var actionNames = Controller.getActionNames();
for (var i = 0, length = actionNames.length; i < length; i++) {
    actionNamesForID[Controller.findAction(actionNames[i])] = actionNames[i];
}

function onActionEvent(action, value) {
    print("onActionEvent() : " + action + " ( " + actionNamesForID[action] + " ) ; " + value);
}

Controller.actionEvent.connect(onActionEvent);

Script.scriptEnding.connect(function () {
    Controller.actionEvent.disconnect(onActionEvent);
});

Triggered when a device is registered or unregistered by a plugin. Not all plugins generate hardwareChanged events: for example, connecting or disconnecting a mouse will not generate an event but connecting or disconnecting an Xbox controller will.

Triggered when an input device starts or stops being active and running (enabled). For example, enabling or disabling the LeapMotion in Settings > Controls > Calibration will trigger this signal.

Parameters

Triggered when there is a new controller input event.

Parameters

Example

Report input events as they occur.

var inputNamesForID = {};
for (var property in Controller.Standard) {
    inputNamesForID[Controller.Standard[property]] = "Controller.Standard." + property;
}

function onInputEvent(input, value) {
    print("onInputEvent() : " + input + " ( " + inputNamesForID[input] + " ) ; " + value);
}

Controller.inputEvent.connect(onInputEvent);

Script.scriptEnding.connect(function () {
    Controller.inputEvent.disconnect(onInputEvent);
});

Triggered when a keyboard key is pressed.

Parameters

Example

Report the KeyEvent details for each key press.

Controller.keyPressEvent.connect(function (event) {
    print(JSON.stringify(event));
});

Triggered when a keyboard key is released from being pressed.

Parameters

Triggered when a mouse button is double-pressed.

Parameters

Triggered when the mouse moves.

Parameters

Example

Report the MouseEvent details for each mouse move.

Controller.mouseMoveEvent.connect(function (event) {
    print(JSON.stringify(event));
});

Triggered when a mouse button is pressed.

Parameters

Triggered when a mouse button is released from being pressed.

Parameters

Triggered when a touch event starts in the Interface window on a touch-enabled display or device.

Parameters

Example

Report the TouchEvent details when a touch event starts.

Controller.touchBeginEvent.connect(function (event) {
    print(JSON.stringify(event));
});

Triggered when a touch event ends in the Interface window on a touch-enabled display or device.

Parameters

Triggered when a touch event update occurs in the Interface window on a touch-enabled display or device.

Parameters

Triggered when the mouse wheel is rotated.

Parameters

Example

Report the WheelEvent details for each wheel rotation.

Controller.wheelEvent.connect(function (event) {
    print(JSON.stringify(event));
});