Controller

• Properties • Methods • Signals • Type Definitions • Method Details • Signal Details •

Description

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

The Controller API provides facilities to interact with computer and controller hardware.

Facilities

Properties

Get Controller property trees.

Mappings

Create and enable or disable Controller mappings.

Input, Hardware, and Action Reflection

Information on the devices and actions available.

Input, Hardware, and Action Signals

Notifications of device and action events.

Mouse, Keyboard, and Touch Signals

Notifications of mouse, keyboard, and touch events.

Control Capturing

Disable and enable the processing of mouse and touch events.

Action Capturing

Disable and enable controller actions.

Controller and Action Values

Get the current value of controller outputs and actions.

Haptics

Trigger haptic pulses.

Display Information

Get information on the display.

Virtual Game Pad

Use the virtual game pad which is available on some devices.

Input Recordings

Create and play input recordings.

Entity Methods

The default scripts implement hand controller actions that use Entities.callEntityMethod to call entity script methods, if present, in the entity being interacted with.

Method Name Description Example
startFarTrigger
continueFarTrigger
stopFarTrigger 		These methods are called when a user is more than 0.3m away from the entity, the entity is triggerable, and the user starts, continues, or stops squeezing the trigger. A light switch that can be toggled on and off from a distance.
startNearTrigger
continueNearTrigger
stopNearTrigger 		These methods are called when a user is less than 0.3m away from the entity, the entity is triggerable, and the user starts, continues, or stops squeezing the trigger. A doorbell that can be rung when a user is near.
startDistanceGrab
continueDistanceGrab
 These methods are called when a user is more than 0.3m away from the entity, the entity is either cloneable, or grabbable and not locked, and the user starts or continues to squeeze the trigger. A comet that emits icy particle trails when a user is dragging it through the sky.
startNearGrab
continueNearGrab
 These methods are called when a user is less than 0.3m away from the entity, the entity is either cloneable, or grabbable and not locked, and the user starts or continues to squeeze the trigger. A ball that glows when it's being held close.
releaseGrab This method is called when a user releases the trigger when having been either distance or near grabbing an entity. Turn off the ball glow or comet trail with the user finishes grabbing it.
startEquip
continueEquip
releaseEquip 		These methods are called when a user starts, continues, or stops equipping an entity. A glass that stays in the user's hand after the trigger is clicked.

All the entity methods are called with the following two arguments:

  • The entity ID.
  • A string, "hand,userID" — where "hand" is "left" or "right", and "userID" is the user's MyAvatar.sessionUUID.

Properties

Name Type Summary
Actions Controller.Actions

Predefined actions on Interface and the user's avatar. These can be used as end points in a RouteObject mapping. A synonym for Controller.Hardware.Actions. Read-only.

Default mappings are provided from the Controller.Hardware.Keyboard and Controller.Standard to actions in keyboardMouse.json and standard.json, respectively.

Hardware Controller.Hardware

Standard and hardware-specific controller and computer outputs, plus predefined actions on Interface and the user's avatar. The outputs can be mapped to Actions or functions in a RouteObject mapping. Additionally, hardware-specific controller outputs can be mapped to Controller.Standard controller outputs. Read-only.

Standard Controller.Standard

Standard controller outputs that can be mapped to Actions or functions in a RouteObject mapping. Read-only.

Each hardware device has a mapping from its outputs to Controller.Standard items, specified in a JSON file. For example, leapmotion.json and vive.json.

Methods

Name Return Value Summary
captureActionEvents None

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

captureEntityClickEvents None

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

Disables default Interface actions for a joystick.

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

Disables default Interface actions for a particular key event.
captureMouseEvents None

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

captureTouchEvents None

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

captureWheelEvents None

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

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

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

Finds the ID of an action from its name.
findDevice number

Finds the ID of a specific controller from its device name.
getActionNames Array.<string>

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

getActions Controller.Actions

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

Gets the current value of an action.
getAllActions Array.<Action>

Gets a list of all available actions.

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

getAvailableInputs Array.<NamedPair>

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

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

getAxisValue number

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

getDeviceName string

Finds the name of a particular controller from its device ID.
getDeviceNames Array.<string>

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

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

Gets the directory in which input recordings are saved.
getPoseValue Pose

Gets the value of a controller pose output.
getRecommendedHUDRect Rect

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

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

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

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

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

Loads an input recording, ready for play back.
loadMapping MappingObject

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.

newMapping MappingObject

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.

parseMapping MappingObject

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

releaseActionEvents None

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

releaseEntityClickEvents None

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

releaseJoystick None

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.
releaseKeyEvents None

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

releaseMouseEvents None

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

releaseTouchEvents None

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.

releaseWheelEvents None

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

saveInputRecording None

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.

setVPadEnabled None

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

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.
setVPadHidden None

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

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.

startInputRecording None

Starts making a recording of currently active controllers.
stopInputPlayback None

Stops play back of a recording started by startInputPlayback.

stopInputRecording None

Stops making a recording started by startInputRecording.

triggerHapticPulse None

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

triggerHapticPulseOnDevice None

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

triggerShortHapticPulse None

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

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

Deprecated: This function is deprecated and will be removed.

Signals

Name Summary
actionEvent

Triggered when an action occurs.
hardwareChanged

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.

inputDeviceRunningChanged

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.
inputEvent

Triggered when there is a new controller input event.

keyPressEvent

Triggered when a keyboard key is pressed.
keyReleaseEvent

Triggered when a keyboard key is released from being pressed.
mouseDoublePressEvent

Triggered when a mouse button is double-pressed.
mouseMoveEvent

Triggered when the mouse moves.
mousePressEvent

Triggered when a mouse button is pressed.
mouseReleaseEvent

Triggered when a mouse button is released from being pressed.
touchBeginEvent

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

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

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

Triggered when the mouse wheel is rotated.

Type Definitions

Actions
Type: object

The Controller.Actions object has properties representing predefined actions on the user's avatar and Interface. The property values are integer IDs, uniquely identifying each action. Read-only.

These actions can be used as end points in the routes of a MappingObject. The data item routed to each action is either a number or a Pose.

