Transform helper overview

The TransformHelpers class contains extensions to the math library that make it easier for you to work with transformation matrices.

In particular, the extensions help you work with the float4x4 contained in the LocalToWorld component.

Extension methods

You can use the extension methods in TransformHelpers to minimize the usage of matrix math in your code. For example, to transform a point from local space into world space you can use TransformPoint:

float3 myWorldPoint = myLocalToWorld.Value.TransformPoint(myLocalPoint);

Or, to transform a point from world space into local space you can use InverseTransformPoint:

float3 myLocalPoint = myLocalToWorld.Value.InverseTransformPoint(myWorldPoint);

The transformation of rotation and direction are handled in a similar way.

Other methods

There are a few methods that aren't extensions outlined below.

LookAtRotation

The LookAtRotation method computes a rotation so that "forward" points to the target:

float3 eyeWorldPosition = new float3(1, 2, 3);
float3 targetWorldPosition = new float3(4, 5, 6);
quaternion lookRotation = TransformHelpers.LookAtRotation(eyeWorldPosition, targetWorldPosition, math.up());

ComputeWorldTransformMatrix

You can use the ComputeWorldTransformMatrix method to immediately use an entity's precise world-space transformation matrix. For example:

  • When performing a raycast from an entity which might be part of an entity hierarchy, such as the wheel of a car object. The ray origin must be in world-space, but the entity's LocalTransform component might be relative to its parent.
  • When an entity's transform needs to track another entity's transform in world-space, and the targeting entity or the targeted entity are in a transform hierarchy.
  • When an entity's transform is modified in the LateSimulationSystemGroup (after the TransformSystemGroup has updated, but before the PresentationSystemGroup runs), you can use ComputeWorldTransformMatrix to compute a new LocalToWorld value for the affected entity.
public void Foo(ref SystemState state)
{
    // Create a simple hierarchy
    Entity parentEntity = state.EntityManager.CreateEntity(typeof(LocalToWorld), typeof(LocalTransform));
    state.EntityManager.SetComponentData(parentEntity, new LocalToWorld() { Value = float4x4.identity });
    state.EntityManager.SetComponentData(parentEntity, LocalTransform.Identity);

    Entity childEntity = state.EntityManager.CreateEntity(typeof(LocalToWorld), typeof(LocalTransform), typeof(Parent));
    state.EntityManager.SetComponentData(childEntity, new Parent() { Value = parentEntity });
    state.EntityManager.SetComponentData(childEntity, new LocalToWorld() { Value = float4x4.identity });
    state.EntityManager.SetComponentData(childEntity, LocalTransform.Identity);

    // Move the parent
    state.EntityManager.SetComponentData(parentEntity, LocalTransform.FromPosition(1, 2, 3));

    // At this point, both the child's and the parent's LocalToWorld will still be identity, because
    // ParentSystem and LocalToWorldSystem have not run yet.
    float4x4 childLocalToWorldMatrix = SystemAPI.GetComponent<LocalToWorld>(childEntity).Value; // Will be identity

    // The following should really be in an OnCreate() or similar. In that case, you will need to call
    // Lookup.Update in the OnUpdate().
    ComponentLookup<LocalTransform> localTransformLookup = SystemAPI.GetComponentLookup<LocalTransform>(true);
    ComponentLookup<Parent> parentLookup = SystemAPI.GetComponentLookup<Parent>(true);
    ComponentLookup<PostTransformMatrix> postTransformLookup = SystemAPI.GetComponentLookup<PostTransformMatrix>(true);

    // If you absolutely need the child's up to date LocalToWorld before LocalToWorldSystem has run, this is how
    // you do it. It is an expensive operation, so use it carefully.
    TransformHelpers.ComputeWorldTransformMatrix(childEntity, out childLocalToWorldMatrix, ref localTransformLookup, ref parentLookup,
        ref postTransformLookup);
}

Additional resources