NOTE: This version of the documentation tracks unstable development happening on A-Frame’s
masterbranch. If you wish to try it out, grab the unstable build. Otherwise, head to the documentation for the current 0.7.0 version
A-Frame represents an entity via the
<a-entity> element. As defined in the
entity-component-system pattern, entities are placeholder objects to
which we plug in components to provide them appearance, behavior, and
Consider the entity below. By itself, it has no appearance, behavior, or functionality. It does nothing:
Or to make it emit light, we can further attach the light component:
We can simply retrieve an entity using DOM APIs.
Once we have an entity, we have access to its properties and methods detailed below.
<a-entity>.components is an object of components attached to the entity. This
gives us access to the entity’s components including each component’s data,
state, and methods.
For example, if we wanted to grab an entity’s three.js camera object or material object, we could reach into its components:
Or if a component exposes an API, we can call its methods:
Whether the entity has attached and initialized all of its components. Though the best way to ensure code is run after the entity is ready is to place code within a component.
Whether the entity is active and playing. If we pause the entity , then
<a-entity>.object3D is a reference to the entity’s three.js
Object3D representation. More specifically,
object3D will be a
THREE.Group object that may contain different types of
as cameras, meshes, lights, or sounds:
We can access the different types of
object3DMap is an object that gives access to the different types
THREE.Object3Ds (e.g., camera, meshes, lights, sounds) that components
We can manage an entity’s set of
THREE.Object3Ds by using
An entity has a reference to its scene element.
addState will push a state onto the entity. This will emit the
event, and we can check the state can for existence using
emit emits a custom DOM event on the entity. For example, we can emit an event to
trigger an animation:
We can also pass event detail or data as the second argument:
The event will bubble by default. we can tell it not to bubble by passing
flushToDOM will manually serialize an entity’s components’ data and update the DOM.
Read more about component-to-DOM serialization.
getAttribute retrieves parsed component data (including mixins and defaults).
componentName is not the name of a registered component,
will behave as it normally would:
getDOMAttribute retrieves only parsed component data that is explicitly
defined in the DOM or via
componentName is the name of a
getDOMAttribute will return only the component data
defined in the HTML as a parsed object.
getDOMAttribute for components is
the partial form of
getAttribute since the returned component data does not
include applied mixins or default values:
Compare the output of the above example of
getObject3D looks up a child
THREE.Object3D referenced by
pause() will stop any dynamic behavior as defined by animations and
components. When we pause an entity, it will stop its animations and call
Component.pause() on each of its components. The components decide to
implement what happens on pause, which is often removing event listeners. An
entity will call
pause() on its child entities when we pause an entity.
For example, the look-controls component on pause will remove event handlers that listen for input.
play() will start any dynamic behavior as defined by animations and
components. This is automatically called when the DOM attaches an entity. When
play(), the entity calls
play() on its child entities.
For example, the sound component on play will begin playing the sound.
componentName is not the name of a registered component or the component is a
setAttribute behaves as it normally would:
componentName is the name of a registered component, it may handle special
parsing for the value. For example, the position component is a
single-property component, but its property type parser allows it to take an
To update component data for a multi-property component, we can pass the name
of a registered component as the
componentName, and pass an object of
properties as the
value. A string is also acceptable (e.g.,
distance: 30), but objects will save A-Frame some work in parsing:
Or to update individual properties for a multi-property component, we can pass
the name of registered component as the
componentName, a property name as the second
argument, and the property value to set as the third argument:
Note that array property types behave uniquely:
- Arrays are mutable. They are assigned by reference so changes to arrays will be visible by the component.
- Updates to array type properties will not trigger the component’s
updatemethod nor emit events.
true is passed as the third argument to
non-specified properties will be reset and clobbered:
setObject3D will register the passed
under the entity’s
object3DMap. A-Frame adds
obj as a child of the entity’s
object3D. An entity will emit the
object3dset event with
setObject3D is called.
componentName is the name of a registered component, along with removing the
attribute from the DOM,
removeAttribute will also detach the component from
the entity, invoking the component’s
remove lifecycle method.
propertyName is given,
removeAttribute will reset the property value of
that property specified by
propertyName to the property’s default value:
removeObject3D removes the object specified by
type from the entity’s
THREE.Group and thus from the scene. This will update the entity’s
object3DMap, setting the value of the
type key to
null. This is generally
called from a component, often within the remove handler:
removeState will pop a state from the entity. This will emit the
stateremoved event, and we can check the state its removal using
|child-attached||A child entity was attached to the entity.|
|child-detached||A child entity was detached from the entity.|
|componentchanged||One of the entity’s components was modified.|
|componentinitialized||One of the entity’s components was initialized.|
|componentremoved||One of the entity’s components was removed.|
|loaded||The entity has attached and initialized its components.|
|pause||The entity is now inactive and paused in terms of dynamic behavior.|
|play||The entity is now active and playing in terms of dynamic behavior.|
|stateadded||The entity received a new state.|
|stateremoved||The entity no longer has a certain state.|
|schemachanged||The schema of a component was changed.|
Below is what the event detail contains for each event:
|child-attached||el||Reference to the attached child element.|
|componentchanged||name||Name of component that had its data modified.|
|id||ID of component that had its data modified.|
|componentinitialized||name||Name of component that was initialized.|
|id||ID of component that had its data modified.|
|componentremoved||name||Name of component that was removed.|
|id||ID of component that was removed.|
|stateadded||state||The state that was attached (string).|
|stateremoved||state||The state that was detached (string).|
|schemachanged||component||Name of component that had it’s schema changed.|
We can use the
componentchanged event to listen for changes to the entity:
We can use the
child-detached events to listen for when
the scene attaches or detaches an entity: