Transforms
@shell/transform is the canonical owner of shared transform components. Renderers, physics, and
spatial packages consume these component identities directly rather than defining or re-exporting
their own copies.
Applications using an engine aggregate can import transform APIs from that aggregate. Standalone
renderers and shared libraries should depend on @shell/transform directly.
Components
Section titled “Components”| Component | Purpose |
|---|---|
Position | Authored simulation position |
Rotation | Authored XYZ Euler rotation |
Scale | Authored XYZ scale |
Anchor | Normalized render anchor |
Pivot | Render pivot |
Size | Render width and height |
Transform | Interpolated local position, rotation, and scale |
PreviousPosition | Previous fixed-step position |
PreviousRotation | Previous fixed-step rotation |
PreviousScale | Previous fixed-step scale |
FixedPosition, FixedRotation, FixedScale | Hidden: the values the fixed steps left this frame |
GlobalPosition | Current hierarchy-derived world position |
GlobalTransform | Interpolated hierarchy-derived world transform |
GlobalTransformMatrix | Exact hierarchy-derived affine matrix, including possible shear |
Flat transforms
Section titled “Flat transforms”TransformPlugin snapshots simulation values during FixedPreUpdate and interpolates them into
Transform during PreRender:
PositionandPreviousPositionproduceTransform.x,y, andz. In 2D,zis the drawing order inside a layer: a higherzis in front, and of equalzusually the entity made later. A child’szis added to its parent’s.RotationandPreviousRotationproduceTransform.rotationX,rotationY, androtationZ.ScaleandPreviousScaleproduceTransform.scaleX,scaleY, andscaleZ.
Adding an authored simulation transform automatically attaches its required previous-state and
Transform components, and the hidden FixedPosition, FixedRotation or FixedScale described
below.
Whatever moves it is drawn evenly
Section titled “Whatever moves it is drawn evenly”Interpolation fits what moves in fixed steps: physics, or a system in FixedUpdate. What moves
after them is drawn where it is, so it is as smooth:
- a script in
Update, a system’s default schedule; - a tween, a timeline or a clip, in
PostUpdate.
How it works:
RecordFixedTransformSystem, the first system ofUpdate, notes the values the fixed steps left (FixedPosition,FixedRotation,FixedScale).- In
PreRender, before interpolation,DrawMovedWhereTheyAreSystemsets the previous value of whatever changed since then to its value. Interpolation then draws it exactly where it is. - Both look only at archetypes whose column changed, so what stands still costs nothing.
- A teleport still jumps.
An entity moved both in a fixed step and after it, in one frame, is drawn at its latest value in that frame, not interpolated.
import { Position, Rotation, Scale, TransformPlugin } from '@shell/transform';
world.addPlugin(TransformPlugin);
const entity = world.get('commands').spawn().root;entity.addComponent(Position, { x: 4, y: 2, z: 0 });entity.addComponent(Rotation, { z: Math.PI / 4 });entity.addComponent(Scale, { x: 2, y: 2, z: 1 });Without HierarchyTransformPlugin, authored transforms are world-space and ECS parent relationships
do not affect them.
Teleportation
Section titled “Teleportation”Use the transforms resource to move an entity without interpolating from its previous position:
world.get('transforms').teleport(entity, { x: 100, y: 50 });Teleportation updates Position, PreviousPosition, and the positional fields of Transform
together, so the rendered local position changes immediately even after interpolation has already
run. Omitted axes retain their current values, rotation and scale are preserved, and velocity is not
changed. The entity must already have Position. With HierarchyTransformPlugin, the destination
is local to the entity’s parent; hierarchy-derived transforms update during hierarchy propagation.
transforms.teleportCount(entity) says how many times an entity was teleported: a camera that
follows it snaps, not glides, when the count changes.
Hierarchy transforms
Section titled “Hierarchy transforms”Install HierarchyTransformPlugin when child transforms should be relative to their parents. It
depends on TransformPlugin, so only the hierarchy plugin needs to be installed:
import { GlobalPosition, HierarchyTransformPlugin, Position } from '@shell/transform';
world.addPlugin(HierarchyTransformPlugin);
const commands = world.get('commands');const parent = commands.spawn().root.addComponent(Position, { x: 10, y: 5 });const child = commands.spawn().root.addComponent(Position, { x: 2, y: 3 });
child.setParent(parent);
// After the next tick, the child's GlobalPosition is (12, 8, 0).const worldPosition = child.getComponent(GlobalPosition);With this plugin installed:
Position,Rotation, andScaleare local simulation state relative to the parent.Transformremains the interpolated local transform.GlobalPositionis the current world-space simulation position.GlobalTransformis the interpolated world-space position, rotation, and scale.GlobalTransformMatrixis the exact interpolated world-space affine transform.
Hierarchy nodes without local transform components use an identity local transform, so they can organize entities while forwarding inherited transforms to descendants.
Timing
Section titled “Timing”PropagateGlobalPositionSystem runs at PostUpdate after ordinary Update movement.
PropagateGlobalTransformSystem runs at PreRender after InterpolateTransformSystem. Fixed-step
physics or spatial systems that need hierarchy-aware world coordinates require explicitly ordered
fixed-schedule propagation.
The PostUpdate walk can write GlobalTransform and GlobalTransformMatrix too, from the same
world matrices, where they are the drawn ones: where each entity’s Transform is its Position,
Rotation and Scale. It leaves them to the PreRender walk, for an entity and what is under it,
where something is drawn apart: between two fixed steps, or by a Transform set by hand. An entity
that came into another archetype this frame (spawned, or given or rid of a component) is left to it
only where interpolation will not draw it at its place: for example, it has no Transform, or a
part of its Transform was set by hand with nothing to interpolate it from (a place with no
Position). The
other entities of that archetype are as they were. So the PreRender walk passes the hierarchy
over, a frame that spawns into it too, unless it was left something, or something in it is drawn
apart or changed after the PostUpdate walk. Between
the two walks, an entity left to the PreRender walk can hold last frame’s globals, or the defaults
of globals just added: read GlobalTransform after PropagateGlobalTransformSystem for the drawn
values of this frame.
Both systems are change-driven. An entity is recomputed only when its own local transform, its
parent, or an ancestor changed, and only then are its global components written and marked changed.
They are not compared with what they held: a change too small to show in a stored global, as a child
moved by 1 under a parent at 100,000,000, is marked all the same. A hierarchy that stands still costs about what the same entities cost as
roots, and a renderer that follows Changed(GlobalTransform) leaves it alone. Global components are
derived: write local transforms only.
Affine transforms
Section titled “Affine transforms”GlobalTransformMatrix stores the upper 3x4 portion of a column-major affine matrix. Use it when
composed rotation and non-uniform scale produce shear that cannot be represented by decomposed
position, rotation, and scale fields.
Reparenting never rewrites local Position, Rotation, or Scale; the same values are interpreted
relative to the new parent on the next propagation pass.
Renderer support
Section titled “Renderer support”Pixi, Three, and WebGPU import canonical components from @shell/transform. Their package barrels do
not re-export them. Pixi can synchronize GlobalTransform in hierarchy-enabled worlds; Three and
WebGPU currently synchronize local Transform.