Controller

Description

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

Functions

Properties

Mappings

Input, Hardware, and Action Reflection

Input, Hardware, and Action Events

Mouse, Keyboard, and Touch Events

Control Capturing

Action Capturing

Controller and Action Values

Haptics

Display Information

Virtual Game Pad

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.

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

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 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 Disable translating and rotating the user's avatar in response to keyboard and controller controls.
captureEntityClickEvents None Disable Entities.mousePressOnEntity and Entities.mouseDoublePressOnEntity events on entities.
captureJoystick None Disable default Interface actions for a joystick.

Deprecated: This function no longer has any effect.

captureKeyEvents None Disable default Interface actions for a particular key event.
captureMouseEvents None Disable processing of mouse "move", "press", "double-press", and "release" events into Controller.Hardware.Keyboard outputs.
captureTouchEvents None Disable processing of touch "begin", "update", and "end" events into Controller.Hardware.Keyboard, Controller.Hardware.Touchscreen, and Controller.Hardware.TouchscreenVirtualPad outputs.
captureWheelEvents None Disable processing of mouse wheel rotation events into Controller.Hardware.Keyboard outputs.
disableMapping None Disable a controller mapping. When disabled, the routes in the mapping have no effect.
enableMapping None Enable or disable a controller mapping. When enabled, the routes in the mapping have effect.
findAction number Find the ID of an action from its name.
findDevice number Find the ID of a specific controller from its device name.
getActionNames Array.<string> Get the names of all actions available as properties of Controller.Actions.
getActions Controller.Actions Get the Controller.Actions property tree. Calling this function is the same as using the Controller property, Controller.Actions.
getActionValue number Get the current value of an action.
getAllActions Array.<Action> Get a list of all available actions.

Deprecated: This function no longer works.

getAvailableInputs Array.<NamedPair> Get a list of all available inputs for a hardware device.

Deprecated: This function no longer works.

getAxisValue number Get the value of a controller axis output. Note: Also gets the value of a controller button output.
getDeviceName string Find the name of a particular controller from its device ID.
getDeviceNames Array.<string> Get the names of all currently available controller devices plus "Actions", "Application", and "Standard".
getHardware Controller.Hardware Get the Controller.Hardware property tree. Calling this function is the same as using the Controller property, Controller.Hardware.
getInputRecorderSaveDirectory string Get the directory in which input recordings are saved.
getPoseValue Pose Get the value of a controller pose output.
getRecommendedHUDRect Rect Get 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> Get all the active and enabled (running) input devices
getStandard Controller.Standard Get the Controller.Standard property tree. Calling this function is the same as using the Controller property, Controller.Standard.
getValue number Get the value of a controller button or axis output. Note: Also gets the value of a controller axis output.
getViewportDimensions Vec2 Get the dimensions of the Interface window's interior if in desktop mode or the HUD surface if in HMD mode.
loadInputRecording None Load an input recording, ready for play back.
loadMapping MappingObject Create a new controller mapping from a MappingJSON JSON file at a URL. Use enableMapping to enable the mapping for it to take effect.

To Do:

  • Implement this function. It currently does not load the mapping from the file; it just returns null.

newMapping MappingObject Create 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 Create a new controller mapping from a MappingJSON string. Use enableMapping to enable the mapping for it to take effect.
releaseActionEvents None Enable translating and rotating the user's avatar in response to keyboard and controller controls that were disabled using captureActionEvents.
releaseEntityClickEvents None Re-enable Entities.mousePressOnEntity and Entities.mouseDoublePressOnEntity events on entities that were disabled using captureEntityClickEvents.
releaseJoystick None Re-enable default Interface actions for a joystick that has been disabled using captureJoystick.

Deprecated: This function no longer has any effect.

releaseKeyEvents None Re-enable default Interface actions for a particular key event that has been disabled using captureKeyEvents.
releaseMouseEvents None Enable processing of mouse "move", "press", "double-press", and "release" events into Controller.Hardware.Keyboard outputs that were disabled using captureMouseEvents.
releaseTouchEvents None Enable 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 Enable processing of mouse wheel rotation events into Controller.Hardware.Keyboard outputs that wer disabled using captureWheelEvents.
saveInputRecording None Save 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 Play 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 Start making a recording of currently active controllers.
stopInputPlayback None Stop play back of a recording started by startInputPlayback.
stopInputRecording None Stop 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.

Signals