Property Type Data Description
Avatar Movement
TranslateX number number Move the user's avatar in the direction of its x-axis, if the camera isn't in independent or mirror modes.
TranslateY number number Move the user's avatar in the direction of its y-axis, if the camera isn't in independent or mirror modes.
TranslateZ number number Move the user's avatar in the direction of its z-axis, if the camera isn't in independent or mirror modes.
Pitch number number Rotate the user's avatar head and attached camera about its negative x-axis (i.e., positive values pitch down) at a rate proportional to the control value, if the camera isn't in HMD, independent, or mirror modes.
Yaw number number Rotate the user's avatar about its y-axis at a rate proportional to the control value, if the camera isn't in independent or mirror modes.
Roll number number No action.
DeltaPitch number number Rotate the user's avatar head and attached camera about its negative x-axis (i.e., positive values pitch down) by an amount proportional to the control value, if the camera isn't in HMD, independent, or mirror modes.
DeltaYaw number number Rotate the user's avatar about its y-axis by an amount proportional to the control value, if the camera isn't in independent or mirror modes.
DeltaRoll number number No action.
StepTranslateX number number No action.
StepTranslateY number number No action.
StepTranslateZ number number No action.
StepPitch number number No action.
StepYaw number number Rotate the user's avatar about its y-axis in a step increment, if the camera isn't in independent or mirror modes.
StepRoll number number No action.
Avatar Skeleton
Hips number Pose Set the hips pose of the user's avatar.
Spine2 number Pose Set the spine2 pose of the user's avatar.
Head number Pose Set the head pose of the user's avatar.
LeftArm number Pose Set the left arm pose of the user's avatar.
RightArm number Pose Set the right arm pose of the user's avatar.
LeftHand number Pose Set the left hand pose of the user's avatar.
LeftHandThumb1 number Pose Set the left thumb 1 finger joint pose of the user's avatar.
LeftHandThumb2 number Pose Set the left thumb 2 finger joint pose of the user's avatar.
LeftHandThumb3 number Pose Set the left thumb 3 finger joint pose of the user's avatar.
LeftHandThumb4 number Pose Set the left thumb 4 finger joint pose of the user's avatar.
LeftHandIndex1 number Pose Set the left index 1 finger joint pose of the user's avatar.
LeftHandIndex2 number Pose Set the left index 2 finger joint pose of the user's avatar.
LeftHandIndex3 number Pose Set the left index 3 finger joint pose of the user's avatar.
LeftHandIndex4 number Pose Set the left index 4 finger joint pose of the user's avatar.
LeftHandMiddle1 number Pose Set the left middle 1 finger joint pose of the user's avatar.
LeftHandMiddle2 number Pose Set the left middle 2 finger joint pose of the user's avatar.
LeftHandMiddle3 number Pose Set the left middle 3 finger joint pose of the user's avatar.
LeftHandMiddle4 number Pose Set the left middle 4 finger joint pose of the user's avatar.
LeftHandRing1 number Pose Set the left ring 1 finger joint pose of the user's avatar.
LeftHandRing2 number Pose Set the left ring 2 finger joint pose of the user's avatar.
LeftHandRing3 number Pose Set the left ring 3 finger joint pose of the user's avatar.
LeftHandRing4 number Pose Set the left ring 4 finger joint pose of the user's avatar.
LeftHandPinky1 number Pose Set the left pinky 1 finger joint pose of the user's avatar.
LeftHandPinky2 number Pose Set the left pinky 2 finger joint pose of the user's avatar.
LeftHandPinky3 number Pose Set the left pinky 3 finger joint pose of the user's avatar.
LeftHandPinky4 number Pose Set the left pinky 4 finger joint pose of the user's avatar.
RightHand number Pose Set the right hand of the user's avatar.
RightHandThumb1 number Pose Set the right thumb 1 finger joint pose of the user's avatar.
RightHandThumb2 number Pose Set the right thumb 2 finger joint pose of the user's avatar.
RightHandThumb3 number Pose Set the right thumb 3 finger joint pose of the user's avatar.
RightHandThumb4 number Pose Set the right thumb 4 finger joint pose of the user's avatar.
RightHandIndex1 number Pose Set the right index 1 finger joint pose of the user's avatar.
RightHandIndex2 number Pose Set the right index 2 finger joint pose of the user's avatar.
RightHandIndex3 number Pose Set the right index 3 finger joint pose of the user's avatar.
RightHandIndex4 number Pose Set the right index 4 finger joint pose of the user's avatar.
RightHandMiddle1 number Pose Set the right middle 1 finger joint pose of the user's avatar.
RightHandMiddle2 number Pose Set the right middle 2 finger joint pose of the user's avatar.
RightHandMiddle3 number Pose Set the right middle 3 finger joint pose of the user's avatar.
RightHandMiddle4 number Pose Set the right middle 4 finger joint pose of the user's avatar.
RightHandRing1 number Pose Set the right ring 1 finger joint pose of the user's avatar.
RightHandRing2 number Pose Set the right ring 2 finger joint pose of the user's avatar.
RightHandRing3 number Pose Set the right ring 3 finger joint pose of the user's avatar.
RightHandRing4 number Pose Set the right ring 4 finger joint pose of the user's avatar.
RightHandPinky1 number Pose Set the right pinky 1 finger joint pose of the user's avatar.
RightHandPinky2 number Pose Set the right pinky 2 finger joint pose of the user's avatar.
RightHandPinky3 number Pose Set the right pinky 3 finger joint pose of the user's avatar.
RightHandPinky4 number Pose Set the right pinky 4 finger joint pose of the user's avatar.
LeftFoot number Pose Set the left foot pose of the user's avatar.
RightFoot number Pose Set the right foot pose of the user's avatar.
Application
BoomIn number number Zoom camera in from third person toward first person view.
BoomOut number number Zoom camera out from first person to third person view.
CycleCamera number number Cycle the camera view from first person look at, to (third person) look at, to selfie if in desktop mode, then back to first person and repeat.
ContextMenu number number Show/hide the tablet.
ToggleMute number number Toggle the microphone mute.
TogglePushToTalk number number Toggle push to talk.
ToggleOverlay number number Toggle the display of overlays.
Sprint number number Set avatar sprint mode.
ReticleClick number number Set mouse-pressed.
ReticleX number number Move the cursor left/right in the x direction.
ReticleY number number move the cursor up/down in the y direction.
ReticleLeft number number Move the cursor left.
ReticleRight number number Move the cursor right.
ReticleUp number number Move the cursor up.
ReticleDown number number Move the cursor down.
UiNavLateral number number Generate a keyboard left or right arrow key event.
UiNavVertical number number Generate a keyboard up or down arrow key event.
UiNavGroup number number Generate a keyboard tab or back-tab key event.
UiNavSelect number number Generate a keyboard Enter key event.
UiNavBack number number Generate a keyboard Esc key event.
LeftHandClick number number Deprecated: This action is deprecated and will be removed. It takes no action.
RightHandClick number number Deprecated: This action is deprecated and will be removed. It takes no action.
Shift number number Deprecated: This action is deprecated and will be removed. It takes no action.
PrimaryAction number number Deprecated: This action is deprecated and will be removed. It takes no action.
SecondaryAction number number Deprecated: This action is deprecated and will be removed. It takes no action.
Aliases
Backward number number Alias for TranslateZ in the positive direction.
Forward number number Alias for TranslateZ in the negative direction.
StrafeRight number number Alias for TranslateX in the positive direction.
StrafeLeft number number Alias for TranslateX in the negative direction.
Up number number Alias for TranslateY in the positive direction.
Down number number Alias for TranslateY in the negative direction.
PitchDown number number Alias for Pitch in the positive direction.
PitchUp number number Alias for Pitch in the negative direction.
YawLeft number number Alias for Yaw in the positive direction.
YawRight number number Alias for Yaw in the negative direction.
Deprecated Aliases
LEFT_HAND number Pose Deprecated: This action is deprecated and will be removed. Use LeftHand instead.
RIGHT_HAND number Pose Deprecated: This action is deprecated and will be removed. Use RightHand instead.
BOOM_IN number number Deprecated: This action is deprecated and will be removed. Use BoomIn instead.
BOOM_OUT number number Deprecated: This action is deprecated and will be removed. Use BoomOut instead.
CONTEXT_MENU number number Deprecated: This action is deprecated and will be removed. Use ContextMenu instead.
TOGGLE_MUTE number number Deprecated: This action is deprecated and will be removed. Use ToggleMute instead.
TOGGLE_PUSHTOTALK number number Deprecated: This action is deprecated and will be removed. Use TogglePushToTalk instead.
SPRINT number number Deprecated: This action is deprecated and will be removed. Use Sprint instead.
LONGITUDINAL_BACKWARD number number Deprecated: This action is deprecated and will be removed. Use Backward instead.
LONGITUDINAL_FORWARD number number Deprecated: This action is deprecated and will be removed. Use Forward instead.
LATERAL_LEFT number number Deprecated: This action is deprecated and will be removed. Use StrafeLeft instead.
LATERAL_RIGHT number number Deprecated: This action is deprecated and will be removed. Use StrafeRight instead.
VERTICAL_UP number number Deprecated: This action is deprecated and will be removed. Use Up instead.
VERTICAL_DOWN number number Deprecated: This action is deprecated and will be removed. Use Down instead.
PITCH_DOWN number number Deprecated: This action is deprecated and will be removed. Use PitchDown instead.
PITCH_UP number number Deprecated: This action is deprecated and will be removed. Use PitchUp instead.
YAW_LEFT number number Deprecated: This action is deprecated and will be removed. Use YawLeft instead.
YAW_RIGHT number number Deprecated: This action is deprecated and will be removed. Use YawRight instead.
LEFT_HAND_CLICK number number Deprecated: This action is deprecated and will be removed. Use LeftHandClick instead.
RIGHT_HAND_CLICK number number Deprecated: This action is deprecated and will be removed. Use RightHandClick instead.
SHIFT number number Deprecated: This action is deprecated and will be removed. Use Shift instead.
ACTION1 number number Deprecated: This action is deprecated and will be removed. Use PrimaryAction instead.
ACTION2 number number Deprecated: This action is deprecated and will be removed. Use SecondaryAction instead.
Deprecated Trackers
TrackedObject00 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject01 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject02 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject03 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject04 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject05 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject06 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject07 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject08 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject09 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject10 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject11 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject12 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject13 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject14 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject15 number Pose Deprecated: This action is deprecated and will be removed. It takes no action.
Hand
Type: number

Some controller actions may be associated with one or both hands:

Value Description
0 Left hand.
1 Right hand.
2 Both hands.
Hardware
Type: object

The Controller.Hardware object has properties representing standard and hardware-specific controller and computer outputs, plus predefined actions on Interface and the user's avatar. Read-only.

The outputs can be mapped to actions or functions in a RouteObject mapping. Additionally, hardware-specific controller outputs can be mapped to standard controller outputs.

Controllers typically implement a subset of the Controller.Standard controls, plus they may implement some extras. Some common controllers are included in the table. You can see the outputs provided by these and others by viewing their MappingJSON files at https://github.com/highfidelity/hifi/tree/master/interface/resources/controllers.

Property Type Description
Controller.Hardware.Actions object Synonym for Controller.Actions.
Controller.Hardware.Application object Interface state outputs. See Controller.Hardware-Application.
Controller.Hardware.Keyboard object Keyboard, mouse, and touch pad outputs. See Controller.Hardware-Keyboard.
Controller.Hardware.OculusTouch object Oculus Rift HMD outputs. See Controller.Hardware-OculusTouch.
Controller.Hardware.Vive object Vive HMD outputs. See Controller.Hardware-Vive.
Example

List all the currently available Controller.Hardware properties. 

function printProperties(string, item) {
    print(string);
    for (var key in item) {
        if (item.hasOwnProperty(key)) {
            printProperties(string + "." + key, item[key]);
        }
    }
}

printProperties("Controller.Hardware", Controller.Hardware);
Hardware-Application
Type: object

The Controller.Hardware.Application object has properties representing Interface's state. The property values are integer IDs, uniquely identifying each output. Read-only.

