Getting Started with A-Frame: Part 1 – Creating a Simple Scene

If you’ve been keeping up to date with developments in webVR, you’ve probably heard a little (or a lot) about something called A-Frame. For those who haven’t  – it’s an open source webVR framework, designed and built by the Mozilla VR team with the purpose of simplifying the development process for creating web based VR content.

A-Frame is essentially a wrapper atop the three.JS webGL framework – one tailored specifically for creating and viewing webVR content. It takes a lot of the grunt work out of setting up a new webVR scene, providing an API that allows easy support for a number of VR headset options (oculus, vive, daydream etc…) or webVR enabled browsers.

The framework is built using a pattern known as the ‘Entity-Component-System’. If you’re not familiar with this term, it’s worth spending a little time getting your head around it. To quote the explanation directly from the docs:

The ECS pattern is a pattern common in game development that favors composability over traditional inheritance and hierarchy:

  • An entity is a general-purpose object that inherently does and renders nothing.
  • A component is a reusable module that we plug into entities to provide appearance, behavior, and/or functionality. They are plug-and-play for objects.
  • A system provides global scope, services, and management to classes of components.

ECS lets us build complex entities with rich behavior by plugging different reusable components into the sockets on the entity. Contrast this to traditional inheritance where if we want to extend an object, we would have to manually create a new class to do so.

If you’re still left scratching your head after that explanation, I’d strongly suggest reading through the details in the (excellent) docs.

But the real killer feature of A-Frame is just how simple and intuitive a developer experience it provides. You can build full, rich VR scenes using just html – providing a structure that almost all developers will feel immediately at home with.

But enough with the introductions, lets build something.

Creating a Simple Scene

First, just set up a standard html document, and import the A-Frame build.

In this case we simply pull in the non-minified build within a script tag. Alternatively, if you’re using npm, you can add it to  your dependencies the usual way:

$ npm install aframe

Then require it in your code:


We’re now set up to start using A-Frame. We’ll keep things very simple (and a little boring) for our first scene. All we’re aiming to do is render a little blue box that we can experience in VR. We need to add just two elements to achieve this:

  • The Scene
  • A Box Primitive

The Scene

  // All other A-Frame entities go here.

The A-Frame scene element is the root of any A-Frame VR scene – any other elements you want to place in your scene (geometries, cameras, lighting etc) will be contained within it.

However the scene element isn’t just a wrapper – It also takes care of a massive amount of three.JS and webVR boilerplate that you would otherwise be coding yourself. This includes providing a canvas and animation loop, setting up the webVR polyfill, three.JS VREffect and default camera and lighting for your scene, and a simple UI for entering VR.

If you haven’t already, take a look at the official docs for the scene element here.

The Box Primitive

  position="-1 0.5 -3"

The above is an A-Frame box primitive. What is a primitive, you ask? Again, you should head to the docs for the best explanation. If you’re feeling lazy, here’s a quick excerpt:

Primitives are entities that:

  • Have a semantic name (e.g., <a-box>)
  • Have a preset assemblage of components
  • Have default component property values
  • Map HTML attributes to component properties

Primitives abstract the core API to:

  • Pre-compose useful components together with prescribed defaults
  • Act as a shorthand for complex-but-common types of entities (e.g., <a-sky>)
  • Provide a familiar interface with HTML attributes mapping to only a single value

For our scene, we’re making use of the box primitive, and as you can see there are a number of attributes attached which are being mapped to properties of components on the underlying entity.

Putting it Together

It’s now time to put this together with the standard html boilerplate to create our scene. All this requires is nesting these components within the body tag of our html, to produce the following:

Congrats! You’ve just created your first VR scene. Go ahead and open the file in your browser of choice. You should see a 3D scene containing a single sky-blue box. You’ll be able to navigate around the scene using your cursor and the WASD keys, and have the ability to enter VR mode through the button on the bottom right of screen (all features handily provided by the scene element).

Go forth and explore your new world!

Bored yet? I don’t blame you. The above is a very simple example, and is more than a little dull. Nonetheless, I hope that this quick intro has given you an insight into the utility and power of A-Frame, and how it can be used to quickly and easily create webVR experiences.

Keep an eye out, as I’ll be releasing the next part in this tutorial series soon, where I’ll guide you through the process of creating a custom component, which we’ll put to use in a much more interesting scene. In the mean time, go read the docs! Seriously.