NEOLearn

Transforms

Position, rotate and scale entities with Transform, read their world position from GlobalTransform, and build parent and child hierarchies.

Updated October 20, 2026

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#

Rust
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)),
));
FieldTypeWhat it is
translationVec3Position.
rotationQuatOrientation.
scaleVec3Size along each local axis. Vec3::ONE is unscaled.

Adding a Transform also adds a GlobalTransform, so you don't spawn that yourself.

Making one#

ConstructorMakes
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#

Rust
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());
    }
}
MethodWhat 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:

Rust
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);
    }
}
MethodReturns
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 othersWorld-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 Transform in Update, its GlobalTransform still holds last frame's value until PostUpdate.
  • A system in PostUpdate that 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 the TransformHelper system parameter:
Rust
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.

Rust
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 a GlobalTransform), 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. Plain insert(ChildOf(p)) keeps the local Transform, 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.

Next steps#