Name Summary
actionEvent Triggered when an action occurs.
deviceRunningChanged Triggered when a device is enabled/disabled Enabling/Disabling Leapmotion on settings/controls will trigger this signal.
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.
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 can be used as end points in the routes of a MappingObject. The data 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, to third person, to full screen mirror, 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: No action.
RightHandClicknumbernumberDeprecated: No action.
ShiftnumbernumberDeprecated: No action.
PrimaryActionnumbernumberDeprecated: No action.
SecondaryActionnumbernumberDeprecated: 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: Use LeftHand instead.
RIGHT_HANDnumberPoseDeprecated: Use RightHand instead.
BOOM_INnumbernumberDeprecated: Use BoomIn instead.
BOOM_OUTnumbernumberDeprecated: Use BoomOut instead.
CONTEXT_MENUnumbernumberDeprecated: Use ContextMenu instead.
TOGGLE_MUTEnumbernumberDeprecated: Use ToggleMute instead.
TOGGLE_PUSHTOTALKnumbernumberDeprecated: Use TogglePushToTalk instead.
SPRINTnumbernumberDeprecated: Use Sprint instead.
LONGITUDINAL_BACKWARDnumbernumberDeprecated: Use Backward instead.
LONGITUDINAL_FORWARDnumbernumberDeprecated: Use Forward instead.
LATERAL_LEFTnumbernumberDeprecated: Use StrafeLeft instead.
LATERAL_RIGHTnumbernumberDeprecated: Use StrafeRight instead.
VERTICAL_UPnumbernumberDeprecated: Use Up instead.
VERTICAL_DOWNnumbernumberDeprecated: Use Down instead.
PITCH_DOWNnumbernumberDeprecated: Use PitchDown instead.
PITCH_UPnumbernumberDeprecated: Use PitchUp instead.
YAW_LEFTnumbernumberDeprecated: Use YawLeft instead.
YAW_RIGHTnumbernumberDeprecated: Use YawRight instead.
LEFT_HAND_CLICKnumbernumberDeprecated: Use LeftHandClick instead.
RIGHT_HAND_CLICKnumbernumberDeprecated: Use RightHandClick instead.
SHIFTnumbernumberDeprecated: Use Shift instead.
ACTION1numbernumberDeprecated: Use PrimaryAction instead.
ACTION2numbernumberDeprecated: Use SecondaryAction instead.
Deprecated Trackers
TrackedObject00numberPoseDeprecated: No action.
TrackedObject01numberPoseDeprecated: No action.
TrackedObject02numberPoseDeprecated: No action.
TrackedObject03numberPoseDeprecated: No action.
TrackedObject04numberPoseDeprecated: No action.
TrackedObject05numberPoseDeprecated: No action.
TrackedObject06numberPoseDeprecated: No action.
TrackedObject07numberPoseDeprecated: No action.
TrackedObject08numberPoseDeprecated: No action.
TrackedObject09numberPoseDeprecated: No action.
TrackedObject10numberPoseDeprecated: No action.
TrackedObject11numberPoseDeprecated: No action.
TrackedObject12numberPoseDeprecated: No action.
TrackedObject13numberPoseDeprecated: No action.
TrackedObject14numberPoseDeprecated: No action.
TrackedObject15numberPoseDeprecated: 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 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.
CameraThirdPersonnumbernumberThe camera is in third-person mode.
CameraFSMnumbernumberThe camera is in full screen mirror mode.
CameraIndependentnumbernumberThe camera is in independent mode.
CameraEntitynumbernumberThe camera is in entity mode.
InHMDnumbernumberThe user is in HMD mode.
AdvancedMovementnumbernumberAdvanced movement controls are enabled.
SnapTurnnumbernumberSnap turn is enabled.
GroundednumbernumberThe user's avatar is on the ground.
NavigationFocusednumbernumberNot used.

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 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 left. The data value is the number of units rotated (typically 1.0).
MouseWheelLeftnumbernumberThe mouse wheel rotated left. The data value is the number of units rotated (typically 1.0).
MouseWheelUpnumbernumberThe mouse wheel rotated up. The data value is the number of units rotated (typically 1.0).
MouseWheelDownnumbernumberThe mouse wheel rotated down. The data value is the number of units rotated (typically 1.0).
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.

To Do:

  • Currently, the mouse wheel in an ordinary mouse generates left/right wheel events instead of up/down.

Hardware-OculusTouch
Type: object

The Controller.Hardware.OculusTouch object has properties representing Oculus Rift. The property values are integer IDs, uniquely identifying each output. Read-only. These 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 Vive. The property values are integer IDs, uniquely identifying each output. Read-only. These can be mapped to actions or functions or Controller.Standard items in a RouteObject mapping.

