Transforms
Position, rotate and scale entities with Transform, read their world position from GlobalTransform, and build parent and child hierarchies.
On this page
Every entity that has a place in the world has a Transform: a translation, a rotation and a scale. It's relative to the entity's parent, or to the world if it has none. The engine works out each entity's world-space GlobalTransform from it once per frame.
NEO's 3D coordinates are right-handed with Y up: X points right, Y up, and the default camera looks down −Z. 2D uses the same axes, with Z only ordering what draws on top.
Transform#
commands.spawn((
Mesh3d(mesh),
MeshMaterial3d(material),
Transform::from_xyz(0.0, 1.0, 0.0)
.with_rotation(Quat::from_rotation_y(0.5))
.with_scale(Vec3::splat(2.0)),
));| Field | Type | What it is |
|---|---|---|
translation | Vec3 | Position. |
rotation | Quat | Orientation. |
scale | Vec3 | Size along each local axis. Vec3::ONE is unscaled. |
Adding a Transform also adds a GlobalTransform, so you don't spawn that yourself.
Making one#
| Constructor | Makes |
|---|---|
Transform::IDENTITY, Transform::default() | At the origin, unrotated, unscaled. |
from_xyz(x, y, z), from_translation(v) | At a position. |
from_rotation(q), from_scale(v) | With a rotation or scale. |
from_matrix(m), from_isometry(iso) | From a matrix or an Isometry3d. |
.with_translation(v), .with_rotation(q), .with_scale(v) | A copy with one part changed. |
.looking_at(target, up), .looking_to(direction, up) | A copy rotated so its forward (−Z) points at a target or along a direction. |
Moving and turning#
fn steer(time: Res<Time>, mut q: Query<&mut Transform, With<Ship>>) {
for mut transform in &mut q {
let forward = transform.forward();
transform.translation += forward * 5.0 * time.delta_secs();
transform.rotate_y(0.8 * time.delta_secs());
}
}| Method | What it does |
|---|---|
forward(), back(), left(), right(), up(), down() | The entity's local directions as Dir3. Forward is −Z, right is +X, up is +Y. |
local_x(), local_y(), local_z() | The local axes. |
rotate(q), rotate_x/y/z(angle), rotate_axis(axis, angle) | Rotates around world axes. |
rotate_local(q), rotate_local_x/y/z(angle), rotate_local_axis(axis, angle) | Rotates around the entity's own axes. |
rotate_around(point, q), translate_around(point, q) | Orbits a point, with or without turning. |
look_at(target, up), look_to(direction, up) | Turns in place to face a point or a direction. |
align(main_axis, main_dir, secondary_axis, secondary_dir) | Turns so one local axis points along a direction and a second one as close as possible to another. |
transform_point(p), mul_transform(t) | Applies the transform to a point, or combines two transforms. |
Angles are in radians. Examples: cargo run --example translation, 3d_rotation, scale, align, transform.
GlobalTransform#
GlobalTransform is the entity's final place in the world, after its parents' transforms are applied. Read it when you need a world-space position, for example to aim at another entity that sits in a hierarchy:
fn aim(target: Single<&GlobalTransform, With<Target>>, mut turrets: Query<&mut Transform, With<Turret>>) {
let target_pos = target.translation();
for mut transform in &mut turrets {
transform.look_at(target_pos, Vec3::Y);
}
}| Method | Returns |
|---|---|
translation(), rotation(), scale() | The world-space parts. |
compute_transform() | The whole thing as a Transform. |
to_matrix(), affine() | As a matrix. |
forward(), right(), up() and the others | World-space directions. |
reparented_to(parent) | The Transform that keeps this entity in place under a new parent. |
Don't write GlobalTransform yourself: the engine overwrites it. Change the Transform instead.
When the world transform updates#
The engine computes GlobalTransform in PostUpdate, in the TransformSystems::Propagate set (and once in PostStartup). So:
- After you change a
TransforminUpdate, itsGlobalTransformstill holds last frame's value untilPostUpdate. - A system in
PostUpdatethat needs this frame's values should run.after(TransformSystems::Propagate). - When you need an up-to-date world transform in the middle of
Update, use theTransformHelpersystem parameter:
fn check(helper: TransformHelper, q: Query<Entity, With<Hand>>) {
for hand in &q {
if let Ok(global) = helper.compute_global_transform(hand) {
info!("hand at {}", global.translation());
}
}
}TransformHelper walks up the hierarchy each call, so use it only where you need it.
Parents and children#
An entity with a ChildOf(parent) component moves with its parent: its Transform is relative to the parent's. The parent gets a Children list automatically.
commands.spawn((
Name::new("Car"),
Transform::from_xyz(0.0, 0.5, 0.0),
children![
(Name::new("Wheel FL"), Transform::from_xyz(-0.8, 0.0, 1.2)),
(Name::new("Wheel FR"), Transform::from_xyz(0.8, 0.0, 1.2)),
],
));- Despawning the parent despawns its children too.
- Every entity in a hierarchy needs a
Transform(and so aGlobalTransform), or the children can't be placed. The engine warns when a parent is missing one. - To move an entity to a new parent and keep it where it is on screen, use
commands.entity(e).set_parent_in_place(new_parent);remove_parent_in_place()makes it a root without moving it. Plaininsert(ChildOf(p))keeps the localTransform, so the entity jumps.
The hierarchy itself (ChildOf, Children, children!, with_child, walking ancestors and descendants) is covered in Relationships.
Static scenes#
Transform propagation skips parts of the hierarchy where nothing changed, which makes large static levels cheap. This is StaticTransformOptimizations::Enabled, the default. For a scene where almost everything moves every frame, StaticTransformOptimizations::Disabled saves the cost of the tracking.