Since January 1, 2018, stewardship of Hive Chicago has transitioned from Mozilla to a new local non-profit, the Chicago Learning Exchange (CLX). Please visit us at chicagolx/joinus to learn how you and your organization can join our growing community. The Hive is still the Hive.

VR Workshop




My First VR Tutorial



My First VR Tutorial

This project will help you build your first virtual reality (VR) site on the Web using Mozilla’s A-Frame JavaScript library. As you follow the tutorial you will

  1. Know and understand what VR is.
  2. Know and understand what A-Frame is.
  3. Know and understand how a webpage can call and run an external script or library on the page.
  4. Style A-Frame ‘primitives’ using attributes like position.
  5. Find and use an ‘equirectangular’ image to replace the webpage’s background.
  6. Change the lighting in your VR environment to approximate the position and angle of light in your background.

Reach out to @MozTeach on Twitter or ask a question on Discourse, our online community forum, if you need an assist!

Let’s get started! You can follow the tutorial sequentially – step by step in order – or jump between sections using these links:

  1. Unleash Web VR!
  2. What’s VR?
  3. What’s A-Frame?
  4. How do external scripts work?
  5. What’s a primitive?
  6. Style the shapes.
  7. Change the background
  8. Change the lighting

Step-by-Step Instructions

  1. Unleash Web VR!

    TL;DR: Delete the comment tags on index.html to get started.

    Right now, this webpage looks wicked boring


    Let’s fix that.

    Go to line 33 of index.html and delete <!--.

    Go to line 50 of index.html and delete -->.

    Take a lookt at index.html to see A-Frame’s Web VR technology come to life. Onward!

    Back to navigation.

  2. What’s VR?

    TL;DR: ‘VR’ stands for ‘virtual reality’ – an explorable digital environment that seems three-dimensional (3D) to a user.

    VR environments are built to have the illusion of depth, even on a two-dimensional (2D) screen. While different VR technologies have been around for a long time, the Oculus Rift and Google Cardboard VR headsets, along with Web technologies like Web Graphics Library (WebGL) and Mozilla’s A-Frame, are making VR more accessible and mainstream than ever before.

    In this tutorial, we’ll use Mozilla’s A-Frame JavaScript library to make wesbites that look 3D. If you have access to an Oculus Rift or Google Cardboard headset and a VR-enabled browswer, you can read more about exploring your page at the Mozilla Developer Network.

    If you’re browser doesn’t support Web VR yet, you can still ‘spin’ the page by clicking, holding, & dragging your mouse and you can edit everything in HTML to create your VR scene.

    Back to navigation.

  3. What’s A-Frame?

    TL;DR: A-Frame is a Mozilla-developed JavaScript library that makes it easy to create VR websites using HTML.

    According to its FAQ, A-Frame

    …is an open source framework for easily creating WebVR experiences with HTML. It is designed and maintained by MozVR (Mozilla’s virtual reality team research team). A-Frame wraps WebGL in HTML custom elements, enabling web developers to create 3D VR scenes that leverage WebGL’s power, without having to learn its complex low-level API.

    What does that mean?

    A-Frame let’s you create 3D, VR environments without having to learn the complexities of WebGL. The A-Frame JavaScript library has all the code you need to call and maniulate primitives like cubes, spheres, and cylinders, as well as to create scenes with backgrounds, cameras, and lighting.

    While you can learn to do an awful lot with A-Frame, it’s easy to begin coding simple shapes and effects. With very little HTML experience, you can create a 3D, VR environment online using A-Frame.

    Back to navigation.

  4. How do external scripts work?

    TL;DR: When you link to an external script, you run its code on your webpage even though it’s hosted from another computer on the Internet.

    When you use the script tag on your webpage, you have to provide the src, or source, for that script, as well. A script’s src is its location, or address, either inside a folder on your computer or somewhere on the Web. As your webpage loads, it brings the code from your script into the page and executes it, applying its rules and effects to your page.

    If you click on index.html in the FILES sidebar on the left-hand side of the Thimble interface, you can see how this looks at line 11:

    <script src=""></script>

    Some external scripts are small and discrete – they do one or two things like make a button work on a survey. Other scripts are large, made of several parts, and much more complex, like a Web-native video game.

    Another kind of script – called a library – contains an entire set of primitives and rules for using them in your webpage. A-Frame is a library that gives you access to ‘primitives’ – generic primitives like a-camera, a-cube, and a-light – along with rules you can use for maniupalting them – like color, position, and rotation.

    The a- prefix before each primitive lets your webpage know that it’s following rules from the A-Frame JavaScript library at line 11.

    People call in external libraries like A-Frame to take advantage of their primitives and rules without having to write all the code that runs theme every time they make a new VR webpage.

    A-Frame is an open source project, which means that everyone with access (and we need to help many more people have much more access) can use the library and even copy and change it for their own uses. Open source projects like A-Frame in emerging technology areas like VR are important because they make it easy for non-experts to understand and use rich web technologies to voice themselves and read, write, and participate on the Web. Making new technologies available to as many people as possible is one way to safeguard the Web as a free, public resource and democratic space for communication, creativity, and problem-solving.

    Back to navigation.

  5. What’s a primitive?

    TL;DR: A primitive is a basic, generic primitive you can copy repeatedly and customize with code.

    In A-Frame, primitives include the basic shapes you might use to create an explorable webpage or graphic design in 3D. These include a-cube, a-cylinder, and a-sphere. Notice how A-frame’s developers name primitives to be easily readble by humans, as well as machines.

    In this tutorial, you’ll have the chance to manipulate several different primitives and effects like camera-position and lighting.

    Back to navigation.

  6. Style the shapes

    TL;DR: You can easily change the color, dimensions, and position of an A-Frame primitive.

    First, look at line 25 and line 36 of index.html. You can see the a-scene tags that surround our other A-Frame elements. This set of a-scene tags has to go around your VR elements so that your webpage knows everything inside of them uses the A-Frame JavaScript library.

    Next, take a look at a-camera, a-cube, a-cylinder, and a-sphere, beginning at line 27 of index.html. Each primitive has a position you can maniuplate by changing the numbers inside the quotation marks.

    • The first number is the horizontal x-axis value for positioning. Negative values go left. Positive values go right.
    • The second number is the vertical y-axis value. Negative values go down. Positive values go up.
    • The third number is the front-back z-axis value. Negative values go backwards into the screen. Positive values move forward towards you.

    In A-Frame, these primitives all begin with a default position of "0 0 0". If you have multiple primitives, it’s important to position them differently so they don’t cover each other. Also in A-Frame, 1 equals one meter. If you position an primitive with a high value like 20, it might appear off-screen.

    You can position a-camera and a-light the same way to create new camera angles and lighting effects on your page.

    That one-meter unit of measurement also applies while sizing primitives. Try changing the height, width, and depth of a-cube, the height of a-cylinder, and the radius of a-sphere. See what happens as you increase and decrese the values for each shape’s dimensions. Remember to use relatively low values for the size of each primitive unless you want it to take up the entire screen and block out the rest of your page.

    Finally, mess around some with the color of each shape. You can use an HTML color-picker like this one to change each shape’s color.

    Back to navigation.

  7. Change the background

    TL;DR: You can use any ‘equirectangular’ picture as a background for your VR webpage.

    A-Frame lets you create a background for your page using an a-sky primitive like the one at line 31 of index.html. The a-sky element uses src to call an external image into the webpage in much the same way our script tags call in the A-Frame library. You can create your own background image or find one online. However, your background image has to be ‘equirectangular:’ it has to have a 2:1 width to height ratio.

    Let’s change the background on this page.

    Online photo-sharing sites like Flickr have equirectangular photo groups you can browse for images to use in your a-sky element. Broswe for the image you want. Try to use pictures that have Creative Commons licenses, like CC-BY or CC-BY-SA, to avoid copyright issues and to include easily shareable, openly licensed assets in your work.

    Once you’ve found your image, control-click or right-click it to ‘copy image address.’ Next, paste that image’s URL (or web address) into the quotation marks following src in a-sky. Take a look at index.html in Thimble’s preview pane to see how your background has changed.

    Back to navigation.

  8. Change the lighting

    TL;DR: You can position the a-light element to match a light source in your background picture.

    After you update your background image using a-sky, revisit the position attrbiute of a-light at line 32 of index.html. Try to match the position of a-light with the position of a light source in your background. Look for obvious sources such as the sun or a candle. Then approximate where you should place a-light using the x-y-z coordinates in position.

    You can add multiple light sources with different colors and positions if you need to.

    Once you’re satisfied with the way light and shadow interact with your shapes, hit ‘Publish’ in the upper right-hand corner of the Thimble interface. Describe your project, publish it, and share the link to your first Web VR project with the world!

    Back to navigation.

Congratulations! You’ve built your first 3D, VR site on the Web! Keep working with A-Frame to create more complex, explorable projects online.