controller-movement

The controller-movement component enables smooth locomotion in VR using controller thumbsticks, allowing users to navigate through virtual environments with intuitive dual-controller movement.

Example

Below is an example of setting up controller movement in a basic scene:

import "spatial-design-system/components/controllers.js";
import "spatial-design-system/components/controllerMovement.js";

<a-scene>
  <!-- Simple environment -->
  <a-sky color="#ECECEC"></a-sky>
  <a-plane position="0 0 0" rotation="-90 0 0" width="20" height="20" color="#7BC8A4"></a-plane>
  
  <!-- Camera rig with controllers and movement -->
  <a-entity id="rig" position="0 1.6 0" controllers>
    <a-camera></a-camera>
    <a-entity controller-movement="
      mainHand: left;
      speed: 2;
      rotationSpeed: 60;
      mode: controller;
      smoothing: 0.1;
      deadzone: 0.2
    "></a-entity>
  </a-entity>
</a-scene>

Props

Property	Type	Default	Description
mainHand	string	"left"	Controller used for movement ("left" or "right")
speed	number	2	Movement speed in meters per second
rotationSpeed	number	60	Rotation speed in degrees per second
mode	string	"controller"	Movement direction mode ("head" or "controller")
smoothing	number	0.1	Movement smoothing factor (0-1, higher = more smoothing)
deadzone	number	0.2	Thumbstick deadzone (0-1, ignores small stick movements)

How It Works

1. The component uses a dual-controller approach for VR locomotion:
   • The main hand (typically left) controls forward/backward movement and strafing
   • The off hand (opposite of main hand) controls rotation
2. Movement is determined by thumbstick direction:
   • Forward/backward: Up/down on the main hand thumbstick
   • Strafing: Left/right on the main hand thumbstick
   • Rotation: Left/right on the off hand thumbstick
3. The movement direction can be based on either:
   • Head direction (where you're looking)
   • Controller direction (where the main controller is pointing)
4. Movement is applied to the camera rig entity, with smooth acceleration and deceleration

Movement Controls

Thumbstick	Direction	Action
Main Hand	Up	Move forward
Main Hand	Down	Move backward
Main Hand	Left	Strafe left
Main Hand	Right	Strafe right
Off Hand	Left	Rotate left
Off Hand	Right	Rotate right

Combining with Other Movement Options

For maximum accessibility, combine smooth locomotion with teleportation using the controller-teleport component:

<a-entity id="rig" position="0 1.6 0" controllers>
  <a-camera></a-camera>
  <!-- Smooth movement with left hand -->
  <a-entity controller-movement="mainHand: left"></a-entity>
  <!-- Teleportation with right hand -->
  <a-entity controller-teleport="hand: right"></a-entity>
</a-entity>

This gives users options for both smooth locomotion and teleportation, accommodating different preferences and comfort levels. Smooth movement is often preferred for precision navigation, while teleportation can reduce motion sickness for some users.