Transforms comparison

Many of the transform operations available in the UnityEngine.Transform class are available in the Entities package, with some key syntax differences.

Unity engine transform property equivalents

UnityEngine property ECS equivalent

childCount

Use SystemAPI.GetBuffer:


int childCount(ref SystemState state, Entity e)
{
  return SystemAPI.GetBuffer(e).Length;
}

forward

Use the Mathematics package normalize with LocalToWorld.Forward. You can omit normalize if you know that the transform hierarchy doesn't have scale:


float3 forward(ref SystemState state, Entity e)
{
  return math.normalize(SystemAPI.GetComponent(e).Forward);
}

localPosition

Use LocalTransform.Position:


float3 localPosition(ref SystemState state, Entity e)
{
  return SystemAPI.GetComponent(e).Position;
}

localRotation

Use LocalTransform.Rotation:


quaternion localRotation(ref SystemState state, Entity e)
{
  return SystemAPI.GetComponent(e).Rotation;
}

localScale

Use LocalTransform.Scale and PostTransformMatrix:


float3 localScale(ref SystemState state, Entity e)
{
  float scale = SystemAPI.GetComponent(e).Scale;
  if ( SystemAPI.HasComponent(e))
  {
    // If PostTransformMatrix contains skew, returned value will be inexact,
    // and diverge from GameObjects.
    float4x4 ptm = SystemAPI.GetComponent(e).Value;
    float lx = math.length(ptm.c0.xyz);
    float ly = math.length(ptm.c1.xyz);
    float lz = math.length(ptm.c2.xyz);
    return new float3(lx, ly, lz) * scale;
  }
  else
  {
    return new float3(scale, scale, scale);
  }
}

localToWorldMatrix

Use LocalToWorld.Value:


float4x4 localToWorldMatrix(ref SystemState state, Entity e)
{
  return SystemAPI.GetComponent(e).Value;
}

lossyScale

Use LocalToWorld.Value and the Mathematics package length:


float3 lossyScale(ref SystemState state, Entity e)
{
  // If LocalToWorld contains skew, returned value will be inexact,
  // and diverge from GameObjects.
  float4x4 l2w = SystemAPI.GetComponent(e).Value;
  float lx = math.length(l2w.c0.xyz);
  float ly = math.length(l2w.c1.xyz);
  float lz = math.length(l2w.c2.xyz);
  return new float3(lx, ly, lz);
}

parent

Use Parent.Value:


Entity parent(ref SystemState state, Entity e)
{
  return SystemAPI.GetComponent(e).Value;
}

position

Use LocalToWorld.Position:


float3 position(ref SystemState state, Entity e)
{
  return SystemAPI.GetComponent(e).Position;
}

right

Use the Mathematics package normalize with LocalToWorld.Right. You can omit normalize if you know that the transform hierarchy doesn't have scale:


float3 right(ref SystemState state, Entity e)
{
  return math.normalize(SystemAPI.GetComponent(e).Right);
}

root

Use Parent.Value:


Entity root(ref SystemState state, Entity e)
{
  while (SystemAPI.HasComponent(e))
  {
    e = SystemAPI.GetComponent(e).Value;
  }
  return e;
}

rotation

Use LocalToWorld.Value:


quaternion rotation(ref SystemState state, Entity e)
{
  return SystemAPI.GetComponent(e).Value.Rotation();
}

up

Use the Mathematics package normalize with LocalToWorld.Up. You can omit normalize if you know that the transform hierarchy doesn't have scale:


float3 up(ref SystemState state, Entity e)
{
  return math.normalize(SystemAPI.GetComponent(e).Up);
}

worldToLocalMatrix

Use the Mathematics package inverse with LocalToWorld.Value. You can omit normalize if you know that the transform hierarchy doesn't have scale:


float4x4 worldToLocalMatrix(ref SystemState state, Entity e)
{
  return math.inverse(SystemAPI.GetComponent(e).Value);
}

Properties with no equivalent

The following properties have no equivalent in the Entities package:

Unity engine transform method equivalents

UnityEngine method ECS equivalent

DetachChildren

Use the following:


void DetachChildren(ref SystemState state, Entity e)
{
  DynamicBuffer buffer = SystemAPI.GetBuffer(e);
  state.EntityManager.RemoveComponent(buffer.AsNativeArray().Reinterpret(),
                                      ComponentType.ReadWrite());
}

GetChild

Use the following:


Child child(ref SystemState state, Entity e, int index)
{
  return SystemAPI.GetBuffer(e)[index];
}

GetLocalPositionAndRotation

Use the following:


void GetLocalPositionAndRotation(ref SystemState state, Entity e, out float3 localPosition, out quaternion localRotation)
{
  LocalTransform transform = SystemAPI.GetComponent(e);
  localPosition = transform.Position;
  localRotation = transform.Rotation;
}

GetPositionAndRotation

Use the following:


void GetPositionAndRotation(ref SystemState state, Entity e, out float3 position, out quaternion rotation)
{
  LocalToWorld l2w = SystemAPI.GetComponent(e);
  position = l2w.Value.Translation();
  rotation = l2w.Value.Rotation();
}

InverseTransformDirection

Use the following:


float3 InverseTransformDirection(ref SystemState state, Entity e, float3 direction)
{
  LocalToWorld l2w = SystemAPI.GetComponent(e);
  return math.inverse(l2w.Value).TransformDirection(direction);
}

InverseTransformPoint

Use the following:


float3 InverseTransformPoint(ref SystemState state, Entity e, float3 position)
{
  LocalToWorld l2w = SystemAPI.GetComponent(e);
  return math.inverse(l2w.Value).TransformPoint(worldPoint);
}

InverseTransformVector

Use the following:


float3 InverseTransformVector(ref SystemState state, Entity e, float3 vector)
{
  return math.inverse(SystemAPI.GetComponent(e).Value)
         .TransformDirection(vector);
}

IsChildOf

Use the following:


bool IsChildOf(ref SystemState state, Entity e, Entity parent)
{
  return SystemAPI.HasComponent(e)
         && SystemAPI.GetComponent(e).Value == parent;
}

LookAt

Use the following:


void LookAt(ref SystemState state, Entity e, float3 target, float3 worldUp)
{
  if (SystemAPI.HasComponent(e))
  {
    Entity parent = SystemAPI.GetComponent(e).Value;
    float4x4 parentL2W = SystemAPI.GetComponent(parent).Value;
    target = math.inverse(parentL2W).TransformPoint(target);
  }
  LocalTransform transform = SystemAPI.GetComponent(e);
  quaternion rotation = quaternion.LookRotationSafe(target, worldUp);
  SystemAPI.SetComponent(e, transform.WithRotation(rotation));
}

Rotate

In the Entities transform system, rotation is always expressed as a quaternion, and an angle is always in radians. There is functionality in the Mathematics package library to convert Euler angles into quaternions, and to convert degrees into radians.

With Space.Self, or if the entity has no parent:


public void Rotate(ref SystemState state, Entity e, quaternion rotation)
{
  LocalTransform transform = SystemAPI.GetComponent(e);
  rotation = math.mul(rotation, transform.Rotation);
  SystemAPI.SetComponent(e, transform.WithRotation(rotation));
}

With Space.World, and the entity may have a parent:


void Rotate(ref SystemState state, Entity e, quaternion rotation)
{
  if (SystemAPI.HasComponent(e))
  {
    Entity parent = SystemAPI.GetComponent(e).Value;
    float4x4 parentL2W = SystemAPI.GetComponent(parent).Value;
    rotation = math.inverse(parentL2W).TransformRotation(rotation);
  }
  LocalTransform transform = SystemAPI.GetComponent(e);
  rotation = math.mul(rotation, transform.Rotation);
  SystemAPI.SetComponent(e, transform.WithRotation(rotation));
}

RotateAround

Use the following:


