title | type | layout | parent_section | source_code | examples |
---|---|---|---|---|---|
position |
components |
docs |
components |
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: