Developing with three.js
Note: This documentation is for the old 1.1.0 version of A-Frame. Check out the documentation for the current 1.3.0 version
Being a framework based on three.js, A-Frame provides full access to the three.js API. We’ll go over how to access the underlying three.js scene, objects, and API that lay underneath A-Frame.
<a-scene>maps one-to-one with a three.js scene.
<a-entity>maps to one or more three.js objects.
- three.js’s objects have a reference to their A-Frame entity via
.el, which is set by A-Frame.
When A-Frame entities are nested in parent-child relationships, so are their three.js objects. For example, take this A-Frame scene:
The three.js scene graph will correspond and look like:
three.js is available as a global object on the window:
A-Frame is an abstraction on top of three.js, but we still operate with three.js underneath. A-Frame’s elements have doors that lead to three.js’s scene graph.
The three.js scene is accessible from the
<a-scene> element as
document.querySelector('a-scene').object3D; // THREE.Scene
And every A-Frame entity also has a reference to
document.querySelector('a-entity').sceneEl.object3D; // THREE.Scene
From a component, we access the scene through its entity
Every A-Frame entity (e.g.,
<a-entity>) has its own
THREE.Object3D, more specifically a
contains different types of
Object3Ds. The root
THREE.Group of an entity is
document.querySelector('a-entity').object3D; // THREE.Group
Entities can be composed of multiple types of
Object3Ds. For example,
an entity can be both a
THREE.Mesh and a
THREE.Light by having both
a geometry component and light component:
<a-entity geometry light></a-entity>
Components add the mesh and light under the entity’s root
References to the mesh and light are stored as different types of three.js
objects in the entity’s
But we can access them through the entity’s
entityEl.getObject3D('mesh'); // THREE.Mesh
Now let’s see how these three.js objects were set in the first place.
Object3D on an entity adds the
Object3D to the entity’s
which makes the newly set
Object3D part of the three.js scene. We set the
Object3D with the entity’s
.setObject3D(name) method where the name
For example, to set a point light from within a component:
We set the light with the name
light. To later access it, we can use the
.getObject3D(name) method as described before:
And when we set a three.js object on an A-Frame entity, A-Frame will set a
reference to the A-Frame entity from the three.js object via
entityEl.getObject3D('light').el; // entityEl
There’s also a
.getOrCreateObject3D(name, constructor) method for creating
and setting an
Object3D if one has not been set with the name. This is
commonly used in the case of
THREE.Mesh when both the geometry and material
components need to get or create a mesh. Whichever component gets initialized
first creates the mesh, then the other component gets the mesh.
To remove an
Object3D from an entity, and consequently the three.js scene, we
can use the entity’s
.removeObject3D(name) method. Going back to our example
with the point light, we remove the light when the component is detached:
Every object and the scene (world) in general has their own coordinate space. A parent object’s position, rotation, and scale transformations are applied to its children’s position, rotation, and scale transformations. Consider this scene:
<a-entity id="foo" position="1 2 3">
From the world’s reference point, foo has position (1,2,3) and bar has position (3, 5, 7) since foo’s transformations apply onto bar’s. From foo’s reference point, foo has position (0, 0, 0) and bar has position (2, 3, 4).
Often we will want to transform between these reference points and coordinate spaces. Above was a simple example, but we might want to do operations such as finding the world-space coordinate of bar’s position, or translate an arbitrary coordinate into foo’s coordinate space. In 3D programming, these operations are accomplished with matrices, but three.js provides helpers to make them easier.
Normally, we’d need to call
.updateMatrixWorld () on parent
true. We can use three.js’s
.getWorldPosition (vector) and
To get the world position of an
var worldPosition = new THREE.Vector3();
To get the world rotation of an
var worldQuaternion = new THREE.Quaternion();
Object3D has more functions available for local-to-world transforms:
To obtain a matrix that transforms from world to an object’s local space, get the inverse of the object’s world matrix.
var worldToLocal = new THREE.Matrix4().getInverse(object3D.matrixWorld)
Then we can apply that
worldToLocal matrix to anything we want to transform: