Controls

controls is a global singleton which provides an interface for VR, desktop and mobile inputs. These are the default controls and provide your standard third/first person controls for mobile/desktop and VR locomotion. This also stores controller state e.g. mouse interactions of VR hand/controller interactions and state.

Examples:

// set object's local postion to the left controller position (world space)
this.update = () => {
  this.position.copy(controls.left.position);
};

// Vibrate the controller when it clicks an object
this.click = (evt) => {
  // Pulse at max intensity, for 20ms
  // evt.hand is 'left' or 'right'
  controls[evt.hand].pulse(1.0, 20);
};

this.update = () => {
  // If using hand tracking
  if (controls.right.inputSource == 2) {
    this.position.copy(controls.right.hand["index-finger-tip"].position);
  }
};

// Set nested object's rotation/quaternion to controller quaternion
this.update = () => {
  // get inverse of parent quaternion
  const quaternion = new THREE.Quaternion();
  this.parent.getWorldQuaternion(quaternion);
  quaternion.invert();
  // copy it so that objects world rotation is 0, 0, 0
  this.quaternion.copy(quaternion);
  // then multiply / set from world controller rotation
  this.quaternion.multiply(controls.left.quaternion);
};

// Change walking speed on desktop, and locomotion speed in VR
controls.speed = 3;

// Set camera to first person
controls.zoom = 0;

// Set camera to third person
controls.zoom = 2.5;

controls.zoom : Number

Controls how far away the camera is from the player on mobile and desktop. Setting controls.zoom = 0 is first person and controls.zoom > 0.5 is third person, (3 is the default).

controls.yShift : Number

How far to move the camera above player eye height. This scales is multiplied by controls.zoom:

camera.position.y += controls.zoom * controls.yShift;

This is useful if you want to move the camera higher so the player's head doesn't overlap with the cursor. The default is 0.1

controls.speed : Number

Movement speed

controls.intersections : Array

An array of the interesected raycastable objects

controls.jumpEnabled : boolean

Flag to enable or disable jumping capability.

controls.flyEnabled : boolean

Flag to enable or disable flying capability.

controls.pressing : Boolean

Left click on desktop

controls.grabbing : Boolean

Right click on desktop

controls.floor : THREE.Object3D | null

The current object below the player, useful for sound effects, collisions.

controls.floorHeight : Number

The floors y position in world space.

controls.falling : boolean

Whether player controls are falling

controls.startPosition : Vector3

The initial camera position when the scene is loaded. This is used for resetting the player position on fall timeout. You can over-ride this. This can be useful for resetting to a point on a map when the player dies or falls for too long

controls.fallResetTime : Number : 2

The time before the player controls resets to the original startPostion when falling for x seconds. The default is 2 (seconds).

To disable this use: controls.fallResetTime = -1

Desktop

// Disable or enable using pointer lock. true by default
controls.desktop.pointerLockEnabled = true | false

controls.desktop.enabled = true | false

controls.desktop.cursor -> cursor DOM element

// You can create your own desktop specific controls, e.g.

controls.desktop = {
	update: (delta)=>{ /* your logic '*/ }
}

Mobile

controls.mobile.enable();

controls.mobile.disable();

controls.mobile = {
  update: (delta) => {
    /* your logic '*/
  },
};

XR

controls.locomotion : Locomotion

Handles locomotion within the VR environment.

controls.locomotion.enabled : boolean

Flag to enable or disable locomotion.

controls['left' or 'right'] : Hand

Left/right controller object, containing state and interaction data for that hand.

Hand : Object

Represents the right control interface, including position, rotation, and interaction states.

Hand joints:

'wrist'
'thumb-metacarpal'
'thumb-phalanx-proximal'
'thumb-phalanx-distal'
'index-finger-phalanx-proximal'
'index-finger-phalanx-intermediate'
'index-finger-phalanx-distal'
'middle-finger-phalanx-proximal'
'middle-finger-phalanx-intermediate'
'middle-finger-phalanx-distal'
'ring-finger-phalanx-proximal'
'ring-finger-phalanx-intermediate'
'ring-finger-phalanx-distal'
'pinky-finger-phalanx-proximal'
'pinky-finger-phalanx-intermediate'
'pinky-finger-phalanx-distal'

// Three.Group storing bone position, rotation
controls.left.hand['pinky-finger-phalanx-distal'] -> THREE.Group