title: position type: components layout: docs parent_section: components source_code: src/components/position.js
The position component places entities at certain spots in 3D space. Position takes a coordinate value as three space-delimited numbers.
All entities inherently have the position component.
<a-entity position="0 1 -1"></a-entity>
A-Frame uses a right-handed coordinate system where the negative Z axis extends into the screen. The table below assumes looking down the negative Z axis from the origin.
Axis | Description | Default Value |
---|---|---|
x | Negative X axis extends left. Positive X Axis extends right. | 0 |
y | Negative Y axis extends down. Positive Y Axis extends up. | 0 |
z | Negative Z axis extends in. Positive Z Axis extends out. | 0 |
World-space positions of child entities inherit from parent entities. Consider this scene:
<a-entity id="parent" position="1 2 3"> <a-entity id="child1"></a-entity> <a-entity id="child2" position="2 3 4"></a-entity> </a-entity>
The world-space position of #child1
would be 1 2 3
as inherited by the entity. In the local parent's space, #child1
's position would be 0 0 0
.
The world-space position of #child2
would be 3 5 7
, by combining the position with the parent entity. In the parent's local space, #child2
's position would be 2 3 4
.
For performance and ergonomics, we recommend updating position directly via the three.js Object3D .position
Vector3 versus via .setAttribute
.
This method is easier because we have access to all the Vector3 utilities, and faster by skipping .setAttribute
overhead and not needing to create an object to set position:
// With three.js el.object3D.position.set(1, 2, 3); // With .setAttribute (less recommended). el.setAttribute('position', {x: 1, y: 2, z: 3});
We can also do incremental updates (which is just modifying a number) and use Vector3 utilities:
el.object3D.position.x += 1; el.object3D.position.multiplyScalar(2); el.object3D.position.sub(someOtherVector);
To reflect updates done at the three.js level, A-Frame returns the actual Object3D.position
vector object when doing .getAttribute('position')
. Note modifying the return value will modify the entity itself.
See also reading position and rotation of the camera.
Transformations are applied to entities in this order: