Building a Basic Scene
Note: This documentation is for the old 0.2.0 version of A-Frame. Check out the documentation for the current 1.4.0 version
Let’s first start building a scene using primitives, the basic building blocks of A-Frame with familiar HTML syntax. Under the hood, primitives are aliases entities that proxy HTML attribute values to component property values. A-Frame is bundled with a handful of primitives for common use cases such as backgrounds, images, meshes, models, images, and videos.
The simplest scene would be a scene containing a box primitive:
Just like with regular HTML elements, each attribute of the entity maps to one value. We can define a color, width, height, and depth of
<a-box>. To see more attributes that
<a-box> and other geometric primitives can accept, check out the common mesh attributes.
Once we open up our scene, the default control setup allows us to look and walk around. To look around, we can drag the mouse or just look around with a mobile device or a Rift. To walk around, we can use the WASD keys. Then to enter VR, click on the Enter VR button.
A-Frame uses a right-handed coordinate system which can be roughly thought of:
- Positive X-axis as “right”
- Positive Y-axis as “up”
- Positive Z-axis as going out of the screen towards us
The basic distance unit in is defined in meters. When designing a scene for virtual reality, it is important to consider the real world scale of the objects we create. A box with
height="100" may look ordinary on our computer screens, but in virtual reality it will look like a massive 100-meter tall monolith.
And the basic rotational unit is defined in degrees. To determine the positive direction of rotation, we can point our thumbs down the direction of a positive axis, and the direction which our fingers curl is the positive direction of rotation.
To translate, rotate, and scale the box, we can plug in the position, rotation, and scale components. The example below (assuming we are positioned on the origin looking down the negative Z-axis) will translate the box left/up/back, rotate the box to the right, stretches the box left-and-right and back-and-front, and shrinks the box up-and-down:
The box doesn’t have to be just a flat color. We can wrap a texture around the box with an image or video using
src. To make sure the color does not mix with the texture, we set the color to white:
To cache the texture and have the scene wait for it to load before rendering, we can move the texture into the asset management system. We define it as an
<img> tag, give it an ID, and point to it using a selector:
We can add an animation to the box using the built-in animation system. An animation is defined by placing an
<a-animation> tag as a child of the entity to animate. Let’s have the box rotate indefinitely to get some motion into our scene:
To interact with the box via clicking or gazing, we can use a cursor which we place as a child of the camera such that it is fixed to the screen. When we don’t define a camera, the scene will inject a default camera, but in this case to add a cursor, we will need to define one. Then what we can do is to tell the animation only to start when the cursor clicks the box, by having the box emit the
click event, using the animation’s
begin attribute which takes an event name:
var box = document.querySelector('a-box');
We can change how the scene is lit using the light primitive,
<a-light>. By default, the scene will inject an ambient light and a directional light (like the sun). Let’s adjust the lighting conditions of the scene adding different kinds of light:
Finally, we can add a background to the scene using the sky primitive,
<a-sky>. The background can be a color or even a 360-degree image or video. But let’s just keep it simple and use a color:
And that wraps up our basic scene. Once we get past the novelty of placing static objects in a 3D space in HTML, we want to be able to add complex appearance, behavior, and functionality. We can do so by using and writing components.