Controller

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

PropertyTypeDataDescription
Avatar Movement
TranslateXnumbernumberMove the user's avatar in the direction of its x-axis, if the camera isn't in independent or mirror modes.
TranslateYnumbernumberMove the user's avatar in the direction of its y-axis, if the camera isn't in independent or mirror modes.
TranslateZnumbernumberMove the user's avatar in the direction of its z-axis, if the camera isn't in independent or mirror modes.
PitchnumbernumberRotate 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.
YawnumbernumberRotate 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.
RollnumbernumberNo action.
DeltaPitchnumbernumberRotate 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.
DeltaYawnumbernumberRotate 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.
DeltaRollnumbernumberNo action.
StepTranslateXnumbernumberNo action.
StepTranslateYnumbernumberNo action.
StepTranslateZnumbernumberNo action.
StepPitchnumbernumberNo action.
StepYawnumbernumberRotate the user's avatar about its y-axis in a step increment, if the camera isn't in independent or mirror modes.
StepRollnumbernumberNo action.
Avatar Skeleton
HipsnumberPoseSet the hips pose of the user's avatar.
Spine2numberPoseSet the spine2 pose of the user's avatar.
HeadnumberPoseSet the head pose of the user's avatar.
LeftArmnumberPoseSet the left arm pose of the user's avatar.
RightArmnumberPoseSet the right arm pose of the user's avatar.
LeftHandnumberPoseSet the left hand pose of the user's avatar.
LeftHandThumb1numberPoseSet the left thumb 1 finger joint pose of the user's avatar.
LeftHandThumb2numberPoseSet the left thumb 2 finger joint pose of the user's avatar.
LeftHandThumb3numberPoseSet the left thumb 3 finger joint pose of the user's avatar.
LeftHandThumb4numberPoseSet the left thumb 4 finger joint pose of the user's avatar.
LeftHandIndex1numberPoseSet the left index 1 finger joint pose of the user's avatar.
LeftHandIndex2numberPoseSet the left index 2 finger joint pose of the user's avatar.
LeftHandIndex3numberPoseSet the left index 3 finger joint pose of the user's avatar.
LeftHandIndex4numberPoseSet the left index 4 finger joint pose of the user's avatar.
LeftHandMiddle1numberPoseSet the left middle 1 finger joint pose of the user's avatar.
LeftHandMiddle2numberPoseSet the left middle 2 finger joint pose of the user's avatar.
LeftHandMiddle3numberPoseSet the left middle 3 finger joint pose of the user's avatar.
LeftHandMiddle4numberPoseSet the left middle 4 finger joint pose of the user's avatar.
LeftHandRing1numberPoseSet the left ring 1 finger joint pose of the user's avatar.
LeftHandRing2numberPoseSet the left ring 2 finger joint pose of the user's avatar.
LeftHandRing3numberPoseSet the left ring 3 finger joint pose of the user's avatar.
LeftHandRing4numberPoseSet the left ring 4 finger joint pose of the user's avatar.
LeftHandPinky1numberPoseSet the left pinky 1 finger joint pose of the user's avatar.
LeftHandPinky2numberPoseSet the left pinky 2 finger joint pose of the user's avatar.
LeftHandPinky3numberPoseSet the left pinky 3 finger joint pose of the user's avatar.
LeftHandPinky4numberPoseSet the left pinky 4 finger joint pose of the user's avatar.
RightHandnumberPoseSet the right hand of the user's avatar.
RightHandThumb1numberPoseSet the right thumb 1 finger joint pose of the user's avatar.
RightHandThumb2numberPoseSet the right thumb 2 finger joint pose of the user's avatar.
RightHandThumb3numberPoseSet the right thumb 3 finger joint pose of the user's avatar.
RightHandThumb4numberPoseSet the right thumb 4 finger joint pose of the user's avatar.
RightHandIndex1numberPoseSet the right index 1 finger joint pose of the user's avatar.
RightHandIndex2numberPoseSet the right index 2 finger joint pose of the user's avatar.
RightHandIndex3numberPoseSet the right index 3 finger joint pose of the user's avatar.
RightHandIndex4numberPoseSet the right index 4 finger joint pose of the user's avatar.
RightHandMiddle1numberPoseSet the right middle 1 finger joint pose of the user's avatar.
RightHandMiddle2numberPoseSet the right middle 2 finger joint pose of the user's avatar.
RightHandMiddle3numberPoseSet the right middle 3 finger joint pose of the user's avatar.
RightHandMiddle4numberPoseSet the right middle 4 finger joint pose of the user's avatar.
RightHandRing1numberPoseSet the right ring 1 finger joint pose of the user's avatar.
RightHandRing2numberPoseSet the right ring 2 finger joint pose of the user's avatar.
RightHandRing3numberPoseSet the right ring 3 finger joint pose of the user's avatar.
RightHandRing4numberPoseSet the right ring 4 finger joint pose of the user's avatar.
RightHandPinky1numberPoseSet the right pinky 1 finger joint pose of the user's avatar.
RightHandPinky2numberPoseSet the right pinky 2 finger joint pose of the user's avatar.
RightHandPinky3numberPoseSet the right pinky 3 finger joint pose of the user's avatar.
RightHandPinky4numberPoseSet the right pinky 4 finger joint pose of the user's avatar.
LeftFootnumberPoseSet the left foot pose of the user's avatar.
RightFootnumberPoseSet the right foot pose of the user's avatar.
Application
BoomInnumbernumberZoom camera in from third person toward first person view.
BoomOutnumbernumberZoom camera out from first person to third person view.
CycleCameranumbernumberCycle 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.
ContextMenunumbernumberShow/hide the tablet.
ToggleMutenumbernumberToggle the microphone mute.
TogglePushToTalknumbernumberToggle push to talk.
ToggleOverlaynumbernumberToggle the display of overlays.
SprintnumbernumberSet avatar sprint mode.
ReticleClicknumbernumberSet mouse-pressed.
ReticleXnumbernumberMove the cursor left/right in the x direction.
ReticleYnumbernumbermove the cursor up/down in the y direction.
ReticleLeftnumbernumberMove the cursor left.
ReticleRightnumbernumberMove the cursor right.
ReticleUpnumbernumberMove the cursor up.
ReticleDownnumbernumberMove the cursor down.
UiNavLateralnumbernumberGenerate a keyboard left or right arrow key event.
UiNavVerticalnumbernumberGenerate a keyboard up or down arrow key event.
UiNavGroupnumbernumberGenerate a keyboard tab or back-tab key event.
UiNavSelectnumbernumberGenerate a keyboard Enter key event.
UiNavBacknumbernumberGenerate a keyboard Esc key event.
LeftHandClicknumbernumberDeprecated: This action is deprecated and will be removed. It takes no action.
RightHandClicknumbernumberDeprecated: This action is deprecated and will be removed. It takes no action.
ShiftnumbernumberDeprecated: This action is deprecated and will be removed. It takes no action.
PrimaryActionnumbernumberDeprecated: This action is deprecated and will be removed. It takes no action.
SecondaryActionnumbernumberDeprecated: This action is deprecated and will be removed. It takes no action.
Aliases
BackwardnumbernumberAlias for TranslateZ in the positive direction.
ForwardnumbernumberAlias for TranslateZ in the negative direction.
StrafeRightnumbernumberAlias for TranslateX in the positive direction.
StrafeLeftnumbernumberAlias for TranslateX in the negative direction.
UpnumbernumberAlias for TranslateY in the positive direction.
DownnumbernumberAlias for TranslateY in the negative direction.
PitchDownnumbernumberAlias for Pitch in the positive direction.
PitchUpnumbernumberAlias for Pitch in the negative direction.
YawLeftnumbernumberAlias for Yaw in the positive direction.
YawRightnumbernumberAlias for Yaw in the negative direction.
Deprecated Aliases
LEFT_HANDnumberPoseDeprecated: This action is deprecated and will be removed. Use LeftHand instead.
RIGHT_HANDnumberPoseDeprecated: This action is deprecated and will be removed. Use RightHand instead.
BOOM_INnumbernumberDeprecated: This action is deprecated and will be removed. Use BoomIn instead.
BOOM_OUTnumbernumberDeprecated: This action is deprecated and will be removed. Use BoomOut instead.
CONTEXT_MENUnumbernumberDeprecated: This action is deprecated and will be removed. Use ContextMenu instead.
TOGGLE_MUTEnumbernumberDeprecated: This action is deprecated and will be removed. Use ToggleMute instead.
TOGGLE_PUSHTOTALKnumbernumberDeprecated: This action is deprecated and will be removed. Use TogglePushToTalk instead.
SPRINTnumbernumberDeprecated: This action is deprecated and will be removed. Use Sprint instead.
LONGITUDINAL_BACKWARDnumbernumberDeprecated: This action is deprecated and will be removed. Use Backward instead.
LONGITUDINAL_FORWARDnumbernumberDeprecated: This action is deprecated and will be removed. Use Forward instead.
LATERAL_LEFTnumbernumberDeprecated: This action is deprecated and will be removed. Use StrafeLeft instead.
LATERAL_RIGHTnumbernumberDeprecated: This action is deprecated and will be removed. Use StrafeRight instead.
VERTICAL_UPnumbernumberDeprecated: This action is deprecated and will be removed. Use Up instead.
VERTICAL_DOWNnumbernumberDeprecated: This action is deprecated and will be removed. Use Down instead.
PITCH_DOWNnumbernumberDeprecated: This action is deprecated and will be removed. Use PitchDown instead.
PITCH_UPnumbernumberDeprecated: This action is deprecated and will be removed. Use PitchUp instead.
YAW_LEFTnumbernumberDeprecated: This action is deprecated and will be removed. Use YawLeft instead.
YAW_RIGHTnumbernumberDeprecated: This action is deprecated and will be removed. Use YawRight instead.
LEFT_HAND_CLICKnumbernumberDeprecated: This action is deprecated and will be removed. Use LeftHandClick instead.
RIGHT_HAND_CLICKnumbernumberDeprecated: This action is deprecated and will be removed. Use RightHandClick instead.
SHIFTnumbernumberDeprecated: This action is deprecated and will be removed. Use Shift instead.
ACTION1numbernumberDeprecated: This action is deprecated and will be removed. Use PrimaryAction instead.
ACTION2numbernumberDeprecated: This action is deprecated and will be removed. Use SecondaryAction instead.
Deprecated Trackers
TrackedObject00numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject01numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject02numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject03numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject04numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject05numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject06numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject07numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject08numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject09numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject10numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject11numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject12numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject13numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject14numberPoseDeprecated: This action is deprecated and will be removed. It takes no action.
TrackedObject15numberPoseDeprecated: 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:

ValueDescription
0Left hand.
1Right hand.
2Both 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.

PropertyTypeDescription
Controller.Hardware.ActionsobjectSynonym for Controller.Actions.
Controller.Hardware.ApplicationobjectInterface state outputs. See Controller.Hardware-Application.
Controller.Hardware.KeyboardobjectKeyboard, mouse, and touch pad outputs. See Controller.Hardware-Keyboard.
Controller.Hardware.OculusTouchobjectOculus Rift HMD outputs. See Controller.Hardware-OculusTouch.
Controller.Hardware.ViveobjectVive 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".

PropertyTypeDataDescription
CameraFirstPersonnumbernumberThe camera is in first-person mode. Legacy first person camera mode.
CameraFirstPersonLookAtnumbernumberThe camera is in first-person mode. Default first person camera mode.
CameraThirdPersonnumbernumberThe camera is in third-person mode. Legacy third person camera mode.
CameraLookAtnumbernumberThe camera is in third-person mode. Default third person camera mode.
CameraFSMnumbernumberThe camera is in full screen mirror mode. Legacy "look at myself" behavior.
CameraSelfienumbernumberThe camera is in selfie mode. Default "look at myself" camera mode.
CameraIndependentnumbernumberThe camera is in independent mode.
CameraEntitynumbernumberThe camera is in entity mode.
InHMDnumbernumberThe user is in HMD mode.
CaptureMousenumbernumberThe 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.
AdvancedMovementnumbernumberAdvanced movement (walking) controls are enabled.
StrafeEnablednumbernumberStrafing is enabled
LeftHandDominantnumbernumberDominant hand set to left.
RightHandDominantnumbernumberDominant hand set to right.
SnapTurnnumbernumberSnap turn is enabled.
GroundednumbernumberThe user's avatar is on the ground.
NavigationFocusednumbernumberNot used.
PlatformWindowsnumbernumberThe operating system is Windows.
PlatformMacnumbernumberThe operating system is Mac.
PlatformAndroidnumbernumberThe 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".

PropertyTypeDataDescription
09numbernumberA "0" – "1" key on the keyboard or keypad is pressed.
AZnumbernumberA "A" – "Z" key on the keyboard is pressed.
SpacenumbernumberThe space bar on the keyboard is pressed.
TabnumbernumberThe tab key on the keyboard is pressed.
ShiftnumbernumberThe shift key on the keyboard is pressed.
ControlnumbernumberThe control key on the keyboard is pressed. (The "Command" key on OSX.)
LeftnumbernumberThe left arrow key on the keyboard or keypad is pressed.
RightnumbernumberThe right arrow key on the keyboard or keypad is pressed.
UpnumbernumberThe up arrow key on the keyboard or keypad is pressed.
DownnumbernumberThe down arrow key on the keyboard or keypad is pressed.
PgUpnumbernumberThe page up key on the keyboard or keypad is pressed.
PgDownnumbernumberThe page down key on the keyboard or keypad is pressed.
LeftMouseButtonnumbernumberThe left mouse button is pressed.
MiddleMouseButtonnumbernumberThe middle mouse button is pressed.
RightMouseButtonnumbernumberThe right mouse button is pressed.
LeftMouseClickednumbernumberThe left mouse button was clicked.
MiddleMouseClickednumbernumberThe middle mouse button was clicked.
RightMouseClickednumbernumberThe right mouse button was clicked.
MouseMoveRightnumbernumberThe mouse moved right. The data value is how far it moved.
MouseMoveLeftnumbernumberThe mouse moved left. The data value is how far it moved.
MouseMoveUpnumbernumberThe mouse moved up. The data value is how far it moved.
MouseMoveDownnumbernumberThe mouse moved down. The data value is how far it moved.
MouseXnumbernumberThe mouse x-coordinate changed. The data value is its new x-coordinate value.
MouseYnumbernumberThe mouse y-coordinate changed. The data value is its new y-coordinate value.
MouseWheelRightnumbernumberThe mouse wheel rotated right or two-finger swipe moved right. The data value is the number of units moved (typically 1.0).
MouseWheelLeftnumbernumberThe mouse wheel rotated left or two-finger swipe moved left. The data value is the number of units moved (typically 1.0).
MouseWheelUpnumbernumberThe 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.

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

TouchpadRightnumbernumberThe average touch on a touch-enabled device moved right. The data value is how far the average position of all touch points moved.
TouchpadLeftnumbernumberThe average touch on a touch-enabled device moved left. The data value is how far the average position of all touch points moved.
TouchpadUpnumbernumberThe average touch on a touch-enabled device moved up. The data value is how far the average position of all touch points moved.
TouchpadDownnumbernumberThe average touch on a touch-enabled device moved down. The data value is how far the average position of all touch points moved.
GesturePinchOutnumbernumberThe 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.
GesturePinchOutnumbernumberThe 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.

PropertyTypeDataDescription
Buttons
Anumbernumber"A" button pressed.
Bnumbernumber"B" button pressed.
Xnumbernumber"X" button pressed.
Ynumbernumber"Y" button pressed.
LeftApplicationMenunumbernumberLeft application menu button pressed.
RightApplicationMenunumbernumberRight application menu button pressed.
Sticks
LXnumbernumberLeft stick x-axis scale.
LYnumbernumberLeft stick y-axis scale.
RXnumbernumberRight stick x-axis scale.
RYnumbernumberRight stick y-axis scale.
LSnumbernumberLeft stick button pressed.
RSnumbernumberRight stick button pressed.
LSTouchnumbernumberLeft stick is touched.
RSTouchnumbernumberRight stick is touched.
Triggers
LTnumbernumberLeft trigger scale.
RTnumbernumberRight trigger scale.
LeftGripnumbernumberLeft grip scale.
RightGripnumbernumberRight grip scale.
Finger Abstractions
LeftPrimaryThumbTouchnumbernumberLeft thumb touching primary thumb button.
LeftSecondaryThumbTouchnumbernumberLeft thumb touching secondary thumb button.
LeftThumbUpnumbernumberLeft thumb not touching primary or secondary thumb buttons.
RightPrimaryThumbTouchnumbernumberRight thumb touching primary thumb button.
RightSecondaryThumbTouchnumbernumberRight thumb touching secondary thumb button.
RightThumbUpnumbernumberRight thumb not touching primary or secondary thumb buttons.
LeftPrimaryIndexTouchnumbernumberLeft index finger is touching primary index finger control.
LeftIndexPointnumbernumberLeft index finger is pointing, not touching primary or secondary index finger controls.
RightPrimaryIndexTouchnumbernumberRight index finger is touching primary index finger control.
RightIndexPointnumbernumberRight index finger is pointing, not touching primary or secondary index finger controls.
Avatar Skeleton
HeadnumberPoseHead pose.
LeftHandnumberPoseLeft hand pose.
RightHandnumberPoseright 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.

PropertyTypeDataDescription
Buttons
LeftApplicationMenunumbernumberLeft application menu button pressed.
RightApplicationMenunumbernumberRight application menu button pressed.
Touch Pad (Sticks)
LXnumbernumberLeft touch pad x-axis scale.
LYnumbernumberLeft touch pad y-axis scale.
RXnumbernumberRight stick x-axis scale.
RYnumbernumberRight stick y-axis scale.
LSnumbernumberLeft touch pad pressed.
LSCenternumbernumberLeft touch pad center pressed.
LSXnumbernumberLeft touch pad pressed x-coordinate.
LSYnumbernumberLeft touch pad pressed y-coordinate.
RSnumbernumberRight touch pad pressed.
RSCenternumbernumberRight touch pad center pressed.
RSXnumbernumberRight touch pad pressed x-coordinate.
RSYnumbernumberRight touch pad pressed y-coordinate.
LSTouchnumbernumberLeft touch pad is touched.
RSTouchnumbernumberRight touch pad is touched.
Triggers
LTnumbernumberLeft trigger scale.
RTnumbernumberRight trigger scale.
LTClicknumbernumberLeft trigger click.
RTClicknumbernumberRight trigger click.
LeftGripnumbernumberLeft grip scale.
RightGripnumbernumberRight grip scale.
Avatar Skeleton
HipsnumberPoseHips pose.
Spine2numberPoseSpine2 pose.
HeadnumberPoseHead pose.
LeftEyenumberPoseLeft eye pose.
RightEyenumberPoseRight eye pose.
EyeBlink_LnumbernumberLeft eyelid blink.
EyeBlink_RnumbernumberRight eyelid blink.
LeftArmnumberPoseLeft arm pose.
RightArmnumberPoseRight arm pose
LeftHandnumberPoseLeft hand pose.
LeftHandThumb1numberPoseLeft thumb 1 finger joint pose.
LeftHandThumb2numberPoseLeft thumb 2 finger joint pose.
LeftHandThumb3numberPoseLeft thumb 3 finger joint pose.
LeftHandThumb4numberPoseLeft thumb 4 finger joint pose.
LeftHandIndex1numberPoseLeft index 1 finger joint pose.
LeftHandIndex2numberPoseLeft index 2 finger joint pose.
LeftHandIndex3numberPoseLeft index 3 finger joint pose.
LeftHandIndex4numberPoseLeft index 4 finger joint pose.
LeftHandMiddle1numberPoseLeft middle 1 finger joint pose.
LeftHandMiddle2numberPoseLeft middle 2 finger joint pose.
LeftHandMiddle3numberPoseLeft middle 3 finger joint pose.
LeftHandMiddle4numberPoseLeft middle 4 finger joint pose.
LeftHandRing1numberPoseLeft ring 1 finger joint pose.
LeftHandRing2numberPoseLeft ring 2 finger joint pose.
LeftHandRing3numberPoseLeft ring 3 finger joint pose.
LeftHandRing4numberPoseLeft ring 4 finger joint pose.
LeftHandPinky1numberPoseLeft pinky 1 finger joint pose.
LeftHandPinky2numberPoseLeft pinky 2 finger joint pose.
LeftHandPinky3numberPoseLeft pinky 3 finger joint pose.
LeftHandPinky4numberPoseLeft pinky 4 finger joint pose.
RightHandnumberPoseRight hand pose.
RightHandThumb1numberPoseRight thumb 1 finger joint pose.
RightHandThumb2numberPoseRight thumb 2 finger joint pose.
RightHandThumb3numberPoseRight thumb 3 finger joint pose.
RightHandThumb4numberPoseRight thumb 4 finger joint pose.
RightHandIndex1numberPoseRight index 1 finger joint pose.
RightHandIndex2numberPoseRight index 2 finger joint pose.
RightHandIndex3numberPoseRight index 3 finger joint pose.
RightHandIndex4numberPoseRight index 4 finger joint pose.
RightHandMiddle1numberPoseRight middle 1 finger joint pose.
RightHandMiddle2numberPoseRight middle 2 finger joint pose.
RightHandMiddle3numberPoseRight middle 3 finger joint pose.
RightHandMiddle4numberPoseRight middle 4 finger joint pose.
RightHandRing1numberPoseRight ring 1 finger joint pose.
RightHandRing2numberPoseRight ring 2 finger joint pose.
RightHandRing3numberPoseRight ring 3 finger joint pose.
RightHandRing4numberPoseRight ring 4 finger joint pose.
RightHandPinky1numberPoseRight pinky 1 finger joint pose.
RightHandPinky2numberPoseRight pinky 2 finger joint pose.
RightHandPinky3numberPoseRight pinky 3 finger joint pose.
RightHandPinky4numberPoseRight pinky 4 finger joint pose.
Trackers
TrackedObject00numberPoseTracker 0 pose.
TrackedObject01numberPoseTracker 1 pose.
TrackedObject02numberPoseTracker 2 pose.
TrackedObject03numberPoseTracker 3 pose.
TrackedObject04numberPoseTracker 4 pose.
TrackedObject05numberPoseTracker 5 pose.
TrackedObject06numberPoseTracker 6 pose.
TrackedObject07numberPoseTracker 7 pose.
TrackedObject08numberPoseTracker 8 pose.
TrackedObject09numberPoseTracker 9 pose.
TrackedObject10numberPoseTracker 10 pose.
TrackedObject11numberPoseTracker 11 pose.
TrackedObject12numberPoseTracker 12 pose.
TrackedObject13numberPoseTracker 13 pose.
TrackedObject14numberPoseTracker 14 pose.
TrackedObject15numberPoseTracker 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.01.0 for unidirectional scales, and the range -1.01.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.

