Minecraft in WebVR with HTML Using A-Frame

Avatar of Kevin Ngo
Kevin Ngo on

I’m Kevin Ngo, a virtual reality web developer on the Mozilla VR team and a core developer of A-Frame. Today, we’ll go over how to build a room scale WebVR Minecraft demo that works on HTC Vive, Oculus Rift, Samsung GearVR, Google Cardboard, desktop, and mobile. The demo will be built with A-Frame in just 11 HTML elements!


A few years ago, Mozilla invented and pioneered WebVR, a JavaScript API for creating immersive VR experiences in your browser, in an experimental build of Firefox. Since then, WebVR has gained wide support from other companies such as Google, Microsoft, Samsung, and Oculus. And it’s now set to release enabled by default in Firefox within a few months!

Why WebVR? The Web brings openness to VR; on the Web, content isn’t controlled by gatekeepers, and users aren’t kept in walled gardens. The Web also brings connectedness to VR; on the Web, we’ll be able to traverse from world to world just as we today jump from page to page with links. With WebGL having matured with and new specifications such as Web Assembly and Service Workers, the Web is ready for VR.

Mozilla VR team created A-Frame to kickstart the WebVR ecosystem, giving web developers the power to build 3D and VR worlds.

A-Frame Homepage

A-Frame is a web framework for building virtual reality experiences. A-Frame is based on HTML and the Entity-Component pattern. HTML is the most accessible language in all of computing, making it possible for anyone to get started. Below is a complete 3D and VR scene in just HTML that runs across multiple VR platforms as well as desktop and mobile:

See the Pen Hello World — A-Frame by mozvr (@mozvr) on CodePen.

That’s it! Specifying just one line of HTML (<a-scene>) will take care of all the 3D and VR boilerplate: canvas, scene, renderer, render loop, camera, and lights. Then we add objects via child elements to the scene. No build steps, just a copy-and-paste-friendly HTML file.

And we can dynamically query and manipulate A-Frame’s HTML the same as we would with standard JavaScript and DOM APIs (e.g., querySelector, getAttribute, addEventListener, setAttribute):

// Query scene graph using `querySelector`.
var sceneEl = document.querySelector('a-scene');
var boxEl = sceneEl.querySelector('a-box');

// Get data about entity with `getAttribute`.
// >> {x: -1, y: 0.5, z: -3}

