Reference Unity objects in your code
To store references to UnityEngine.Object types in your code, you can use the UnityObjectRef struct inside an unmanaged IComponentData component. You can then use this reference to access the original object and use it in systems.
For example, you have a GameObject with an Animator object which you want to instantiate and access in a system. You can achieve this by creating an IComponentData struct with a UnityObjectRef field that holds a reference to the GameObject. You can then instantiate this prefab from a system, and use the target Animator component.
Using UnityObjectRef
The following example shows how to define IComponentData types with UnityObjectRef fields and how to use a baker to store a reference to the GameObject prefab during conversion. The first component (AnimatorPrefabRef) holds the prefab reference written by the baker; the second (AnimatorInstanceRef) is added later at runtime to hold the live Animator instance:
public class AnimatorAuthoring : MonoBehaviour
{
public GameObject AnimatorPrefab;
public class AnimatorBaker : Baker<AnimatorAuthoring>
{
public override void Bake(AnimatorAuthoring authoring)
{
var e = GetEntity(TransformUsageFlags.Renderable);
AddComponent(e, new AnimatorPrefabRef
{
Prefab = authoring.AnimatorPrefab
});
}
}
}
public struct AnimatorPrefabRef : IComponentData
{
public UnityObjectRef<GameObject> Prefab;
}
public struct AnimatorInstanceRef : IComponentData
{
public UnityObjectRef<Animator> Animator;
}
You can use SystemAPI to access and instantiate the prefab. The system below copies the entity's LocalToWorld to the spawned GameObject so multiple entities don't pile up at the same position, then adds the AnimatorInstanceRef to the entity:
public partial struct SpawnAnimatedCubeSystem : ISystem
{
EntityQuery m_Query;
public void OnCreate(ref SystemState state)
{
m_Query = SystemAPI.QueryBuilder()
.WithAll<AnimatorPrefabRef, LocalToWorld>()
.WithNone<AnimatorInstanceRef>()
.Build();
state.RequireForUpdate(m_Query);
}
public void OnUpdate(ref SystemState state)
{
var entities = m_Query.ToEntityArray(state.WorldUpdateAllocator);
foreach (var entity in entities)
{
var prefabRef = SystemAPI.GetComponent<AnimatorPrefabRef>(entity);
var worldTransform = SystemAPI.GetComponent<LocalToWorld>(entity);
//Instantiate the GO and place it at the entity's transform
var rotatingCube = Object.Instantiate(prefabRef.Prefab.Value);
rotatingCube.transform.SetPositionAndRotation(worldTransform.Position, worldTransform.Rotation);
//Add the animator to the entity
state.EntityManager.AddComponentData(entity, new AnimatorInstanceRef
{
Animator = rotatingCube.GetComponent<Animator>()
});
}
}
}
You can also access and modify the Animator from a separate system by querying the AnimatorInstanceRef and dereferencing the UnityObjectRef with .Value. The following example shows how to adjust the animation speed dynamically:
public partial struct ModulateAnimatorSpeedSystem : ISystem
{
public void OnUpdate(ref SystemState state)
{
var sineSpeed = 1f + math.sin((float)SystemAPI.Time.ElapsedTime);
//Query and modify the speed of the Animator
foreach (var instanceRef in SystemAPI.Query<AnimatorInstanceRef>())
{
instanceRef.Animator.Value.speed = sineSpeed;
}
}
}
Referencing the same asset in MonoBehaviour and IComponentData code
During a Player build, Unity collects all UntypedWeakReferenceId values from each included subscene. This also includes any WeakObjectReference<T> and WeakObjectSceneReference properties. Any Unity objects directly referenced from entity data (including UnityObjectRef<T>) are also collected and added to a special ScriptableObject that has an UntypedWeakReferenceId created for it.
Unity builds these references into a set of ContentArchive instances that it optimizes for usage and duplication as follows:
- Any objects that are used together are put into the same archive to maximize loading efficiency.
- Any shared objects are put into separate archives to prevent duplication.
- Any objects that have direct references from normal scenes are built directly into Player data, which is separate from the archive data.
If an object is referenced by both normal and entity scenes it is duplicated in both sets of data and each has its own InstanceID at runtime. A normal scene can contain a WeakObjectReference<T> and you can use this reference to load from the archive data at runtime as long as the reference is also included in an entity scene. This setup only includes one copy of the asset in the build.
Limitations
The UnityObjectRef<T> struct has the following limitations:
- The
Valueproperty and the implicit conversion toTreturn a managed object. Use them only on the main thread, and not in jobs or in Burst-compiled code. - A
UnityObjectRef<T>value stores the runtime ID of the object, which is valid only in the current Editor or Player session. When Unity saves an entity scene, it converts the references in components, buffer elements, and shared components, so that they point to the same objects after Unity loads the scene. Unity converts a reference in the following cases:- The reference points to an asset saved in the project, such as a prefab, mesh, material, or
ScriptableObjectasset. - The reference points to an object that a baker creates, such as a
ScriptableObjectinstance created with theScriptableObject.CreateInstancemethod, or a procedural mesh. Unity saves a copy of the object in the entity scene. Unity doesn't save objects that have theHideFlags.DontSaveInBuildflag.
- The reference points to an asset saved in the project, such as a prefab, mesh, material, or
- Unity doesn't convert the references that you save outside entity scenes, for example in the settings of an Editor tool. To save a reference to an object in Editor code, use the
GlobalObjectIdstruct. UnityObjectRef<T>fields aren't supported inside blob asset data. Unity converts object references only in components, buffer elements, and shared components, not in blob data. After Unity loads a blob asset from an entity scene, theValueproperty of aUnityObjectRef<T>field in the blob data might return the original object, for example in the same Editor session, or it might returnnull. Unity doesn't log an error, and a null check doesn't reliably detect the problem. If a component needs both blob data and a reference to a Unity object, store theUnityObjectRef<T>on the component or buffer element that contains theBlobAssetReference.