PropertyTypeDataDescription
Buttons
Anumbernumber"A" button pressed.
Bnumbernumber"B" button pressed.
Xnumbernumber"X" button pressed.
Ynumbernumber"Y" button pressed.
DLnumbernumberD-pad left pressed.
DRnumbernumberD-pad right pressed.
DUnumbernumberD-pad up pressed.
DDnumbernumberD-pad down pressed.
Startnumbernumber"Start" center button pressed.
Backnumbernumber"Back" center button pressed.
LBnumbernumberLeft bumper button pressed.
RBnumbernumberRight bumper button pressed.
Sticks
LXnumbernumberLeft stick x-axis scale.
LYnumbernumberLeft stick y-axis scale.
RXnumbernumberRight stick x-axis scale.
RYnumbernumberRight stick y-axis scale.
LSnumbernumberLeft stick button pressed.
RSnumbernumberRight stick button pressed.
LSTouchnumbernumberLeft stick is touched.
RSTouchnumbernumberRight stick is touched.
Triggers
LTnumbernumberLeft trigger scale.
RTnumbernumberRight trigger scale.
LTClicknumbernumberLeft trigger click.
RTClicknumbernumberRight trigger click.
LeftGripnumbernumberLeft grip scale.
RightGripnumbernumberRight grip scale.
LeftGripTouchnumbernumberLeft grip is touched.
RightGripTouchnumbernumberRight grip is touched.
Aliases, PlayStation Style Names
CrossnumbernumberAlias for A.
CirclenumbernumberAlias for B.
SquarenumbernumberAlias for X.
TrianglenumbernumberAlias for Y.
LeftnumbernumberAlias for DL.
RightnumbernumberAlias for DR.
UpnumbernumberAlias for DU.
DownnumbernumberAlias for DD.
SelectnumbernumberAlias for Back.
L1numbernumberAlias for LB.
R1numbernumberAlias for RB.
L3numbernumberAlias for LS.
R3numbernumberAlias for RS.
L2numbernumberAlias for LT.
R2numbernumberAlias for RT.
Finger Abstractions
LeftPrimaryThumbnumbernumberLeft primary thumb button pressed.
LeftSecondaryThumbnumbernumberLeft secondary thumb button pressed.
RightPrimaryThumbnumbernumberRight primary thumb button pressed.
RightSecondaryThumbnumbernumberRight secondary thumb button pressed.
LeftPrimaryThumbTouchnumbernumberLeft thumb touching primary thumb button.
LeftSecondaryThumbTouchnumbernumberLeft thumb touching secondary thumb button.
LeftThumbUpnumbernumberLeft thumb not touching primary or secondary thumb buttons.
RightPrimaryThumbTouchnumbernumberRight thumb touching primary thumb button.
RightSecondaryThumbTouchnumbernumberRight thumb touching secondary thumb button.
RightThumbUpnumbernumberRight thumb not touching primary or secondary thumb buttons.
LeftPrimaryIndexnumbernumberLeft primary index control pressed.
LeftSecondaryIndexnumbernumberLeft secondary index control pressed.
RightPrimaryIndexnumbernumberRight primary index control pressed.
RightSecondaryIndexnumbernumberRight secondary index control pressed.
LeftPrimaryIndexTouchnumbernumberLeft index finger is touching primary index finger control.
LeftSecondaryIndexTouchnumbernumberLeft index finger is touching secondary index finger control.
LeftIndexPointnumbernumberLeft index finger is pointing, not touching primary or secondary index finger controls.
RightPrimaryIndexTouchnumbernumberRight index finger is touching primary index finger control.
RightSecondaryIndexTouchnumbernumberRight index finger is touching secondary index finger control.
RightIndexPointnumbernumberRight index finger is pointing, not touching primary or secondary index finger controls.
Avatar Skeleton
HipsnumberPoseHips pose.
Spine2numberPoseSpine2 pose.
HeadnumberPoseHead pose.
LeftArmnumberPoseLeft arm pose.
RightArmnumberPoseRight arm pose
LeftHandnumberPoseLeft hand pose.
LeftHandThumb1numberPoseLeft thumb 1 finger joint pose.
LeftHandThumb2numberPoseLeft thumb 2 finger joint pose.
LeftHandThumb3numberPoseLeft thumb 3 finger joint pose.
LeftHandThumb4numberPoseLeft thumb 4 finger joint pose.
LeftHandIndex1numberPoseLeft index 1 finger joint pose.
LeftHandIndex2numberPoseLeft index 2 finger joint pose.
LeftHandIndex3numberPoseLeft index 3 finger joint pose.
LeftHandIndex4numberPoseLeft index 4 finger joint pose.
LeftHandMiddle1numberPoseLeft middle 1 finger joint pose.
LeftHandMiddle2numberPoseLeft middle 2 finger joint pose.
LeftHandMiddle3numberPoseLeft middle 3 finger joint pose.
LeftHandMiddle4numberPoseLeft middle 4 finger joint pose.
LeftHandRing1numberPoseLeft ring 1 finger joint pose.
LeftHandRing2numberPoseLeft ring 2 finger joint pose.
LeftHandRing3numberPoseLeft ring 3 finger joint pose.
LeftHandRing4numberPoseLeft ring 4 finger joint pose.
LeftHandPinky1numberPoseLeft pinky 1 finger joint pose.
LeftHandPinky2numberPoseLeft pinky 2 finger joint pose.
LeftHandPinky3numberPoseLeft pinky 3 finger joint pose.
LeftHandPinky4numberPoseLeft pinky 4 finger joint pose.
RightHandnumberPoseRight hand pose.
RightHandThumb1numberPoseRight thumb 1 finger joint pose.
RightHandThumb2numberPoseRight thumb 2 finger joint pose.
RightHandThumb3numberPoseRight thumb 3 finger joint pose.
RightHandThumb4numberPoseRight thumb 4 finger joint pose.
RightHandIndex1numberPoseRight index 1 finger joint pose.
RightHandIndex2numberPoseRight index 2 finger joint pose.
RightHandIndex3numberPoseRight index 3 finger joint pose.
RightHandIndex4numberPoseRight index 4 finger joint pose.
RightHandMiddle1numberPoseRight middle 1 finger joint pose.
RightHandMiddle2numberPoseRight middle 2 finger joint pose.
RightHandMiddle3numberPoseRight middle 3 finger joint pose.
RightHandMiddle4numberPoseRight middle 4 finger joint pose.
RightHandRing1numberPoseRight ring 1 finger joint pose.
RightHandRing2numberPoseRight ring 2 finger joint pose.
RightHandRing3numberPoseRight ring 3 finger joint pose.
RightHandRing4numberPoseRight ring 4 finger joint pose.
RightHandPinky1numberPoseRight pinky 1 finger joint pose.
RightHandPinky2numberPoseRight pinky 2 finger joint pose.
RightHandPinky3numberPoseRight pinky 3 finger joint pose.
RightHandPinky4numberPoseRight pinky 4 finger joint pose.
LeftFootnumberPoseLeft foot pose.
RightFootnumberPoseRight foot pose.
Trackers
TrackedObject00numberPoseTracker 0 pose.
TrackedObject01numberPoseTracker 1 pose.
TrackedObject02numberPoseTracker 2 pose.
TrackedObject03numberPoseTracker 3 pose.
TrackedObject04numberPoseTracker 4 pose.
TrackedObject05numberPoseTracker 5 pose.
TrackedObject06numberPoseTracker 6 pose.
TrackedObject07numberPoseTracker 7 pose.
TrackedObject08numberPoseTracker 8 pose.
TrackedObject09numberPoseTracker 9 pose.
TrackedObject10numberPoseTracker 10 pose.
TrackedObject11numberPoseTracker 11 pose.
TrackedObject12numberPoseTracker 12 pose.
TrackedObject13numberPoseTracker 13 pose.
TrackedObject14numberPoseTracker 14 pose.
TrackedObject15numberPoseTracker 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.01.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.01.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.01.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.01.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));
});