// Add event listener with `addEventListener`.
box.addEventListener('click', function () {
  // Modify entity with `setAttribute`.
  box.setAttribute('color', 'red');

And since it’s just HTML and JavaScript, A-Frame works with many existing frameworks and libraries:

Works with d3, Vue, React, Redux, jQuery, Angular

Although A-Frame’s HTML looks easy, A-Frame’s API is much more powerful than simply making 3D declarative. A-Frame is an entity-component-system (ECS) framework. Notably used by Unity, ECS is a pattern popular in game development. The concept follows:

  • All objects in the scene are entities, an empty object that doesn’t do anything on its own, analogous to an empty <div>. In A-Frame, entities are represented in the DOM as an element.
  • Then we plug components into those entities to provide appearance, behavior, and functionality. In A-Frame, components are registered in JavaScript and can be made to do anything. They have full access to three.js and DOM APIs. Components can be attached to entities in HTML after they are registered.

The advantage of ECS is that it’s composable; we can mix and match these reusable components to build more complex 3D objects. A-Frame takes it up a notch and makes it declarative and part of the DOM as we’ll see in the Minecraft example.

Example Skeleton

Now to our demo. We’ll be building a basic VR voxel builder. The voxel builder will be primarily for room scale VR with positional tracking and tracked controllers (e.g., HTC Vive, Oculus Rift + Touch). We’ll also make it work on desktop and mobile, but the experience won’t be as compelling.

We’ll start off with skeleton HTML. If you want to skim through (all 11 lines of HTML), check out the source code on GitHub.

<script src="https://aframe.io/releases/0.5.0/aframe.min.js"></script>


Adding a Ground

<a-plane> and <a-circle> are basic primitives that are commonly used for adding a ground. We’ll be using <a-cylinder> to better work with the raycasters our controllers will be using. The cylinder will have a radius of 30 meters to match the radius of the sky we’ll add later. Note that A-Frame units are in meters to match the real-world units returned from the WebVR API.

The texture of the ground we’ll be using is hosted at `https://cdn.aframe.io/a-painter/images/floor.jpg`. We’ll add the texture to our assets, and create a thin cylinder entity pointing to that texture:

See the Pen Minecraft VR Demo (Part 1) by mozvr (@mozvr) on CodePen.

Preloading Assets

Specifying a URL via the src attribute will load the texture at runtime.

Since network requests can negatively impact render performance, we can preload the texture such that the scene doesn’t start rendering until its assets have been fetched. We can do this using the asset management system.

We place <a-assets> into our <a-scene>, place assets (e.g., images, videos, models, sounds) into <a-assets>, and point to them from our entities via a selector (e.g., #myTexture).

Let’s move our ground texture to <a-assets> to be preloaded using an <img> element:

See the Pen Minecraft VR Demo (Part 2: Preloading Texture) by mozvr (@mozvr) on CodePen.

Adding a Background

Let’s add a 360° background to our <a-scene> with the <a-sky> element. <a-sky> is a large 3D sphere with a material mapped on the inside. Just like a normal image, <a-sky> can take an image path with src. This ultimately lets us do immersive 360° images with one line of HTML. As an exercise later, try using some 360° images from Flickr’s
equirectangular pool

We could add a plain color background (e.g., <a-sky color="#333"></a-sky>) or a gradient, but let’s add a textured background with an image. The image we’re using is hosted at `https://cdn.aframe.io/a-painter/images/sky.jpg`. The image texture we are using covers semi-sphere so we’ll chop our sphere in half with theta-length="90", and we’ll give our sphere a radius of 30 meters to match the ground:

See the Pen Minecraft VR Demo (Part 3: Adding a Background) by mozvr (@mozvr) on CodePen.

Adding Voxels

Voxels in our VR application will be like <a-box> but attached with a few custom A-Frame components. But first let’s go over the entity-component pattern. Let’s see how the easy-to-use primitives such as <a-box> are composed under the hood.

This section will later do a deeper dive into the implementation of a couple A-Frame components. In practice though, we’d often get to use components via HTML already written by A-Frame community developers rather than building them from scratch.

Entity-Component Pattern

Every single object in an A-Frame scene is <a-entity>, which by itself doesn’t do anything, like an empty <div>. We plug in components (not to be confused with Web or React Components) to that entity to provide with appearance, behavior, and logic.

For a box, we attach and configure A-Frame’s basic geometry and material components. Components are represented as HTML attributes, and component properties are defined like CSS styles by default. Here’s what <a-box> looks like decomposed to its fundamental components. <a-box> wraps the components:

<a-box color="red" depth="0.5" height="0.5" shader="flat" width="0.5"></a-box>
<a-entity geometry="primitive: box; depth: 0.5; height: 0.5; width 0.5"
          material="color: red; shader: standard"></a-entity>

The benefit of components is that they are composable. We can mix and match from a bunch of existing components to construct different types of objects.

In 3D development, the possible types of objects we construct are infinite in number and complexity, and we need an easy way of defining new types of objects rather than through traditional inheritance. Contrast this to the 2D web where we develop with a small pool of fixed HTML elements and plop them into a hierarchy.

Random Color Component

Components in A-Frame are defined in JavaScript, and they have full access to three.js and DOM APIs; they can do anything. We define all of our objects as a bundle of components.

We’ll put the pattern to action by writing an A-Frame component to set a random color on our box. Components are registered with AFRAME.registerComponent. We can define a schema, (the component’s data) and lifecycle handler methods (the component’s logic). For the random color component, we’ll won’t be setting a schema since it won’t be configurable. But we will define the init handler, which is called exactly once when the component is attached:

AFRAME.registerComponent('random-color', {
  init: function () {
    // ...

For the random color component, we want to set a random color on the entity that this component is attached to. Components have a reference to the entity with this.el from the handler methods.

And to change the color with JavaScript, we change the material component’s color property using .setAttribute(). A-Frame several DOM APIs a bit, but the APIs mostly mirror
vanilla web development. Read more about using JavaScript and DOM APIs with

We’ll also add the material component to the list of components that should initialize before this one, just so our material isn’t overwritten.

AFRAME.registerComponent('random-color', {
  dependencies: ['material'],

  init: function () {
    // Set material component's color property to a random color.
    this.el.setAttribute('material', 'color', getRandomColor());

function getRandomColor() {
  const letters = '0123456789ABCDEF';
  var color = '#';
  for (var i = 0; i < 6; i++ ) {
    color += letters[Math.floor(Math.random() * 16)];
  return color;

After the component is registered, we can attach this component straight from HTML. All code written within A-Frame’s framework is extending HTML, and those extensions can be used on other objects and in other scenes. The beautiful thing is that a developer could write a component that adds physics to an object, and then someone that doesn’t even know JavaScript could add
physics to their scene!

Take our box entity from earlier, we attach the random-color HTML attribute to plug in the random-color component. We’ll save the component as a JS file and include it before the scene:

See the Pen Minecraft VR Demo (Part 4: Random Color Component) by mozvr (@mozvr) on CodePen.

Components can be plugged into on any entity without having to create or extend a class like we’d have to in traditional inheritance. If we wanted to attach it to say, <a-sphere> or <a-obj-model>, we could!

<!-- Reusing and attaching the random color component to other entities. -->
<a-sphere random-color></a-sphere>
<a-obj-model src="model.obj" random-color></a-obj-model>

if we wanted to share this component for other people to use, we could too. We curate from many handy components from the ecosystem at the A-Frame Registry, similar to the Unity Asset Store. If we developed our application using components, all our code is inherently modular and reusable!

Snap Component

We’ll have a snap component to snap our boxes to a grid so they aren’t overlapping. We won’t get into the details of how this component is implemented, but you can check out the snap component’s source code (20 lines of JavaScript).

We attach the snap component to our box so that it snaps to every half meter, also with an offset to center the box:

   geometry="primitive: box; height: 0.5; width: 0.5; depth: 0.5"
   material="shader: standard"
   snap="offset: 0.25 0.25 0.25; snap: 0.5 0.5 0.5"></a-entity>

Now we have a box entity represented as a bundle of components that can be used to describe all the voxels in our scene.


We can create a mixin to define a reusable bundle of components.

Instead of <a-entity>, which adds an object to the scene, we’ll describe it using <a-mixin> which can be reused to create voxels like a prefab:

See the Pen Minecraft VR Demo (Part 5: Mixins) by mozvr (@mozvr) on CodePen.

And we’ve added voxels using that mixin:

<a-entity mixin="voxel" position="-1 0 -2"></a-entity>
<a-entity mixin="voxel" position="0 0 -2"></a-entity>
<a-entity mixin="voxel" position="0 1 -2">
  <a-animation attribute="rotation" to="0 360 0" repeat="indefinite"></a-animation>
<a-entity mixin="voxel" position="1 0 -2"></a-entity>

Next, we’ll be creating voxels dynamically through interaction using tracked controllers. Let’s start adding our hands to the application.

Adding Hand Controllers

Adding HTC Vive or Oculus Touch tracked controllers is easy:

<!-- Vive. -->
<a-entity vive-controls="hand: left"></a-entity>
<a-entity vive-controls="hand: right"></a-entity>

<!-- Or Rift. -->
<a-entity oculus-touch-controls="hand: left"></a-entity>
<a-entity oculus-touch-controls="hand: right"></a-entity>

We’ll be using hand-controls which abstracts and works with both Vive and Rift controls, providing models of basic hand. We’ll make the left hand responsible for teleporting around and the right hand responsible for spawning and placing blocks.

<a-entity id="teleHand" hand-controls="left"></a-entity>
<a-entity id="blockHand" hand-controls="right"></a-entity>

Adding Teleportation to the Left Hand

We’ll plug in teleportation capabilities to the left hand such that we hold a button to show an arc coming out of the controller, and let go of the button to teleport to the end of the arc. Before, we wrote our own A-Frame components.

But we can also use open source components already made from the community and just use them straight from HTML!

For teleportation, there’s a teleport-controls component by @fernandojsg. Following the README, we add the component via a <script> tag and just set the teleport-controls component on the controller on the entity:

<script src="https://aframe.io/releases/0.5.0/aframe.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-teleport-controls.min.js"></script>

<!-- ... -->

<a-entity id="teleHand" hand-controls="left" teleport-controls></a-entity>
<a-entity id="blockHand" hand-controls="right"></a-entity>

Then we’ll configure the teleport-controls component to use an arc type of teleportation. By default, teleport-controls will only teleport on the ground, but we can specify with collisionEntities to teleport on the blocks and the ground using selectors. These properties are part of the API that the teleport-controls component was created with:

<a-entity id="teleHand" hand-controls="left" teleport-controls="type: parabolic; collisionEntities: [mixin='voxel'], #ground"></a-entity>

That’s it! One script tag and one HTML attribute and we can teleport. For more cool components, check out the A-Frame Registry.

Adding Voxel Spawner to the Right Hand

In WebVR, the ability to click on objects isn’t built-in as it is in 2D applications. We have to provide that ourselves. Fortunately, A-Frame has many components to handle interaction. A common method for cursor-like clicking in VR is to use a raycaster, a laser that shoots out and returns objects that it intersects with. Then we implement the cursor states by listening to interaction events and checking the raycaster for intersections.

A-Frame provides a gaze-based cursor for clicking by looking at objects, but there’s also a controller-cursor component available that attaches the clicking laser to VR tracked controllers. Like the teleport-controls component, we include the script tag and attach the controller-cursor component. This time to the right hand:

<script src="https://aframe.io/releases/0.5.0/aframe.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-teleport-controls.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/aframe-controller-cursor-component.min.js"></script>

<!-- ... -->

<a-entity id="teleHand" hand-controls="left" teleport-controls="type: parabolic; collisionEntities: [mixin='voxel'], #ground"></a-entity>
<a-entity id="blockHand" hand-controls="right" controller-cursor></a-entity>

Now when we pull the trigger button on the tracked controllers, controller-cursor will emit a click event on both the controller and the entity it is intersecting at the time. Events such as mouseenter, mouseleave are also provided. The event contains details about the intersection.

That provides us with the ability to click, but we’ll have to wire up some code to handle those clicks to spawn blocks. We can use an event listener and document.createElement:

document.querySelector('#blockHand').addEventListener(`click`, function (evt) {
  // Create a blank entity.
  var newVoxelEl = document.createElement('a-entity');

  // Use the mixin to make it a voxel.
  newVoxelEl.setAttribute('mixin', 'voxel');

  // Set the position using intersection point. The `snap` component above which
  // is part of the mixin will snap it to the closest half meter.
  newVoxelEl.setAttribute('position', evt.detail.intersection.point);

  // Add to the scene with `appendChild`.

To generalize creating entities from an intersection event, we’ve created an intersection-spawn component that can be configured with any event and list of properties. We won’t go into the detail of the implementation, but you can check out the simple intersection-spawn component source code on GitHub. We attach intersection-spawn capabilities to the right hand:

<a-entity id="blockHand" hand-controls="right" controller-cursor intersection-spawn="event: click; mixin: voxel"></a-entity>

Now when we click, we spawn voxels!

Adding Support for Mobile and Desktop

We see how we’ve built a custom type of object (i.e., a tracked hand controller with a hand model that has click capabilities and spawns blocks on click) by mixing together components. The wonderful thing with components is that they are reusable in other contexts. We could even attach the intersection-spawn component with the gaze-based cursor component so that we can also spawn blocks on mobile and desktop, without changing a thing about the component!

<a-entity id="blockHand" hand-controls="right" controller-cursor intersection-spawn="event: click; mixin: voxel"></a-entity>

  <a-cursor intersection-spawn="event: click; mixin: voxel"></a-cursor>

Try It Out!

Read the source code on GitHub.

Our VR voxel builder is ultimately 11 HTML elements. We can preview it on desktop and mobile. On desktop, we can drag and click to spawn blacks. On mobile, we can pan the device around and tap to spawn blocks.

See the Pen Minecraft VR Demo (Final) by mozvr (@mozvr) on CodePen.

If you have a VR headset (e.g., HTC Vive, Oculus Rift + Touch), grab a WebVR-enabled browser and head over to the demo. VR by plugging in an HTC Vive or Oculus Rift and using a WebVR-enabled browser.

If you want to view what it looks like in VR from your desktop or mobile device, check out the demo with pre-recorded VR motion capture and gestures.

Looking Forward

A-Frame has an active open source community and ecosystem. To date:

A-Frame is the WebVR framework for innovating what VR on the Web will look like while making it easy for anyone to get involved developing with 3D and VR. HTML keeps it dead simple while being fed by the Entity-Component pattern underneath. These experimentations will be the foundation of the open Metaverse, shared persistent connected virtual spaces that will be inhabited by everyone.

It’s the early stages of VR and especially for WebVR, but browsers soon shipping WebVR enabled by default to hundreds of millions, web developers should get involved to make VR accessible to everyone.