These states can be mapped to actions or functions or Controller.Standard items in a RouteObject mapping (e.g., using the RouteObject#when method). Each data value is either 1.0 for "true" or 0.0 for "false".

Property Type Data Description
CameraFirstPerson number number The camera is in first-person mode. Legacy first person camera mode.
CameraFirstPersonLookAt number number The camera is in first-person mode. Default first person camera mode.
CameraThirdPerson number number The camera is in third-person mode. Legacy third person camera mode.
CameraLookAt number number The camera is in third-person mode. Default third person camera mode.
CameraFSM number number The camera is in full screen mirror mode. Legacy "look at myself" behavior.
CameraSelfie number number The camera is in selfie mode. Default "look at myself" camera mode.
CameraIndependent number number The camera is in independent mode.
CameraEntity number number The camera is in entity mode.
InHMD number number The user is in HMD mode.
CaptureMouse number number The mouse is captured. In this mode, the mouse is invisible and cannot leave the bounds of Interface, as long as Interface is the active window and no menu item is selected.
AdvancedMovement number number Advanced movement (walking) controls are enabled.
StrafeEnabled number number Strafing is enabled
LeftHandDominant number number Dominant hand set to left.
RightHandDominant number number Dominant hand set to right.
SnapTurn number number Snap turn is enabled.
Grounded number number The user's avatar is on the ground.
NavigationFocused number number Not used.
PlatformWindows number number The operating system is Windows.
PlatformMac number number The operating system is Mac.
PlatformAndroid number number The operating system is Android.
Hardware-Keyboard
Type: object

The Controller.Hardware.Keyboard object has properties representing keyboard, mouse, and display touch events. The property values are integer IDs, uniquely identifying each output. Read-only.

These events can be mapped to actions or functions or Controller.Standard items in a RouteObject mapping. For presses, each data value is either 1.0 for "true" or 0.0 for "false".

Property Type Data Description
0 – 9 number number A "0" – "1" key on the keyboard or keypad is pressed.
A – Z number number A "A" – "Z" key on the keyboard is pressed.
Space number number The space bar on the keyboard is pressed.
Tab number number The tab key on the keyboard is pressed.
Shift number number The shift key on the keyboard is pressed.
Control number number The control key on the keyboard is pressed. (The "Command" key on OSX.)
Left number number The left arrow key on the keyboard or keypad is pressed.
Right number number The right arrow key on the keyboard or keypad is pressed.
Up number number The up arrow key on the keyboard or keypad is pressed.
Down number number The down arrow key on the keyboard or keypad is pressed.
PgUp number number The page up key on the keyboard or keypad is pressed.
PgDown number number The page down key on the keyboard or keypad is pressed.
LeftMouseButton number number The left mouse button is pressed.
MiddleMouseButton number number The middle mouse button is pressed.
RightMouseButton number number The right mouse button is pressed.
LeftMouseClicked number number The left mouse button was clicked.
MiddleMouseClicked number number The middle mouse button was clicked.
RightMouseClicked number number The right mouse button was clicked.
MouseMoveRight number number The mouse moved right. The data value is how far it moved.
MouseMoveLeft number number The mouse moved left. The data value is how far it moved.
MouseMoveUp number number The mouse moved up. The data value is how far it moved.
MouseMoveDown number number The mouse moved down. The data value is how far it moved.
MouseX number number The mouse x-coordinate changed. The data value is its new x-coordinate value.
MouseY number number The mouse y-coordinate changed. The data value is its new y-coordinate value.
MouseWheelRight number number The mouse wheel rotated right or two-finger swipe moved right. The data value is the number of units moved (typically 1.0).
MouseWheelLeft number number The mouse wheel rotated left or two-finger swipe moved left. The data value is the number of units moved (typically 1.0).
MouseWheelUp number number The mouse wheel rotated up or two-finger swipe moved up. The data value is the number of units move3d (typically 1.0).

Warning: The mouse wheel in an ordinary mouse generates left/right wheel events instead of up/down.

MouseWheelDown number number The mouse wheel rotated down or two-finger swipe moved down. The data value is the number of units moved (typically 1.0).

Warning: The mouse wheel in an ordinary mouse generates left/right wheel events instead of up/down.

TouchpadRight number number The average touch on a touch-enabled device moved right. The data value is how far the average position of all touch points moved.
TouchpadLeft number number The average touch on a touch-enabled device moved left. The data value is how far the average position of all touch points moved.
TouchpadUp number number The average touch on a touch-enabled device moved up. The data value is how far the average position of all touch points moved.
TouchpadDown number number The average touch on a touch-enabled device moved down. The data value is how far the average position of all touch points moved.
GesturePinchOut number number The average of two touches on a touch-enabled device moved out. The data value is how far the average positions of the touch points moved out.
GesturePinchOut number number The average of two touches on a touch-enabled device moved in. The data value is how far the average positions of the touch points moved in.
Hardware-OculusTouch
Type: object

The Controller.Hardware.OculusTouch object has properties representing the Oculus Rift. The property values are integer IDs, uniquely identifying each output. Read-only.

These outputs can be mapped to actions or functions or Controller.Standard items in a RouteObject mapping.

Property Type Data Description
Buttons
A number number "A" button pressed.
B number number "B" button pressed.
X number number "X" button pressed.
Y number number "Y" button pressed.
LeftApplicationMenu number number Left application menu button pressed.
RightApplicationMenu number number Right application menu button pressed.
Sticks
LX number number Left stick x-axis scale.
LY number number Left stick y-axis scale.
RX number number Right stick x-axis scale.
RY number number Right stick y-axis scale.
LS number number Left stick button pressed.
RS number number Right stick button pressed.
LSTouch number number Left stick is touched.
RSTouch number number Right stick is touched.
Triggers
LT number number Left trigger scale.
RT number number Right trigger scale.
LeftGrip number number Left grip scale.
RightGrip number number Right grip scale.
Finger Abstractions
LeftPrimaryThumbTouch number number Left thumb touching primary thumb button.
LeftSecondaryThumbTouch number number Left thumb touching secondary thumb button.
LeftThumbUp number number Left thumb not touching primary or secondary thumb buttons.
RightPrimaryThumbTouch number number Right thumb touching primary thumb button.
RightSecondaryThumbTouch number number Right thumb touching secondary thumb button.
RightThumbUp number number Right thumb not touching primary or secondary thumb buttons.
LeftPrimaryIndexTouch number number Left index finger is touching primary index finger control.
LeftIndexPoint number number Left index finger is pointing, not touching primary or secondary index finger controls.
RightPrimaryIndexTouch number number Right index finger is touching primary index finger control.
RightIndexPoint number number Right index finger is pointing, not touching primary or secondary index finger controls.
Avatar Skeleton
Head number Pose Head pose.
LeftHand number Pose Left hand pose.
RightHand number Pose right hand pose.
Hardware-Vive
Type: object

The Controller.Hardware.Vive object has properties representing the Vive. The property values are integer IDs, uniquely identifying each output. Read-only.

These outputs can be mapped to actions or functions or Controller.Standard items in a RouteObject mapping.

Property Type Data Description
Buttons
LeftApplicationMenu number number Left application menu button pressed.
RightApplicationMenu number number Right application menu button pressed.
Touch Pad (Sticks)
LX number number Left touch pad x-axis scale.
LY number number Left touch pad y-axis scale.
RX number number Right stick x-axis scale.
RY number number Right stick y-axis scale.
LS number number Left touch pad pressed.
LSCenter number number Left touch pad center pressed.
LSX number number Left touch pad pressed x-coordinate.
LSY number number Left touch pad pressed y-coordinate.
RS number number Right touch pad pressed.
RSCenter number number Right touch pad center pressed.
RSX number number Right touch pad pressed x-coordinate.
RSY number number Right touch pad pressed y-coordinate.
LSTouch number number Left touch pad is touched.
RSTouch number number Right touch pad is touched.
Triggers
LT number number Left trigger scale.
RT number number Right trigger scale.
LTClick number number Left trigger click.
RTClick number number Right trigger click.
LeftGrip number number Left grip scale.
RightGrip number number Right grip scale.
Avatar Skeleton
Hips number Pose Hips pose.
Spine2 number Pose Spine2 pose.
Head number Pose Head pose.
LeftEye number Pose Left eye pose.
RightEye number Pose Right eye pose.
EyeBlink_L number number Left eyelid blink.
EyeBlink_R number number Right eyelid blink.
LeftArm number Pose Left arm pose.
RightArm number Pose Right arm pose
LeftHand number Pose Left hand pose.
LeftHandThumb1 number Pose Left thumb 1 finger joint pose.
LeftHandThumb2 number Pose Left thumb 2 finger joint pose.
LeftHandThumb3 number Pose Left thumb 3 finger joint pose.
LeftHandThumb4 number Pose Left thumb 4 finger joint pose.
LeftHandIndex1 number Pose Left index 1 finger joint pose.
LeftHandIndex2 number Pose Left index 2 finger joint pose.
LeftHandIndex3 number Pose Left index 3 finger joint pose.
LeftHandIndex4 number Pose Left index 4 finger joint pose.
LeftHandMiddle1 number Pose Left middle 1 finger joint pose.
LeftHandMiddle2 number Pose Left middle 2 finger joint pose.
LeftHandMiddle3 number Pose Left middle 3 finger joint pose.
LeftHandMiddle4 number Pose Left middle 4 finger joint pose.
LeftHandRing1 number Pose Left ring 1 finger joint pose.
LeftHandRing2 number Pose Left ring 2 finger joint pose.
LeftHandRing3 number Pose Left ring 3 finger joint pose.
LeftHandRing4 number Pose Left ring 4 finger joint pose.
LeftHandPinky1 number Pose Left pinky 1 finger joint pose.
LeftHandPinky2 number Pose Left pinky 2 finger joint pose.
LeftHandPinky3 number Pose Left pinky 3 finger joint pose.
LeftHandPinky4 number Pose Left pinky 4 finger joint pose.
RightHand number Pose Right hand pose.
RightHandThumb1 number Pose Right thumb 1 finger joint pose.
RightHandThumb2 number Pose Right thumb 2 finger joint pose.
RightHandThumb3 number Pose Right thumb 3 finger joint pose.
RightHandThumb4 number Pose Right thumb 4 finger joint pose.
RightHandIndex1 number Pose Right index 1 finger joint pose.
RightHandIndex2 number Pose Right index 2 finger joint pose.
RightHandIndex3 number Pose Right index 3 finger joint pose.
RightHandIndex4 number Pose Right index 4 finger joint pose.
RightHandMiddle1 number Pose Right middle 1 finger joint pose.
RightHandMiddle2 number Pose Right middle 2 finger joint pose.
RightHandMiddle3 number Pose Right middle 3 finger joint pose.
RightHandMiddle4 number Pose Right middle 4 finger joint pose.
RightHandRing1 number Pose Right ring 1 finger joint pose.
RightHandRing2 number Pose Right ring 2 finger joint pose.
RightHandRing3 number Pose Right ring 3 finger joint pose.
RightHandRing4 number Pose Right ring 4 finger joint pose.
RightHandPinky1 number Pose Right pinky 1 finger joint pose.
RightHandPinky2 number Pose Right pinky 2 finger joint pose.
RightHandPinky3 number Pose Right pinky 3 finger joint pose.
RightHandPinky4 number Pose Right pinky 4 finger joint pose.
Trackers
TrackedObject00 number Pose Tracker 0 pose.
TrackedObject01 number Pose Tracker 1 pose.
TrackedObject02 number Pose Tracker 2 pose.
TrackedObject03 number Pose Tracker 3 pose.
TrackedObject04 number Pose Tracker 4 pose.
TrackedObject05 number Pose Tracker 5 pose.
TrackedObject06 number Pose Tracker 6 pose.
TrackedObject07 number Pose Tracker 7 pose.
TrackedObject08 number Pose Tracker 8 pose.
TrackedObject09 number Pose Tracker 9 pose.
TrackedObject10 number Pose Tracker 10 pose.
TrackedObject11 number Pose Tracker 11 pose.
TrackedObject12 number Pose Tracker 12 pose.
TrackedObject13 number Pose Tracker 13 pose.
TrackedObject14 number Pose Tracker 14 pose.
TrackedObject15 number Pose Tracker 15 pose.
MappingJSON
Type: object

A MappingObject can be specified in JSON format. A simple example is provided below. Full examples — the default mappings provided in Interface — can be found at https://github.com/highfidelity/hifi/tree/master/interface/resources/controllers.

Properties

Name Type Summary
name string

The name of the mapping.

channels Array.<Controller.MappingJSONRoute>

An array of routes.

Example

A simple mapping JSON that makes the right trigger move your avatar up after a dead zone.

{
    "name": "com.vircadia.controllers.example.jsonMapping",
    "channels": [
        { 
            "from": "Standard.RT", 
            "filters": { "type": "deadZone", "min": 0.05 },
            "to": "Actions.TranslateY"
        }
    ]
}
MappingJSONAxis
Type: object

An axis pair in a Controller.MappingJSONRoute.

Properties

Name Type Summary
makeAxis Array.<Array.<string>>

A two-member array of single-member arrays of Controller.Hardware property names. The leading "Controller.Hardware." can be omitted from the property names.

Example

An axis using the keyboard's left and right keys.

{ "makeAxis" : [
        ["Keyboard.Left"],
        ["Keyboard.Right"]
    ]
}
MappingJSONFilter
Type: object

A filter in a Controller.MappingJSONRoute.

Properties

Name Type Attributes Summary
type string

The name of the filter, being the name of the one of the RouteObject's filter methods.

? string <optional>

If the filter method has a first parameter, the property name is the name of that parameter and the property value is the value to use.
? string <optional>

If the filter method has a second parameter, the property name is the name of that parameter and the property value is the value to use.
Example

A hysteresis filter.

{ 
    "type": "hysteresis", 
    "min": 0.85, 
    "max": 0.9
}
MappingJSONRoute
Type: object

A route in a Controller.MappingJSON.

Properties

Name Type Attributes Summary
from string | Controller.MappingJSONAxis

The name of a Controller.Hardware property or an axis made from them. If a property name, the leading "Controller.Hardware." can be omitted.

peek boolean <optional>

If true, then peeking is enabled per RouteObject#peek.

Default Value: false

debug boolean <optional>

If true, then debug is enabled per RouteObject#debug.

Default Value: false

when string | Array.<string> <optional>

One or more numeric Controller.Hardware property names which are evaluated as booleans and ANDed together. Prepend a property name with a ! to do a logical NOT. The leading "Controller.Hardware." can be omitted from the property names.

Default Value: []

filters Controller.MappingJSONFilter | Array.<Controller.MappingJSONFilter> <optional>

One or more filters in the route.

Default Value: []

to string

The name of a Controller.Actions or Controller.Standard property. The leading "Controller." can be omitted.

Standard
Type: object

The Controller.Standard object has properties representing standard controller outputs. Those for physical controllers are based on the XBox controller, with aliases for PlayStation. The property values are integer IDs, uniquely identifying each output. Read-only.

These outputs can be mapped to actions or functions in a RouteObject mapping. The data value provided by each control is either a number or a Pose. Numbers are typically normalized to 0.0 or 1.0 for button states, the range 0.0 – 1.0 for unidirectional scales, and the range -1.0 – 1.0 for bidirectional scales.

Each hardware device has a mapping from its outputs to a subset of Controller.Standard items, specified in a JSON file. For example, vive.json and leapmotion.json.

Property Type Data Description
Buttons
A number number "A" button pressed.
B number number "B" button pressed.
X number number "X" button pressed.
Y number number "Y" button pressed.
DL number number D-pad left pressed.
DR number number D-pad right pressed.
DU number number D-pad up pressed.
DD number number D-pad down pressed.
Start number number "Start" center button pressed.
Back number number "Back" center button pressed.
LB number number Left bumper button pressed.
RB number number Right bumper button pressed.
Sticks
LX number number Left stick x-axis scale.
LY number number Left stick y-axis scale.
RX number number Right stick x-axis scale.
RY number number Right stick y-axis scale.
LS number number Left stick button pressed.
RS number number Right stick button pressed.
LSTouch number number Left stick is touched.
RSTouch number number Right stick is touched.
Triggers
LT number number Left trigger scale.
RT number number Right trigger scale.
LTClick number number Left trigger click.
RTClick number number Right trigger click.
LeftGrip number number Left grip scale.
RightGrip number number Right grip scale.
LeftGripTouch number number Left grip is touched.
RightGripTouch number number Right grip is touched.
Aliases, PlayStation Style Names
Cross number number Alias for A.
Circle number number Alias for B.
Square number number Alias for X.
Triangle number number Alias for Y.
Left number number Alias for DL.
Right number number Alias for DR.
Up number number Alias for DU.
Down number number Alias for DD.
Select number number Alias for Back.
L1 number number Alias for LB.
R1 number number Alias for RB.
L3 number number Alias for LS.
R3 number number Alias for RS.
L2 number number Alias for LT.
R2 number number Alias for RT.
Finger Abstractions
LeftPrimaryThumb number number Left primary thumb button pressed.
LeftSecondaryThumb number number Left secondary thumb button pressed.
RightPrimaryThumb number number Right primary thumb button pressed.
RightSecondaryThumb number number Right secondary thumb button pressed.
LeftPrimaryThumbTouch number number Left thumb touching primary thumb button.
LeftSecondaryThumbTouch number number Left thumb touching secondary thumb button.
LeftThumbUp number number Left thumb not touching primary or secondary thumb buttons.
RightPrimaryThumbTouch number number Right thumb touching primary thumb button.
RightSecondaryThumbTouch number number Right thumb touching secondary thumb button.
RightThumbUp number number Right thumb not touching primary or secondary thumb buttons.
LeftPrimaryIndex number number Left primary index control pressed.
LeftSecondaryIndex number number Left secondary index control pressed.
RightPrimaryIndex number number Right primary index control pressed.
RightSecondaryIndex number number Right secondary index control pressed.
LeftPrimaryIndexTouch number number Left index finger is touching primary index finger control.
LeftSecondaryIndexTouch number number Left index finger is touching secondary index finger control.
LeftIndexPoint number number Left index finger is pointing, not touching primary or secondary index finger controls.
RightPrimaryIndexTouch number number Right index finger is touching primary index finger control.
RightSecondaryIndexTouch number number Right index finger is touching secondary index finger control.
RightIndexPoint number number Right index finger is pointing, not touching primary or secondary index finger controls.
Avatar Skeleton
Hips number Pose Hips pose.
Spine2 number Pose Spine2 pose.
Head number Pose Head pose.
LeftArm number Pose Left arm pose.
RightArm number Pose Right arm pose
LeftHand number Pose Left hand pose.
LeftHandThumb1 number Pose Left thumb 1 finger joint pose.
LeftHandThumb2 number Pose Left thumb 2 finger joint pose.
LeftHandThumb3 number Pose Left thumb 3 finger joint pose.
LeftHandThumb4 number Pose Left thumb 4 finger joint pose.
LeftHandIndex1 number Pose Left index 1 finger joint pose.
LeftHandIndex2 number Pose Left index 2 finger joint pose.
LeftHandIndex3 number Pose Left index 3 finger joint pose.
LeftHandIndex4 number Pose Left index 4 finger joint pose.
LeftHandMiddle1 number Pose Left middle 1 finger joint pose.
LeftHandMiddle2 number Pose Left middle 2 finger joint pose.
LeftHandMiddle3 number Pose Left middle 3 finger joint pose.
LeftHandMiddle4 number Pose Left middle 4 finger joint pose.
LeftHandRing1 number Pose Left ring 1 finger joint pose.
LeftHandRing2 number Pose Left ring 2 finger joint pose.
LeftHandRing3 number Pose Left ring 3 finger joint pose.
LeftHandRing4 number Pose Left ring 4 finger joint pose.
LeftHandPinky1 number Pose Left pinky 1 finger joint pose.
LeftHandPinky2 number Pose Left pinky 2 finger joint pose.
LeftHandPinky3 number Pose Left pinky 3 finger joint pose.
LeftHandPinky4 number Pose Left pinky 4 finger joint pose.
RightHand number Pose Right hand pose.
RightHandThumb1 number Pose Right thumb 1 finger joint pose.
RightHandThumb2 number Pose Right thumb 2 finger joint pose.
RightHandThumb3 number Pose Right thumb 3 finger joint pose.
RightHandThumb4 number Pose Right thumb 4 finger joint pose.
RightHandIndex1 number Pose Right index 1 finger joint pose.
RightHandIndex2 number Pose Right index 2 finger joint pose.
RightHandIndex3 number Pose Right index 3 finger joint pose.
RightHandIndex4 number Pose Right index 4 finger joint pose.
RightHandMiddle1 number Pose Right middle 1 finger joint pose.
RightHandMiddle2 number Pose Right middle 2 finger joint pose.
RightHandMiddle3 number Pose Right middle 3 finger joint pose.
RightHandMiddle4 number Pose Right middle 4 finger joint pose.
RightHandRing1 number Pose Right ring 1 finger joint pose.
RightHandRing2 number Pose Right ring 2 finger joint pose.
RightHandRing3 number Pose Right ring 3 finger joint pose.
RightHandRing4 number Pose Right ring 4 finger joint pose.
RightHandPinky1 number Pose Right pinky 1 finger joint pose.
RightHandPinky2 number Pose Right pinky 2 finger joint pose.
RightHandPinky3 number Pose Right pinky 3 finger joint pose.
RightHandPinky4 number Pose Right pinky 4 finger joint pose.
LeftFoot number Pose Left foot pose.
RightFoot number Pose Right foot pose.
Trackers
TrackedObject00 number Pose Tracker 0 pose.
TrackedObject01 number Pose Tracker 1 pose.
TrackedObject02 number Pose Tracker 2 pose.
TrackedObject03 number Pose Tracker 3 pose.
TrackedObject04 number Pose Tracker 4 pose.
TrackedObject05 number Pose Tracker 5 pose.
TrackedObject06 number Pose Tracker 6 pose.
TrackedObject07 number Pose Tracker 7 pose.
TrackedObject08 number Pose Tracker 8 pose.
TrackedObject09 number Pose Tracker 9 pose.
TrackedObject10 number Pose Tracker 10 pose.
TrackedObject11 number Pose Tracker 11 pose.
TrackedObject12 number Pose Tracker 12 pose.
TrackedObject13 number Pose Tracker 13 pose.
TrackedObject14 number Pose Tracker 14 pose.
TrackedObject15 number Pose Tracker 15 pose.

Method Details

(static) captureActionEvents( )

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);
(static) captureEntityClickEvents( )

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);
(static) captureJoystick( joystickID )

Disables default Interface actions for a joystick.

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

Parameters

Name Type Description
joystickID number

The integer ID of the joystick.

(static) captureKeyEvents( event )

Disables default Interface actions for a particular key event.

Parameters

Name Type Description
event KeyEvent

Details of the key event to be captured. The key property must be specified. The text property is ignored. The other properties default to false.

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);
});
(static) captureMouseEvents( )

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);
(static) captureTouchEvents( )

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

(static) captureWheelEvents( )

Disables processing of mouse wheel rotation events into Controller.Hardware.Keyboard outputs.
(static) disableMapping( mappingName )

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

Parameters

Name Type Description
mappingName string

The name of the mapping.

(static) enableMapping( mappingName, enableopt )

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

Parameters

Name Type Attributes Default Value Description
mappingName string

The name of the mapping.

enable boolean <optional>
 true

If true then the mapping is enabled, otherwise it is disabled.

(static) findAction( actionName ) → {number}
Returns: The integer ID of the action if found, otherwise 4095. Note that this value is not the same as the value of the relevant Controller.Actions property.

Finds the ID of an action from its name.

Parameters

Name Type Description
actionName string

The name of the action: one of the Controller.Actions property names.

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.
(static) findDevice( deviceName ) → {number}
Returns: The integer ID of the device if available, otherwise 65535.

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