public void RotateAround(ref SystemState state, Entity e, float3 point, float3 axis, float angle)
{
  // Note: axis should be of unit length
  if (SystemAPI.HasComponent(e))
  {
    Entity parent = SystemAPI.GetComponent(e).Value;
    float4x4 parentL2W = SystemAPI.GetComponent(parent).Value;
    float4x4 invParentL2W = math.inverse(parentL2W);
    point = invParentL2W.TransformPoint(point);
    axis = invParentL2W.TransformDirection(axis);
  }
  var transform = SystemAPI.GetComponent(e);
  var q = quaternion.AxisAngle(axis, angle);
  transform.Position = point + math.mul(q, transform.Position - point);
  transform.Rotation = math.mul(q, transform.Rotation);
  SystemAPI.SetComponent(e, transform);
}

SetLocalPositionAndRotation

Use the following:


void SetLocalPositionAndRotation(ref SystemState state, Entity e, float3 localPosition, quaternion localRotation)
{
  SystemAPI.SetComponent(e, LocalTransform.FromPositionRotation(localPosition, localRotation));
}

SetParent

Without worldPositionStays:


void SetParent(ref SystemState state, Entity e, Entity parent)
{
  SystemAPI.SetComponent(e, new Parent { Value = parent});
}

With worldPositionStays:


void SetParent(ref SystemState state, Entity e, Entity parent)
{
  float4x4 childL2W = SystemAPI.GetComponent(e).Value;
  float4x4 parentL2W = SystemAPI.GetComponent(parent).Value;
  float4x4 temp = math.mul(math.inverse(parentL2W), childL2W);

  SystemAPI.SetComponent(e, new Parent { Value = parent});
  SystemAPI.SetComponent(e, LocalTransform.FromMatrix(temp));
}

SetPositionAndRotation

If the entity has no parent:


void SetPositionAndRotationA(ref SystemState state, Entity e, float3 position, quaternion rotation)
{
  SystemAPI.SetComponent(e, LocalTransform.FromPositionRotation(position, rotation));
}

If the entity has a parent:


void SetPositionAndRotationB(ref SystemState state, Entity e, float3 position, quaternion rotation)
{
  if (SystemAPI.HasComponent(e))
  {
    Entity parent = SystemAPI.GetComponent(e).Value;
    float4x4 parentL2W = SystemAPI.GetComponent(parent).Value;
    float4x4 invParentL2W = math.inverse(parentL2W);
    position = invParentL2W.TransformPoint(position);
    rotation = invParentL2W.TransformRotation(rotation);
  }
  SystemAPI.SetComponent(e, LocalTransform.FromPositionRotation(position, rotation));
}

TransformDirection

Use the following:


float3 TransformDirection(ref SystemState state, Entity e, float3 direction)
{
  float3 temp = SystemAPI.GetComponent(e).Value.TransformDirection(direction);
  return temp * (math.length(direction) / math.length(temp));
}

TransformPoint

Use the following:


float3 TransformPoint(ref SystemState state, Entity e, float3 position)
{
  return SystemAPI.GetComponent(e).Value.TransformPoint(position);
}

Transformvector

Use the following:


float3 TransformVector(ref SystemState state, Entity e, float3 vector)
{
  return SystemAPI.GetComponent(e).Value.TransformDirection(vector);
}

Translate

With Space.Self, or if the entity has no parent:


void Translate(ref SystemState state, Entity e, float3 translation)
{
  SystemAPI.GetComponentRW(e, false).ValueRW.Position += translation;
}

With Space.World, and the entity may have a parent:


void Translate(ref SystemState state, Entity e, float3 translation)
{
  if (SystemAPI.HasComponent(e))
  {
    Entity parent = SystemAPI.GetComponent(e).Value;
    float4x4 parentL2W = SystemAPI.GetComponent(parent).Value;
    translation = math.inverse(parentL2W).TransformDirection(translation);
  }
  SystemAPI.GetComponentRW(e, false).ValueRW.Position += translation;
}

Methods with no equivalent

The following methods have no equivalent in the Entities package:

Additional resources