Note: This documentation is for the old 0.2.0 version of A-Frame. Check out the documentation for the current 1.2.0 version
- Ease us into the concept of the entity-component-system pattern.
- Provide a more familiar interface with HTML attributes mapping to only a single value.
- Pre-compose useful components together with prescribed defaults to create semantic building blocks out-of-the-box.
A-Frame ships with a handful of primitives for common use cases such as displaying basic geometric primitives, 3D models, and media assets.
Here is an assortment of various primitives in use:
To create a wide red box using the primitives API, we could write:
<a-box color="red" width="3"></a-box>
Once attached, this will expand to:
<a-box color="red" width="3" geometry="primitive: box; width: 3" material="color: red"></a-box>
Thus, it is equivalent to:
<a-entity geometry="primitive: box; width: 3" material="color: red"></a-entity>
Under the hood, we see that primitives extend
<a-entity> as a custom element while providing some defaults. It defaults the
geometry.primitive property to
box. And it maps (i.e., proxies) the HTML
width attribute to the underlying
geometry.width property and the HTML
color attribute to the underlying
Since primitives extends
<a-entity>s, operations that can be done upon entities can be done upon primitives. These operations include:
- Positioning, rotating, and scaling
- Attaching additional components to define additional appearance, behavior, or functionality
- Applying animations
- Specifying mixins
Note that primitives are a helper layer on top of A-Frame’s core API. Thus it is still extremely valuable to grasp the following:
- How the rest of the system works under the hood
- How to compose and configure components onto entities
- How to use the asset management system
If you haven’t already, we heavily recommend skimming through the rest of the documentation.
The following documentation pages for individual primitive elements will:
- Describe what the primitive does in practice
- Describe roughly how the primitive is composed
- Describe which component properties the attributes proxy the value to (e.g.,
material.color, meaning the
colorproperty of the material component)
- Describe any techniques or caveats
A lot of the primitives represent geometric meshes (i.e., shapes with an appearance). Thus, many of them inherit the common mesh attributes. So while attributes such as
src are not listed in the attributes table for primitives such as
<a-plane>, they are there. Remember to refer to common mesh attributes table when noted.