Manual
Manual
Transforms and parents
Where an entity is, how it is turned and how big it is are its Transform, relative to its parent. This page covers the Transform in the Inspector and in code, the world position the engine works out from it, and parents and children: how they are set, what a parent passes down, and when a system sees the result.
Transform
The Transform section of the Inspector has three rows:
| Field | What it does |
|---|---|
| Position | Where the entity is, as X, Y and Z, relative to its parent, or to the world for an entity with none. |
| Rotation | How it is turned, as three angles in degrees about X, Y and Z. |
| Scale | How big it is along each of its own axes; 1 is its natural size. |
The rotation is applied about Z first, then X, then Y, each about the axes as they stand in the world. Three angles are only one way of writing a rotation, so the angles read back from a rotation may differ from those you typed and still mean the same turn. The engine keeps the rotation as a quaternion, and the Inspector's Debug view shows the fields as the engine keeps them, the rotation as the quaternion's four numbers.
The Scene view's Move, Rotate and Scale tools change the Transform too; see The Scene view.
A Transform is Bevy's own Transform, and is optional like any component: an entity that only holds a game's state needs none, and Remove Component takes it off. Many components need one and bring it with them when they are added, such as a mesh or a light. Add Component gives a Transform at the origin, not turned, at scale 1.
A Transform in code
In C#, Transform is a struct with the same memory as Bevy's, which world.Transform() binds to, checking every field against where the Rust compiler put it. Its members:
| Member | What it is |
|---|---|
Rotation | The rotation as a quaternion, a Vector128<float> holding x, y, z and w. |
RotationX, RotationY, RotationZ, RotationW | The quaternion's parts, to read or set one at a time. |
TranslationX, TranslationY, TranslationZ | The position, relative to the parent. |
ScaleX, ScaleY, ScaleZ | The scale along each axis. |
Transform.Identity | At the origin, not turned, at scale 1. |
The zero value is not the identity: it has no size and no rotation. Components start zeroed when a command spawns them, so fill a spawn batch's transforms with Transform.Identity, as Spawning entities shows.
Build rotations with System.Numerics.Quaternion and store them with Vector128.Create. Quaternion.CreateFromYawPitchRoll(yaw, pitch, roll), in radians, turns in the same order as the Inspector's three angles, Y being yaw, X pitch and Z roll.
using System.Numerics;using System.Runtime.CompilerServices;using System.Runtime.Intrinsics;using Abyss.Core;
public static partial class Spinning{ [AbyssSystem] [MethodImpl(MethodImplOptions.AggressiveInlining)] private static void Spin(ref Transform transform, ref Spinner spinner, in SystemContext context) { spinner.Angle += spinner.Speed * context.DeltaTime; Quaternion turn = Quaternion.CreateFromAxisAngle(Vector3.UnitY, spinner.Angle); transform.Rotation = Vector128.Create(turn.X, turn.Y, turn.Z, turn.W); }}
// In a plugin's Build:Spinning.AddSpin(schedule, world.Transform(), world.Component<Spinner>());To read a rotation back as a quaternion, new Quaternion(t.RotationX, t.RotationY, t.RotationZ, t.RotationW).
A system that writes Transform publishes Bevy's change ticks for it by itself, which is what lets the engine see that the entity moved; see Reacting to changes.
Code that runs between frames, such as a flow, reads and writes one entity's transform with world.ReadTransform(entity), null for an entity with none, and world.WriteTransform(entity, transform).
World positions
Each entity with a Transform also has a GlobalTransform: where it is in the world, worked out from its own Transform and those of everything above it. The engine works it out with Bevy's transform propagation, in Bevy's PostUpdate, after your frame's systems have run and their commands have been applied. Read it, and never write it.
GlobalTransform is a matrix rather than a second Transform:
| Member | What it is |
|---|---|
TranslationX, TranslationY, TranslationZ | The world position. |
Translation | The same, as a Vector128<float> whose fourth lane means nothing. |
AxisX, AxisY, AxisZ | The matrix's axes, rotation and scale together, each with a fourth lane that means nothing. |
There is no world rotation to read: it is held inside the axes, and the engine does not take it out for you.
ComponentType<GlobalTransform> global = world.GlobalTransform();ComponentType<Diver> diver = world.Component<Diver>();
schedule.Add("Surface", [global.Read(), diver.Write()], static context =>{ foreach (Chunk chunk in context.Chunks) { ReadOnlySpan<GlobalTransform> places = chunk.GetReadOnlySpan<GlobalTransform>(0); Span<Diver> divers = chunk.GetSpan<Diver>(1); for (int row = 0; row < chunk.Count; row++) { divers[row].Underwater = places[row].TranslationY < 0f; } }});The same frame's positions
Because propagation runs after your systems, a system that reads GlobalTransform sees the positions of the end of the last frame, before this frame's writes to Transform. Usually that is what you want. When a system must see where another system put something in the same frame, add the engine's ResolveTransforms between them:
Following.AddLead(schedule, world.Transform(), world.Component<Leader>()); // writes Transformschedule.AddHosted(EngineSystems.ResolveTransforms); // works out GlobalTransform nowFollowing.AddAim(schedule, world.GlobalTransform(), world.Component<Turret>()); // reads itIt runs alone at the place it was added: every system added before it runs before it, and every one added after runs after. It works out every entity's world position from scratch, without skipping what did not move, so it costs the whole hierarchy each time; Performance has the numbers. Propagation still runs in PostUpdate afterward.
Parents and children
An entity's parent is Bevy's ChildOf component on it, and its children are what the Hierarchy shows under it. A child's Transform is relative to its parent: move, turn or scale the parent and everything under it follows.
Setting a parent in code
A system sets parents with commands, and declares .AndReparent:
context.Commands.SetParent(sword, hand);context.Commands.ClearParent(arrow);SetParent(children, parents) and ClearParent(children) take spans for many at once. The child keeps its Transform as it was, so it is now relative to its new parent, and it moves in the world unless its Transform is set to where it should be under the parent. A pair whose parent is gone by the time the command applies is skipped.
This differs from dragging a row onto another in the Hierarchy, which keeps the entity where it is in the world and works out a new Transform for it under its new parent; see Arrange by dragging.
Instantiate(prefab, position, rotation, parent: hand) places an instance under a parent from the start, its position and rotation relative to it.
Reading parents
Between frames, world.ParentOf(entity) gives the parent, or null for an entity with none. A system reads parents as a column: ChildOf holds the parent's entity, which reads as a ulong:
ComponentLayout childOf = world.LayoutOf("ChildOf");
schedule.Add("Parents", [childOf.Read(), tether.Read()], static context =>{ foreach (Chunk chunk in context.Chunks) { ReadOnlySpan<ulong> parents = chunk.GetReadOnlySpan<ulong>(0); // parents[row] is the entity above row }});ChildOf is read, and never written: a parent is changed only through commands, which keep the hierarchy whole. Its layout refuses Write().
Reading children
Between frames, world.ChildrenOf(entity) gives the entities under it, in the order the Hierarchy lists them, and none for one with no children. A system takes each entity's children as a ChildrenView, passed world.Children():
public static partial class Squads{ [AbyssSystem] [MethodImpl(MethodImplOptions.AggressiveInlining)] private static void Count(ref Squad squad, ChildrenView children) { squad.Members = children.Count; foreach (ulong member in children) { // ... } }}
// In a plugin's Build:Squads.AddCount(schedule, world.Component<Squad>(), world.Children());A view has Count, the child at an index, AsSpan() and foreach. ChildrenColumn gives a chunk's, column[row] being one row's, and a system written by hand gets one with chunk.GetChildren(column), its term world.Children().Read(). An entity with no children carries no Children, so a system that takes them sees only the entities that have some. Children are read, never written: they change as each child's parent does, through the commands above. The view lasts while the system runs, and works in a parallel system too.
Names
An entity's name is Bevy's Name component, what the Hierarchy shows it as. Between frames, world.EntityName(entity) reads it, null for an entity nothing named, and world.SetEntityName(entity, name) sets it. A system takes each entity's name as a NameView, passed world.Name():
[AbyssSystem][MethodImpl(MethodImplOptions.AggressiveInlining)]private static void Rally(ref Squad squad, NameView name){ squad.IsCaptain = name.Is("Captain");}
// In a plugin's Build:AddRally(schedule, world.Component<Squad>(), world.Name());Is compares the name with a string, or with UTF-8 such as "Captain"u8, and makes no string to do it; Utf8 is the name's bytes, and ToString() makes a string of it. NameColumn gives a chunk's, and chunk.GetNames(column) one by hand, its term world.Name().Read(). An entity nothing named carries no Name, so a system that takes names sees only the entities that have one.
A system names an entity with context.Commands.SetName(entity, name), an empty name taking the name away, and declares .AndSetName, since giving or taking a name moves the entity between archetypes.
What a parent passes down
- Its transform. A child's world position is its own Transform on top of its parent's.
- Its scene. A child is always in its parent's scene. An entity put under another takes that one's scene; taken out from under it, it stays in the scene it was in. See Entities and scenes in code.
- Being switched off. The checkbox in the Inspector header, or
world.SetActive(entity, false), switches off the entity and everything under it: no query sees them, so no system updates them and nothing draws them.world.IsActiveInHierarchy(entity)says whether the entity and everything above it are on. - Being hidden. The eye in the Inspector header, or
world.SetVisibility(entity, EntityVisibility.Hidden), stops the entity and everything under it set to inherit from being drawn. Unlike switching off, systems still see and update a hidden entity. - Being despawned. Despawning a parent despawns everything under it.
In the Scripting API
- Transform and GlobalTransform: an entity's place relative to its parent, and in the world.
- EngineSystems:
ResolveTransforms, the world positions worked out part way through a frame. - CommandBuffer:
SetParent,ClearParentandSetName. - World:
ReadTransform,WriteTransform,ParentOf,ChildrenOf,Children,Name,EntityName,SetActiveandSetVisibility. - ChildrenView and ChildrenColumn: an entity's children in a system.
- NameView and NameColumn: an entity's name in a system.