Parameters

Name Type Description
deviceName string

The name of the device to find.

Example

Get the ID of the Oculus Touch.

var deviceID = Controller.findDevice("OculusTouch");
print("Device ID = " + deviceID);
(static) getActionNames( ) → {Array.<string>}
Returns: An array of action names.

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", ...
(static) getActions( ) → {Controller.Actions}
Returns: The Controller.Actions property tree.

Gets the Controller.Actions property tree. Calling this function is the same as using the Controller property, Controller.Actions.
(static) getActionValue( actionID ) → {number}
Returns: The current value of the action.

Gets the current value of an action.

Parameters

Name Type Description
actionID number

The integer ID of the action.

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);
(static) getAllActions( ) → {Array.<Action>}
Returns: All available actions.

Gets a list of all available actions.

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

(static) getAvailableInputs( deviceID ) → {Array.<NamedPair>}
Returns: All available inputs for the device.

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

Name Type Description
deviceID number

Integer ID of the hardware device.

(static) getAxisValue( source ) → {number}
Returns: The current value of the controller item output if source is valid, otherwise 0.

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

Parameters

Name Type Description
source number

The Controller.Standard or Controller.Hardware item.

(static) getDeviceName( deviceID ) → {string}
Returns: The name of the device if found, otherwise "unknown".

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

