Entity positioning

Development guide

Index icon See index
Search Icon

Entity positioning

All entities, including primitives, glTF models and base entities, have a position, a rotation and a scale. These can be easily configured, as shown below:

<box
  position={{ x: 5, y: 3, z: 5 }}
  rotation={{ x: 180, y: 90, z: 0 }}
  scale={0.5}
/>

Position

position is a 3D vector, it sets the position of the entity’s center on all three axes.

  • By default, coordinates are measured in meters. If you’re positioning a child of a parent entity that has a scale that’s different from 1, the position vector is scaled accordingly.
  • x:0, y:0, z:0 refers is the middle of the scene’s base parcel, at ground level. You can change this by setting a different position on the scene entity, or by editing the base attribute of scene.json. The position of a child entity is relative to the center position of its parent entity, so x:0, y:0, z:0 always refers to the center of the parent, wherever it is in the scene.
<box position={{ x: 5, y: 3, z: 5 }} />

Tip: When previewing a scene locally, a compass appears in the (0,0,0) point of the scene with labels for each axis.

Rotation

rotation is a 3D vector too, but where x, y and z represent the rotation in that axis.

<box rotation={{ x: 180, y: 90, z: 0 }} />

Turn to face the user

You can set an entity to act as a billboard, this means that it will always rotate to face the user. This was a common technique used in 3D games of the 90s, where most entities were planes that always faced the player, but the same can be used with and 3D model. This is also very handy to add to text entities, since it makes them always legible.

<box billboard={7} />

You must provide this setting with a number that selects between the following modes:

  • 0: No movement on any axis
  • 1: Only move in the X axis, the rotation on other axis is fixed.
  • 2: Only move in the Y axis, the rotation on other axis is fixed.
  • 4: Only move in the Z axis, the rotation on other axis is fixed.
  • 7: Rotate on all axis to follow the user.

If the entity is configured with both a specific rotation and a billboard setting, it uses the rotation set on by its billboard behavior.

Turn to face a position

You can set an entity to face a specific position in the scene using lookAt. This is a way to set the rotation of an entity without having to deal with angles.

<box lookAt={{ x: 2, y: 1, z: 3 }} transition={{ lookAt: { duration: 500 } }} />

This setting needs a Vector3Component as a value, this vector indicates the coordinates of the point in the scene that it will look at. You can, for example, set this value to a variable in the scene state that is updated with another entity’s position.

You can use a transition to make movements caused by lookAt smoother and more natural.

If the entity is configured with both a specific rotation and a lookAt setting, it uses the rotation set on by its lookAt behavior.

Scale

scale can either be a number, to maintain the entity’s proportions, or a 3D vector, in case you want to scale the axis in different proportions.

<box scale={0.5} />

Inherit positioning from parent

When an entity is nested inside another, the child entities inherit components from the parents. This means that if a parent entity is positioned, scaled or rotated, its children are also affected. The position, rotation and scale values of children entities don’t override those of the parents, instead these are compounded.

You can include an invisible base entity to wrap a set of other entities and define their positioning as a group.

<entity position={{ x: 0, y: 0, z: 1 }} rotation={{ x: 45, y: 0, z: 0 }}>
  <box position={{ x: 10, y: 0, z: 0 }} scale={2} />
  <box position={{ x: 10, y: 10, z: 0 }} scale={1} />
  <box position={{ x: 0, y: 10, z: 0 }} scale={2} />
</entity>

You can also set a position, rotation and scale for the entire <scene/> entity and affect everything in the scene.

Transitions

In dynamic scenes, you can configure an entity to affect the way in which it moves. By default, all changes to an entity are rendered as a sudden shift from one state to another. By adding a transition, you can make the change be gradual and more natural.

The example below shows a box entity that is configured to rotate smoothly.

<box
  rotation={currentRotation}
  transition={{
    rotation: { duration: 1000, timing: "ease-in" }
  }}
/>

Note: The transition doesn’t make the box rotate, it just sets the way it rotates whenever the value of the entity’s rotation changes, usually as the result of an event.

The transition can be added to affect the following properties of an entity:

  • position
  • rotation
  • scale
  • color
  • lookAt

Note that the transition for each of these properties is configured separately.

 <box
    rotation={currentRotation}
    color={currentColor}
    scale={currentScale}
    transition={{
      rotation: { duration: 1000, timing: "ease-in" },
      color: { duration: 3000, timing: "exponential-in" },
      scale: { duration: 300, timing: "bounce-in" }
    }}
  />

The transition allows you to set:

  • A delay: milliseconds to wait before the change begins occuring.
  • A duration: milliseconds from when the change begins to when it ends.
  • Timing: select a function to shape the transition. For example, the transition could be linear, ease-in, ease-out, exponential-in or bounce-in, among other options.

In the example below, a transition is applied to the rotation of an invisible entity that wraps a box. As the box is off-center from the parent entity, the box pivots like an opening door.

<entity
  rotation={currentRotation}
  transition={{
    rotation: { duration: 1000, timing: "ease-in" }
  }}
>
  <box
    id="door"
    scale={{ x: 1, y: 2, z: 0.05 }}
    position={{ x: 0.5, y: 1, z: 0 }}
  />
</entity>
×
×

Subscribe

The latest tutorials sent straight to your inbox.

×

Share

Share this tutorial with your community.