Introduction
Note: This documentation is for the old 0.1.0 version of A-Frame. Check out the documentation for the current 1.5.0 version
Primitives are concise, semantic building blocks blocks that wrap A-Frame’s underlying entity-component system. A-Frame ships with a handful of built-in primitives for common use cases such as <a-cube>
, <a-model>
, and <a-sky>
. These primitives are to help people get started with using A-Frame. To uncover the full composability and extensibility of A-Frame, dive down into the underlying entity-component system.
Using primitives, to create a red cube that’s 3 meters wide, we can write:
<a-cube width="3" color="red"></a-cube> |
… instead of the more verbose entity-component equivalent:
<a-entity geometry="primitive: box; width: 3" material="color: red"></a-entity> |
Under the hood, <a-cube>
is wrapping <a-entity>
in a custom element, and mapping the HTML width
attribute to the underlying geometry
component’s width property.
Primitives are designed to enable developers to start building A-Frame scenes without having to learn A-Frame’s full entity-component system. By being semantic and concise, they also improve the readability of our markup.
Primitives and entity-component instances can be freely mixed within an A-Frame scene. Entities with components are useful when developers need to go beyond primitives and tap into the deeper power and flexibility of A-Frame’s built-in components, which include material, geometry, light, and more.
Entities can also be very useful for grouping elements (primitives or otherwise):
<a-entity id="tree" position="30 12 86"> |
Primitives work with animations also. To create a cube that spins endlessly, we can write:
<a-cube color="yellow"> |
Adding components directly to primitives to extend their behavior is currently not supported, however, and will lead to unpredictable results.