Parameters

Name Type Description
deviceID number

The integer ID of the device.

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);
(static) getDeviceNames( ) → {Array.<string>}
Returns: An array of device names.

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.
(static) getHardware( ) → {Controller.Hardware}
Returns: The Controller.Hardware property tree.

Gets the Controller.Hardware property tree. Calling this function is the same as using the Controller property, Controller.Hardware.
(static) getInputRecorderSaveDirectory( ) → {string}
Returns: The directory in which input recordings are saved.

Gets the directory in which input recordings are saved.
(static) getPoseValue( source ) → {Pose}
Returns: The current value of the controller pose output if source is a pose output, otherwise an invalid pose with Pose.valid == false.

Gets the value of a controller pose output.

Parameters

Name Type Description
source number

The Controller.Standard or Controller.Hardware pose output.

(static) getRecommendedHUDRect( ) → {Rect}
Returns: The recommended area in which to position UI.

Gets the recommended area to position UI on the HUD surface if in HMD mode or Interface's window interior if in desktop mode.
(static) getRunningInputDevices( ) → {Array.<string>}
Returns: The list of current active and running input devices.

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()));
(static) getStandard( ) → {Controller.Standard}
Returns: The Controller.Standard property tree.

Gets the Controller.Standard property tree. Calling this function is the same as using the Controller property, Controller.Standard.
(static) getValue( source ) → {number}
Returns: The current value of the controller item output if source is valid, otherwise 0.

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

Parameters

Name Type Description
source number

The Controller.Standard or Controller.Hardware item.

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");
}
(static) getViewportDimensions( ) → {Vec2}
Returns: The dimensions of the Interface window interior if in desktop mode or HUD surface if in HMD mode.

Gets the dimensions of the Interface window's interior if in desktop mode or the HUD surface if in HMD mode.
(static) loadInputRecording( file )

Loads an input recording, ready for play back.

Parameters

Name Type Description
file string

The path to the recording file, prefixed by "file:///".

(static) loadMapping( jsonURL ) → {MappingObject}
Returns: A controller mapping object.

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

Name Type Description
jsonURL string

The URL the MappingJSON JSON file.

(static) newMapping( mappingNameopt ) → {MappingObject}
Returns: A controller mapping object.

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

Name Type Attributes Default Value Description
mappingName string <optional>
 Uuid.generate()