PropertyTypeDataDescription
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.
LS_CENTERnumbernumberLeft touch pad center pressed.
LS_XnumbernumberLeft touch pad pressed x-coordinate.
LS_YnumbernumberLeft touch pad pressed y-coordinate.
RSnumbernumberRight touch pad pressed.
RS_CENTERnumbernumberRight touch pad center pressed.
RS_XnumbernumberRight touch pad pressed x-coordinate.
RS_YnumbernumberRight 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.
LeftArmnumberPoseLeft arm pose.
RightArmnumberPoseRight arm pose
LeftHandnumberPoseLeft hand pose.
RightHandnumberPoseRight hand 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.highfidelity.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 name 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 with a ! to use the logical NOT of the property value. 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 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 Controller.Standard items, specified in a JSON file. For example, leapmotion.json and vive.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. To Do: Implement this for current controllers.
LeftSecondaryIndexnumbernumberLeft secondary index control pressed.
RightPrimaryIndexnumbernumberRight primary index control pressed. To Do: Implement this for current controllers.
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( )

Disable 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( )

Disable 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 )

Disable default Interface actions for a joystick.

Deprecated: This function no longer has any effect.

Parameters

Name Type Description
joystickID number The integer ID of the joystick.
(static) captureKeyEvents( event )

Disable 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( )

Disable 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.highfidelity.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( )

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

(static) captureWheelEvents( )

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

(static) disableMapping( mappingName )

Disable 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, enable )

Enable or disable a controller mapping. When enabled, the routes in the mapping have effect.

Parameters

Name Type Default Value Description
mappingName string The name of the mapping.
enable boolean 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.

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

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

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

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

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

Get a list of all available actions.

Deprecated: This function no longer works.

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

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

Deprecated: This function 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.

Get 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".

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

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

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

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

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

Get 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: An array of strings with the names

Get all the active and enabled (running) input devices

(static) getStandard( ) → {Controller.Standard}
Returns: The Controller.Standard property tree.

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

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

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

(static) loadInputRecording( file )

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

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

To Do:

  • Implement this function. It currently does not load the mapping from the file; it just returns null.

Parameters

Name Type Description
jsonURL string The URL the MappingJSON JSON file.
(static) newMapping( mappingName ) → {MappingObject}
Returns: A controller mapping object.

Create 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 Default Value Description
mappingName string 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.highfidelity.controllers.example.newMapping";
var mapping = Controller.newMapping(MAPPING_NAME);

mapping.from(Controller.Standard.RT).to(Controller.Actions.TranslateY);
Controller.enableMapping(MAPPING_NAME);

Script.scriptEnding.connect(function () {
    Controller.disableMapping(MAPPING_NAME);
});
(static) parseMapping( jsonString ) → {MappingObject}
Returns: A controller mapping object.

Create 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.highfidelity.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( )

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

(static) releaseEntityClickEvents( )

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

(static) releaseJoystick( joystickID )

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

Deprecated: This function no longer has any effect.

Parameters

Name Type Description
joystickID number The integer ID of the joystick.
(static) releaseKeyEvents( event )

Re-enable 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( )

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

(static) releaseTouchEvents( )

Enable 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( )

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

(static) saveInputRecording( )

Save 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( )

Play 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( )

Start 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( )

Stop play back of a recording started by startInputPlayback.

(static) stopInputRecording( )

Stop making a recording started by startInputRecording.

(static) triggerHapticPulse( strength, duration, hand )

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

Parameters

Name Type Default Value Description
strength number The strength of the haptic pulse, 0.01.0.
duration number The duration of the haptic pulse, in milliseconds.
hand Controller.Hand 2 The hand or hands to trigger the haptic pulse on.
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, hand )

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

Parameters

Name Type Default Value Description
deviceID number The ID of the device to trigger the haptic pulse on.
strength number The strength of the haptic pulse, 0.01.0.
duration number The duration of the haptic pulse, in milliseconds.
hand Controller.Hand 2 The hand or hands to trigger the haptic pulse on.
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, hand )

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

Parameters

Name Type Default Value Description
strength number The strength of the haptic pulse, 0.01.0.
hand Controller.Hand 2 The hand or hands to trigger the haptic pulse on.
(static) triggerShortHapticPulseOnDevice( deviceID, strength, hand )

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

Parameters

Name Type Default Value Description
deviceID number The ID of the device to trigger the haptic pulse on.
strength number The strength of the haptic pulse, 0.01.0.
hand Controller.Hand 2 The hand or hands to trigger the haptic pulse on.

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);
});
deviceRunningChanged( deviceName, isEnabled )
Returns: Signal

Triggered when a device is enabled/disabled Enabling/Disabling Leapmotion on settings/controls will trigger this signal.

Parameters

Name Type Description
deviceName string The name of the device that is getting enabled/disabled
isEnabled boolean Return if the device is enabled.
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.

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));
});