Locomotion with aframe-extras

Contributed by Nicholas Bottone in May 2022

An important part of immersiveness and interactiveness of VR applications is the ability to move around within the environment, also known as locomotion.  There are a couple different primary methods for locomotion in VR:

1)      Smooth motion with a joystick – more precise, more visually pleasing, and does not break immersiveness.  Comes with the downside of causing motion sickness for some people.

2)      Point to teleport – less likely to cause motion sickness, but breaks the immersiveness of the app.

In this tutorial, we will be implementing smooth joystick locomotion using the aframe-extras library.

You will need to ensure that the aframe-extras bundle gets included with your application bundle.  You can install aframe-extras as an NPM dependency and import it into one of your JS files, or you can include it as a script tag in your HTML file.  Aframe-extras offers minified bundles that include all of their resources, or more specifical bundles that contain only the control-related resources.  If you only plan to use locomotion from aframe-extras, you can go with the latter option to save on download size.  Below is an example of the script tag you could include in your document head:

<script src="https://cdn.jsdelivr.net/gh/donmccurdy/aframe-extras@v6.1.1/dist/aframe-extras.controls.min.js"></script>; 

You will need to add an <a-camera> component to your HTML file if you have not done so already.  You can alternatively use <a-entity camera>, which functions identically.  This component’s position and rotation will automatically be determined by the VR headset’s sensors, so you only need to worry about setting manual values if you want a custom starting position.  You should consider setting the starting position’s y-value to be 1.6 meters above the ground, which is the average standing height.

By default, the camera component will allow using keyboard (WASD) and mouse controls to move the camera around when using a laptop/desktop computer without a VR headset.  You can customize this behavior by adding attributes to the camera.  For instance, you can enable “pointer lock” which forces the mouse pointer to stay within the window (similar to how PC video games work) by using the attribute: look-controls="pointerLockEnabled: true"

Next, you will need to surround your camera component as well as both of your controller components with an a-entity that will act as the “rig”.  This rig will be the container that will move both the camera and the controllers around the environment together when the player uses the movement controls.

We will add the “movement-controls” attribute to the rig to tell aframe-extras to use this rig for locomotion.  This is the only required attribute, but there are optional attributes related to movement speed, whether or not the user can fly vertically, etc.  See this example for a simple implementation:

<a-entity id="rig" movement-controls>

  <a-camera position="0 1.6 0"></a-camera>

  <a-entity id="left-con" oculus-touch-controls="hand: left"></a-entity>

  <a-entity id="right-con" oculus-touch-controls="hand: right"></a-entity>

</a-entity>

See an example implementation of this frontend architecture built with aframe-extras on the VRWiz repository.

Congratulations!  You should now have implemented smooth locomotion with Aframe!