Note: This documentation is for the old 0.3.0 version of A-Frame. Check out the documentation for the current 0.5.0 version
An entity is represented by the
<a-entity> element. As defined in the entity-component-system pattern, entities are placeholder objects to which we plug in components in order to provide them apperance, behavior, and functionality.
Table of Contents
- Retrieving an Entity
- addState (stateName)
- emit (name, detail, bubbles)
- flushToDOM (recursive)
- getAttribute (attr)
- getComputedAttribute (attr)
- getObject3D (type)
- getOrCreateObject3D (type, Constructor)
- pause ()
- play ()
- setAttribute (attr, value, componentAttrValue)
- setObject3D (type, obj)
- removeAttribute (attr)
- removeObject3D (type)
- removeState (stateName)
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 all of its properties and methods, which are detailed below.
<a-entity>.components is an object of components attached to the entity. This gives us access to all of the entity’s components including their data, methods, and API.
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 or not the entity is active and playing. If the entity is paused, then
isPlaying will be false.
<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
THREE.Object3Ds such as cameras, meshes, lights, or sounds:
The different types
Object3Ds can be accessed through
THREE.Object3Ds (e.g., camera, meshes, lights, sounds) that may have been registered by components.
THREE.Object3Ds can be managed using
An entity has a reference to its scene element.
addState will push a state onto the entity. This will emit the
stateadded event, and the state can then be checked 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 all of the entity’s components’ data and update the DOM. Read more about component-to-DOM serialization.
getAttribute can be used to retrieve parsed component data. If
attr is the name of a registered component,
getAttribute will return only the component data defined in the HTML as a parsed object.
getAttribute for components is the partial form of
getComputedAttribute since the returned component data does not include applied mixins or default values:
attr is not the name of a registered component,
getAttribute will behave as it normally would:
getComputedAttribute is similar to
getAttribute, but it will return all of the component’s properties for multi-property components. It can be thought of as an analog to
getComputedStyle, which in CSS returns all CSS properties after applying stylesheets and computations.
getComputedAttribute will return all component properties after applying mixins and default values.
Compare the output of the above example of
More often we will want to use
getComputedAttribute to inspect the component’s data. Though sometimes we might want to use
getAttribute to discern which properties were explicitly defined.
getObject3D looks up a child
THREE.Object3D of the entity that is registered under
If the entity does not have a
THREE.Object3D registered under
getOrCreateObject3D will register an instantiated
THREE.Object3D using the passed
Constructor. If the entity does have an
THREE.Object3D registered under
getOrCreateObject3D will act as
pause will stop any dynamic behavior as defined by animations and components. When an entity is paused, it will stop all of its animations and call
Component.pause on each of its components. It is up to the components to implement how they paused, but they generally remove event listeners and background behavior. An entity will call
pause on all of its children when it is paused itself.
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 entity is attached. When an entity calls
play, it will call
play on all of its children.
For example, the sound component on play will begin playing the sound.
attr is not the name of a registered component or the component is a single-property component,
setAttribute behaves mostly as it normally would:
attr 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 object:
To set or replace component data for a multi-property component, we can pass the name of a registered component as the
attr, and pass an object of properties as the
To update individual properties for a multi-property component, we can pass the name of registered component as the
attr, a property name as the second argument, and the property value to set as the third argument:
setObject3D will register the passed
type under the entity’s
obj will be added as a child of the entity’s root
object3D. Passing in the value
obj has the effect of unregistering the
THREE.Object3D previously registered under
attr 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.
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 the state can then be checked for its removal using
|child-attached||A child was attached to the entity.|
|componentchanged||One of the entity’s component’s data was modified.|
|componentremoved||One of the entity’s component was removed.|
|loaded||The entity has attached and initialized all of 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.|
|componentremoved||name||Name of component that was removed.|
|componentchanged||name||Name of component that had its data modified.|
|id||Id of component that had its data modified.|
|newData||Component’s new data, after it was modified.|
|oldData||Component’s previous data, before it was modified.|
|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-attached event to listen for elements being attached: