Introduction to TransformHandle API

Introduction to the TransformHandle API and the key differences from the Transform API.

Read time 3 minutes

Last updated 12 days ago

The

TransformHandle

API is an alternative to the

Transform

API. Unlike the

Transform

component (a managed class),

TransformHandle

is an unmanaged

struct

, which makes it compatible with the Burst compiler in code that runs on the main thread.

While the

TransformHandle

API covers the same core operations as the

Transform

API, its design introduces several key differences described on this page. The

TransformHandle

API ensures compatibility with future entity and GameObject interactions.

Differences with Transform API

The

TransformHandle

API functionality is equivalent to the

Transform

API, the key differences are in the way you access it, and in the implementation details. The

TransformHandle

API works alongside the

Transform

API in Unity 6.

Transform API (Unity 6.2 and earlier)	TransformHandle API (Unity 6.3 and later)
You access the transform using the `GameObject.transform` property.	You access the transform using `gameObject.transformHandle` or `transform.GetTransformHandle` (where `transform` is the `Transform` component).
Returns a `Transform` component reference (managed type).	Returns a `TransformHandle` struct (unmanaged type).
The API is managed and not compatible with the Burst compiler.	Is compatible with the Burst compiler in Burst-compiled code that runs on the main thread. The `TransformHandle` struct isn't thread-safe and throws a safety exception if you access it from a job that implements an interface such as `IJobParallelForTransform` . To read or write transform values from jobs, use the `TransformAccessArray` struct, which you can construct from a `NativeArray<TransformHandle>` collection. For more information, refer to Using TransformHandle with Burst.
Editor and runtime API.	Runtime-only API.

Transform APIs that are not available in the TransformHandle API

The following methods and properties from

Transform

APIs are not available in

TransformHandle

API:

```
GetSiblingIndex
```
/
```
SetSiblingIndex
```
```
Find
```
```
hasChanged
```
property

TransformHandle API without an equivalent in the Transform API

The following

TransformHandle

API elements don't have an equivalent in the

Transform

API.

```
TransformHandle.DirectChildrenEnumerable
```
represents an enumerable of the direct children of a transformHandle, and this enumerable returns a DirectChildrenEnumerator when enumerated.
```
TransformHandle.DirectChildrenEnumerator
```
is an enumerator that goes through the direct children of a transform.
```
TransformHandle.DirectChildren
```
returns a DirectChildrenEnumerable of this transform, which you can use to iterate over direct children with a foreach loop.
```
TransformHandle.GetDirectChildrenEnumerator
```
returns a DirectChildrenEnumerator of this transform, which you can use to manually iterate over direct children.
```
TransformHandle.SubhierarchyEnumerable
```
represents an enumerable of a
```
TransformHandle
```
instance and all of its descendants. When enumerated, it returns a
```
TransformHandle.SubhierarchyEnumerator
```
instance.
```
TransformHandle.SubhierarchyEnumerator
```
is an enumerator that yields a
```
TransformHandle
```
instance and all of its descendants. The
```
TransformHandle
```
instance itself is yielded first, followed by its descendants in depth-first order.
```
TransformHandle.Subhierarchy
```
returns a
```
TransformHandle.SubhierarchyEnumerable
```
instance that you can use to iterate over this
```
TransformHandle
```
instance and all of its descendants with a
```
foreach
```
loop.
```
TransformHandle.GetSubhierarchyEnumerator
```
returns a
```
TransformHandle.SubhierarchyEnumerator
```
instance that you can use to manually iterate over this
```
TransformHandle
```
instance and all of its descendants.

Differences in common operations

The following common operations have a different implementation in

TransformHandle

API.

Check if a transform is valid:

Transform:
```
transform != null
```
TransformHandle:
```
TransformHandle.IsValid
```

Iterate the direct children of the transform:

Transform:
```
foreach (Transform t in transform)
```

TransformHandle:

foreach (TransformHandle t in handle.DirectChildren)

Set a parent of a transform to

None

Transform:
```
transform.SetParent(null)
```

TransformHandle:

transformHandle.SetParent(TransformHandle.None)

Alternative declaration:

TransformHandle h = transformHandle; h.parent = TransformHandle.None;

For specific examples on how to use the API, refer to TransformHandle API examples.

Methods with different argument or return types

The following methods are functionally equivalent, but have different argument types or return types (

Transform

, or

TransformHandle

depending on the API they are called from).

Different argument types:

```
IsChildOf
```
```
LookAt
```
```
SetParent
```
```
Translate
```
(overload)

Different return types:

```
GetChild
```
```
parent
```
```
root
```

Documentation

Development

User Acquisition

Monetization

Industry

Unity Engine

User Manual

Script Reference