A unique name for the mapping. If not specified a new UUID generated by Uuid.generate is used.

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);
});
(static) parseMapping( jsonString ) → {MappingObject}
Returns: A controller mapping object.

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

Parameters

Name Type Description
jsonString string

A JSON string of the MappingJSON.

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();
});
(static) releaseActionEvents( )

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

(static) releaseEntityClickEvents( )

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

(static) releaseJoystick( joystickID )

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

Name Type Description
joystickID number

The integer ID of the joystick.

(static) releaseKeyEvents( event )

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

Parameters

Name Type Description
event KeyEvent

Details of the key event to release from capture. The key property must be specified. The text property is ignored. The other properties default to false.

(static) releaseMouseEvents( )

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

(static) releaseTouchEvents( )

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.

(static) releaseWheelEvents( )

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

(static) saveInputRecording( )

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.

(static) setVPadEnabled( enable )

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

Parameters

Name Type Description
enable boolean

If true then the virtual game pad doesn't work, otherwise it does work provided that it is not hidden by setVPadHidden.

(static) setVPadExtraBottomMargin( margin )

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

Name Type Description
margin number

Integer number of pixels in the extra margin.

(static) setVPadHidden( hidden )

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

Parameters

Name Type Description
hidden boolean

If true then the virtual game pad is hidden, otherwise it is shown.

(static) startInputPlayback( )

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);
}
(static) startInputRecording( )

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);
(static) stopInputPlayback( )

Stops play back of a recording started by startInputPlayback.

(static) stopInputRecording( )

Stops making a recording started by startInputRecording.

(static) triggerHapticPulse( strength, duration, indexopt )

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

Parameters

Name Type Attributes Default Value Description
strength number

The strength of the haptic pulse, range 0.0 – 1.0.

duration number

The duration of the haptic pulse, in milliseconds.

index number <optional>
 2

The index on devices on which to trigger the haptic pulse. The meaning of each index will vary by device. For example, for hand controllers, index = 0 is the left hand, index = 1 is the right hand, and index = 2 is both hands. For other devices, such as haptic vests, index will have a different meaning, defined by the input device.

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);
(static) triggerHapticPulseOnDevice( deviceID, strength, duration, indexopt )

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

Parameters

Name Type Attributes Default Value Description
deviceID number

The ID of the device to trigger the haptic pulse on.
strength number

The strength of the haptic pulse, range 0.0 – 1.0.

duration number

The duration of the haptic pulse, in milliseconds.

index number <optional>
 2

The index on this device on which to trigger the haptic pulse. The meaning of each index will vary by device. For example, for hand controllers, index = 0 is the left hand, index = 1 is the right hand, and index = 2 is both hands. For other devices, such as haptic vests, index will have a different meaning, defined by the input device.

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);
(static) triggerShortHapticPulse( strength, indexopt )

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

Parameters

Name Type Attributes Default Value Description
strength number

The strength of the haptic pulse, range 0.0 – 1.0.

index number <optional>
 2

The index on devices on which to trigger the haptic pulse. The meaning of each index will vary by device. For example, for hand controllers, index = 0 is the left hand, index = 1 is the right hand, and index = 2 is both hands. For other devices, such as haptic vests, index will have a different meaning, defined by the input device.

(static) triggerShortHapticPulseOnDevice( deviceID, strength, indexopt )

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

Parameters

Name Type Attributes Default Value Description
deviceID number

The ID of the device to trigger the haptic pulse on.
strength number

The strength of the haptic pulse, range 0.0 – 1.0.

index number <optional>
 2

The index on this device on which to trigger the haptic pulse. The meaning of each index will vary by device. For example, for hand controllers, index = 0 is the left hand, index = 1 is the right hand, and index = 2 is both hands. For other devices, such as haptic vests, index will have a different meaning, defined by the input device.

(static) updateRunningInputDevices( deviceName, isRunning, runningDevices )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
deviceName string

Device name.

isRunning boolean

Is running.

runningDevices Array.<string>

Running devices.

Signal Details

actionEvent( actionID, value )
Returns: Signal

Triggered when an action occurs.

Parameters

Name Type Description
actionID number

The ID of the action, per findAction.

value number

The value associated with the action.

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);
});
hardwareChanged( )
Returns: Signal

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.

inputDeviceRunningChanged( deviceName, isRunning )
Returns: Signal

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

Name Type Description
deviceName string

The name of the device.

isRunning boolean

true if the device is active and running, false if it isn't.

inputEvent( action, value )
Returns: Signal

Triggered when there is a new controller input event.

Parameters

Name Type Description
action number

The input action, per Controller.Standard.

value number

The value associated with the input action.

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);
});
keyPressEvent( event )
Returns: Signal

Triggered when a keyboard key is pressed.

Parameters

Name Type Description
event KeyEvent

Details of the key press.

Example

Report the KeyEvent details for each key press.

Controller.keyPressEvent.connect(function (event) {
    print(JSON.stringify(event));
});
keyReleaseEvent( event )
Returns: Signal

Triggered when a keyboard key is released from being pressed.

Parameters

Name Type Description
event KeyEvent

Details of the key release.

mouseDoublePressEvent( event )
Returns: Signal

Triggered when a mouse button is double-pressed.

Parameters

Name Type Description
event MouseEvent

Details of the button double-press.

mouseMoveEvent( event )
Returns: Signal

Triggered when the mouse moves.

Parameters

Name Type Description
event MouseEvent

Details of the mouse movement.

Example

Report the MouseEvent details for each mouse move.

Controller.mouseMoveEvent.connect(function (event) {
    print(JSON.stringify(event));
});
mousePressEvent( event )
Returns: Signal

Triggered when a mouse button is pressed.

Parameters

Name Type Description
event MouseEvent

Details of the button press.

mouseReleaseEvent( event )
Returns: Signal

Triggered when a mouse button is released from being pressed.

Parameters

Name Type Description
event MouseEvent

Details of the button release.

touchBeginEvent( event )
Returns: Signal

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

Parameters

Name Type Description
event TouchEvent

Details of the touch begin.

Example

Report the TouchEvent details when a touch event starts.

Controller.touchBeginEvent.connect(function (event) {
    print(JSON.stringify(event));
});
touchEndEvent( event )
Returns: Signal

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

Parameters

Name Type Description
event TouchEvent

Details of the touch end.
touchUpdateEvent( event )
Returns: Signal

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

Parameters

Name Type Description
event TouchEvent

Details of the touch update.

wheelEvent( event )
Returns: Signal

Triggered when the mouse wheel is rotated.

Parameters

Name Type Description
event WheelEvent

Details of the wheel movement.

Example

Report the WheelEvent details for each wheel rotation.

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