@depasquale/three-immersive-controls
v0.0.17
Published
Immersive (VR) controls for Three.js
Downloads
685
Readme
Three.js Immersive Controls
- Immersive (VR) functionality
- Movement and rotation with VR controllers (move with left thumbstick, rotate with right thumbstick)
- Object selection with VR controllers (
A
button or trigger)
- Browser window functionality
- Movement and rotation with keyboard (WASD and arrow keys)
- Object selection with mouse
Installation
npm install @depasquale/three-immersive-controls
Usage
import ImmersiveControls from '@depasquale/three-immersive-controls';
// Create the `camera`, `renderer`, and `scene` instances with Three.js
// ...
const controls = new ImmersiveControls(camera, renderer, scene, { /* options */ });
Include this in the render loop:
controls.update();
Options
initialPosition: THREE.Vector3
- The player's initial position in the scene. Default is
new THREE.Vector3(0, 1.6, 4)
.
- The player's initial position in the scene. Default is
lookAt: THREE.Vector3
- Point toward which the player is initially oriented. (Not yet implemented.)
floor: number | false
number
(default is0
): Sets the y position of a floor below which the player cannot pass (simple solution for collision detection instead of navmeshes).false
: No limit to the player's movement along the y-axis is set.
gravity: true | false
true
(default): The player's movement is restricted to the x- and z-axes, and the y position remains at thefloor
setting.false
: The player can also move vertically along the y-axis (flight mode).
moveSpeed: { keyboard: number, vr: number }
- Speed at which the player moves through the scene when input is received from the keyboard or VR controllers. Default is
{ vr: 2.5, keyboard: 5 }
.
- Speed at which the player moves through the scene when input is received from the keyboard or VR controllers. Default is
rotateSpeed: number
- Speed at which the player is rotated when input is received from the keyboard or VR controllers. Default is
1
.
- Speed at which the player is rotated when input is received from the keyboard or VR controllers. Default is
tumble: true | false
- Allow the player to rotate on the x-axis in addition to the y-axis. Default is
false
.
- Allow the player to rotate on the x-axis in addition to the y-axis. Default is
showControllerModel: true | false
- Show the VR controllers in immersive mode. Default is
true
.
- Show the VR controllers in immersive mode. Default is
showEnterVRButton: true | false
- Add a button to the DOM to allow the user to enter immersive mode when this functionality is supported. Default is
true
.
- Add a button to the DOM to allow the user to enter immersive mode when this functionality is supported. Default is
showExitVRButton: true | false
- Display a button in front of the player in the scene which allows the user to exit immersive mode. Default is
true
.
- Display a button in front of the player in the scene which allows the user to exit immersive mode. Default is
vrControls: true | false
- Activate immersive (VR) controls. Default is
true
.
- Activate immersive (VR) controls. Default is
keyboardControls: true | false
- Activate keyboard controls. Default is
true
.
- Activate keyboard controls. Default is
mouseControls: true | false
- Activate mouse controls. Default is
true
. (Movement with mouse input has not yet been implemented, but object selection with the mouse works.)
- Activate mouse controls. Default is
showFps: true | false
- Display the
Stats
indicator in the DOM and in front of the player in the scene to monitor performance. Default isfalse
.
- Display the
Examples
Examples are provided in the examples
directory. To try them locally in your browser, run:
npm run examples
Or try them here.
To do
- Add collision detection with navmeshes
- Test with a variety of VR devices (so far only tested with Oculus Quest 2)
- Handle situations when only one VR controller is available
- Add controls for touchscreen devices
- Better repositioning of "Exit VR" button in scene
- Possible additional features
- Teleportation
- Blinders during rotation and movement
- Movement with mouse input
- Hand tracking