Upgrade the Entities package
This page describes how to upgrade a project from an older version of the Entities package.
Starting with Unity 6.4, the Entities package is a core package and is distributed alongside each version of the Unity Editor. The version of the package follows the Unity release (for example, version 6.6.0 in Unity 6.6) instead of the previous 1.x versioning scheme.
The changes in this guide are grouped by the version you upgrade from, with the most recent versions first. If you upgrade across multiple Unity versions, apply all the sections that cover the versions between your current version and the new one. For example, if you upgrade a project from Entities 1.3, apply every section on this page.
Some deprecated APIs produce console warnings that contain enough instructions to update the code. This page covers only the changes that require more significant updates to your project.
Upgrading from Unity 6.7
Unity 7.0 introduces the following changes:
- Managed components are removed
- Entities Hierarchy window is removed
- Update code that uses the Entities Hierarchy window
Managed components are removed
Unity 7.0 removes managed components and managed shared components. They were deprecated in Unity 6.6, and in Unity 6.7 the APIs that access managed component data cause compilation errors.
If your project contains managed components, the following happens in Unity 7.0:
- If the project contains a class that implements
IComponentData, Entities can't initialize. This also applies to a class in a package, and to a class that no code uses. Unity doesn't create any worlds, so no systems run, and the console displays an error message that names the class. - A shared component that contains managed fields causes the
EA0017compilation error. - The APIs that work with managed components, such as the
GetComponentObjectandAddComponentObjectmethods, theSystemAPI.ManagedAPIclass, and the shared component methods that have theManagedsuffix, are removed or cause compilation errors. - You can't add
UnityEngine.Objecttypes, such asTransform, to entities, or use them in queries. To access a Unity component on a companion GameObject, use theEntityManager.GetCompanion<T>method. For more information, refer to Access Unity components through companion components. - The
UNITY_DISABLE_MANAGED_COMPONENTSandUNITY_DISABLE_MANAGED_SHARED_COMPONENT_WARNINGSscripting symbols have no effect. You can remove them from your project. - If you load a world that you serialized with managed component data, for example with the methods of the
SerializeUtilityclass, Unity throws an exception of typeInvalidOperationException. Serialize the world again in Unity 7.0.
To convert managed components to unmanaged components, refer to Convert managed components to unmanaged components.
Entities Hierarchy window is removed
The Entities Hierarchy window (Window > Entities > Hierarchy (Deprecated)) is removed. Use the Hierarchy window instead. It displays a node for each world below the scene nodes, and each world node contains the subscenes and entities of that world.
The following table contains the features that are removed together with the Entities Hierarchy window, and what to use instead:
| Removed feature | What to use instead |
|---|---|
| The world drop-down menu in the Entities Hierarchy window. | The Hierarchy window displays a node for each world. To choose which types of worlds it displays, use the Type Of Worlds Shown property in Preferences > Entities > Hierarchy Window. For more information, refer to Entities Preferences reference. |
| The Authoring, Runtime, and Mixed data modes. | The Hierarchy window displays authoring GameObjects under their scene, and entities under the node of their world, so you can view both at the same time. |
| Search by entity name, ID, or component. | The search field in the Hierarchy window. To filter by component type, use the t: token, for example t:LocalTransform. To find an entity by its ID, use the id= token. For more information, refer to Search for entities. |
Advanced search syntax, such as the all, none, and any component filters, and filters by shared component value. |
To display the entities that have all of several component types, add one t: token for each type in the Hierarchy window search field. The none and any component filters and the filters by shared component value have no direct replacement. |
| The Update Mode, Minimum Milliseconds Between Hierarchy Update Cycles, Exclude Unnamed Nodes For Search, and Advanced Search properties in Preferences > Entities > Hierarchy Window. | No direct replacement. The Show Hidden Entities and Type Of Worlds Shown properties in Preferences > Entities > Hierarchy Window are still available. They control which entities and worlds the Hierarchy window displays. |
The Window > Search > Node Hierarchy menu item, and the nh: search provider in the Search window. |
The search field in the Hierarchy window. |
| The Open in Search Window item in the component context menu of the Entity Inspector. | The Open in Hierarchy item in the same menu. It opens the Hierarchy window and filters it by the component type. For a shared component, the filter displays all the entities that have the shared component type, regardless of its value. For more information, refer to Component context menu. |
Update code that uses the Entities Hierarchy window
The HierarchySearchProvider class is obsolete, and code that uses it causes a compilation error. The class has no replacement API, remove the code that uses it.
If Editor scripts open the Entities Hierarchy window or the Node Hierarchy search provider with the EditorApplication.ExecuteMenuItem method, update them. The Window/Entities/Hierarchy (Deprecated) and Window/Search/Node Hierarchy menu paths no longer exist, and for these paths the method returns false and writes an error message to the console. To open the Hierarchy window instead, pass the Window/General/Hierarchy menu path to the method.
Upgrading from Unity 6.6
Unity 6.7 introduces the following changes:
- Managed component APIs cause compilation errors
- Migrate PostLoadCommandBuffer to RequestSceneLoaded.ImportEntity
- Remove SubScene.HierarchyColor
- HierarchySearchProvider is deprecated
Managed component APIs cause compilation errors
In Unity 6.7, the APIs that access managed component data are obsolete, and code that uses them causes a compilation error:
- APIs that read or write managed component data, such as the
EntityManager.GetComponentObject,EntityManager.GetSharedComponentManaged, andBaker.AddComponentObjectmethods and theSystemAPI.ManagedAPIclass, cause theCS0619compiler error. - Generic APIs that require an unmanaged type, such as the
SystemAPI.Query<T>andEntityManager.GetSharedComponent<T>methods, cause theCS8377compiler error ifTis a managed component. - An
IJobEntityjob whoseExecutemethod has a managed component parameter causes theSGJE0025source generator error.
Shared components that contain managed fields still produce the EA0017 analyzer warning in Unity 6.7.
To fix these errors, convert your managed components to unmanaged components. For more information, refer to Convert managed components to unmanaged components.
Migrate PostLoadCommandBuffer to RequestSceneLoaded.ImportEntity
The PostLoadCommandBuffer component is obsolete, and code that uses it causes a compilation error.
Replace PostLoadCommandBuffer with the RequestSceneLoaded.ImportEntity field, which you can use to pass the same data to ProcessAfterLoad systems as an entity instead of as recorded commands. To migrate a call site:
- Create an entity in the main world, and add the components that your
EntityCommandBuffercommands created. - Set
ImportEntityto that entity, either in theSceneSystem.LoadParametersthat you give toSceneSystem.LoadSceneAsync, or on the scene meta entity. - Don't change the
ProcessAfterLoadsystem. It queries the same components as it did before.
If your project sets PostLoadCommandBuffer on both a scene meta entity and its section meta entities, set ImportEntity on the section meta entities only, and leave the scene-level value unset. The streaming system read PostLoadCommandBuffer from the section and ignored any PostLoadCommandBuffer on the scene. ImportEntity behaves differently: if the section and the scene reference different entities, the streaming system imports both, and your ProcessAfterLoad systems receive two imported entities.
Don't destroy the entity you created in the main world before the scene load completes, because the streaming system reads from it while the scene loads. Destroy it when your project no longer needs it.
While Unity loads a section of the scene, the streaming system copies the entity you created into that section's streaming world. Unless your ProcessAfterLoad system destroys that copy after it reads the components, Unity moves the copy into the main world together with the rest of the section's entities. PostLoadCommandBuffer doesn't create this copy, so after you make this change, the main world can contain an entity that it didn't contain before.
For more information about how ImportEntity works, refer to RequestSceneLoaded.ImportEntity.
Remove SubScene.HierarchyColor
The SubScene.HierarchyColor property is obsolete, and code that uses it causes a compilation error. The Hierarchy window displays subscenes in the same way as it displays scenes and GameObjects, so it doesn't apply a per-subscene color. Remove the code that uses the property. If your project reads the value for its own purposes, declare a Color field on one of your own components, and read the color from that field instead.
HierarchySearchProvider is deprecated
The HierarchySearchProvider class is obsolete, and code that uses it produces an obsolete API warning. The class is the search provider of the deprecated Entities Hierarchy window, and it has no replacement API. To filter entities by component type, use the t: token in the search field of the Hierarchy window. For more information, refer to Search for entities.
Upgrading from Unity 6.5
Unity 6.6 introduces the following changes:
- Convert managed components to unmanaged components
- Change EntityCommandBuffer PlaybackPolicy code
- Update code that relies on placeholder entities
- Entities Hierarchy window is deprecated
Convert managed components to unmanaged components
Managed components (IComponentData) and managed shared components (ISharedComponentData) are deprecated in Unity 6.6. In Unity 6.7, the APIs that access managed component data cause compilation errors, and Unity 7.0 removes managed components.
The following component types are managed:
- A component is managed if it's a class that implements
IComponentData. A struct that implementsIComponentDatacan't contain managed (reference-type) fields. If it does, Unity reports an error that says that the field type isn't supported in a component. - A shared component is always a struct. It's managed if it contains managed fields, such as
stringor other classes.
When you open a project that uses managed components in Unity 6.6:
- APIs that work with managed component types produce obsolete API warnings.
- Shared components that are structs with managed fields produce the
EA0017analyzer warning. To temporarily silence this warning while you migrate, define theUNITY_DISABLE_MANAGED_SHARED_COMPONENT_WARNINGSscripting symbol.
To convert a managed component to an unmanaged one, declare it as a struct that contains only unmanaged fields:
- Replace references to
UnityEngine.Objectinstances (such as materials, meshes, orScriptableObjectassets) withUnityObjectRef<T>. In Unity 6.6, accessing an object throughUnityObjectRef<T>is significantly faster than in previous versions, which makes it a suitable replacement for a managed reference. For more information, refer to Reference Unity objects in your code. - Replace
stringfields with one of theUnity.Collections.FixedStringtypes. - Replace managed collections, such as arrays and lists, with a dynamic buffer or a blob asset.
Some managed types, such as AnimationCurve, have no unmanaged equivalent. To keep such data on an entity without a managed component, store it in a ScriptableObject instance that you create at bake time, and reference that instance from an unmanaged component. To do this:
- Define a class that inherits from
ScriptableObjectand declares the managed fields you want to keep. - In a baker, create an instance of this class with
ScriptableObject.CreateInstance, and copy the managed data from the authoring component into it. - Add an unmanaged component that stores the instance in a
UnityObjectRef<T>field. - In your systems, access the managed data through the
Valueproperty of the reference.
This approach lets you keep using the API of the managed type, but the code that reads the data can't be Burst-compiled. Use it only for data that you can't represent with unmanaged types.
Convert managed shared components
To convert a managed shared component, replace its managed fields with unmanaged types in the same way as for components. Then replace the calls to the methods that have the Managed suffix with the methods that have no suffix. For example, replace the EntityManager.GetSharedComponentManaged method with EntityManager.GetSharedComponent, and the WithSharedComponentFilterManaged method with WithSharedComponentFilter.
Access Unity components through companion components
If your code uses the GetComponentObject<T> method to access a Unity component on a companion GameObject, such as a Light or AudioSource component, use the EntityManager.GetCompanion<T> method instead. It returns the component on the companion GameObject of the entity. Call it on the main thread. If the entity has no CompanionComponent<T> component, the method throws an exception.
Entities Graphics bakes only a fixed set of Unity component types into companion components. For the list of these types, refer to Companion components in the Entities Graphics documentation.
Replace IDisposable and ICloneable
In Unity 6.6 and earlier, Unity calls the Dispose method of a managed component that implements the IDisposable interface when it removes the component or destroys the entity. It calls the Clone method of a managed component that implements the ICloneable interface when it copies the component, for example when it instantiates an entity. Unmanaged components don't support these interfaces:
- To release resources when you destroy an entity or remove a component from it, store the resources in a cleanup component. When you destroy an entity that has a cleanup component, Unity removes the other components but keeps the entity until a system removes the cleanup component. Write a system that queries for entities that have the cleanup component but not the original component. This query finds both the destroyed entities and the entities that you removed the original component from. The system releases the resources and then removes the cleanup component.
- When Unity copies an unmanaged component, it copies the field values, so the copy references the same objects as the original. If each entity needs its own copy of an object, create the copy from a system after Unity instantiates the entity.
Change EntityCommandBuffer PlaybackPolicy code
The PlaybackPolicy enum is obsolete, and using it causes a compile error. This includes both PlaybackPolicy.SinglePlayback and PlaybackPolicy.MultiPlayback, as well as any EntityCommandBuffer constructor overload that takes a PlaybackPolicy parameter.
SinglePlayback is the only supported behavior and is the default: an EntityCommandBuffer can be played back only once. Create an EntityCommandBuffer without specifying a PlaybackPolicy. If you need to apply the same set of commands more than once, record them again into a new EntityCommandBuffer for each playback.
Update code that relies on placeholder entities
In Unity 6.6 the EntityCommandBuffer.CreateEntity and EntityCommandBuffer.Instantiate methods, including their ParallelWriter overloads, return valid Entity references at record time, instead of the placeholder entities that Unity remapped during playback. You can store these references and pass them to other code, and they stay valid before and after playback. As in earlier versions, the entities have no components until you play back the command buffer, so you can't access them through EntityManager or queries until playback completes.
If code in your project specifically detects placeholder entities (for example, by checking for a negative Entity.Index), update it, because command buffers no longer create placeholder entities.
For more information, refer to Entities created by command buffers.
Entities Hierarchy window is deprecated
The Entities Hierarchy window (Window > Entities > Hierarchy (Deprecated)) is deprecated and will be removed in a future release. Entities appear in the standard Hierarchy window alongside GameObjects, scenes, and subscenes, so use that window instead.
Upgrading from Unity 6.4
Unity 6.5 removes the APIs that were deprecated in Entities 1.4, and introduces the following changes:
- Change code that uses
Entities.ForEachandJob.WithCode - Change Aspects code
- Migrate InstanceID code to EntityId
- Journaling API is removed
Change code that uses Entities.ForEach and Job.WithCode
To consolidate the Entities API and improve iteration time, Entities.ForEach is deprecated in Entities 1.4 and removed in Unity 6.5. Use either IJobEntity or SystemAPI.Query instead.
The Job.WithCode API is also removed. Use IJob instead.
IJobEntity
Because IJobEntity Execute methods support ref and in parameters to denote read-only and read-write status, you can often copy the lambda of an Entities.ForEach into the Execute method for the IJobEntity job struct. Additionally, IJobEntity supports all the scheduling options that Entities.ForEach supports.
Note
IJobEntity isn't Burst-compiled by default and it can't capture variables because there is no lambda body. Use the [BurstCompile] attribute to enable Burst compilation and write captured variables into fields on the job struct.
Code example using Entities.ForEach
public partial class RotationSpeedSystemForEachISystem : SystemBase
{
protected override void OnUpdate()
{
float deltaTime = SystemAPI.Time.DeltaTime;
Entities
.ForEach((ref LocalTransform transform, in RotationSpeed rotationSpeed) =>
{
transform.Rotation = math.mul(
math.normalize(transform.Rotation),
quaternion.AxisAngle(math.up(), rotationSpeed.RadiansPerSecond * deltaTime));
})
.ScheduleParallel();
}
}
Code example using IJobEntity
[BurstCompile]
public partial struct ASampleJob : IJobEntity
{
public float DeltaTime;
void Execute(ref LocalTransform transform, in RotationSpeed rotationSpeed)
{
transform.Rotation = math.mul(
math.normalize(transform.Rotation),
quaternion.AxisAngle(math.up(), rotationSpeed.RadiansPerSecond * DeltaTime));
}
}
public partial class ASample : SystemBase
{
protected override void OnUpdate()
{
var deltaTime = SystemAPI.Time.DeltaTime;
new ASampleJob{ DeltaTime = deltaTime }.ScheduleParallel();
}
}
For more information about IJobEntity, refer to Iterate over component data with IJobEntity.
SystemAPI.Query
For entity iteration that doesn't have to happen in a job (but can still be Burst compiled), SystemAPI.Query can provide a simpler option because it uses the RefRO and RefRW types to wrap type parameters that you access as read-only and read-write respectively. There are additional builder methods on Query to indicate WithAll, WithNone, WithAny and other options.
The following changes the previous Entities.ForEach example to use SystemAPI.Query
public partial class ASample : SystemBase
{
protected override void OnUpdate()
{
var deltaTime = SystemAPI.Time.DeltaTime;
foreach (var (transform, rotationSpeed) in
SystemAPI.Query<RefRW<LocalTransform>, RefRO<RotationSpeed>>())
{
transform.ValueRW.Rotation = math.mul(
math.normalize(transform.ValueRO.Rotation),
quaternion.AxisAngle(math.up(), rotationSpeed.ValueRO.RadiansPerSecond * deltaTime));
}
}
}
For more information about SystemAPI.Query, refer to Iterate over component data with SystemAPI.Query.
Change Aspects code
Aspects are deprecated in Entities 1.4 and removed in Unity 6.5, and there's no direct replacement for them. Instead you must replace the abstraction with explicit code that queries for the correct set of components and performs the expected operation on them. The following code provides a simple example of converting an aspect and its usage into an explicit EntityQuery and a helper method designed to perform the operation.
Code example using Aspects:
public partial struct RotationSystem : ISystem
{
[BurstCompile]
public void OnUpdate(ref SystemState state)
{
var deltaTime = SystemAPI.Time.DeltaTime;
var elapsedTime = SystemAPI.Time.ElapsedTime;
foreach (var movement in SystemAPI.Query<VerticalMovementAspect>())
{
movement.Move(elapsedTime);
}
}
}
readonly partial struct VerticalMovementAspect : IAspect
{
readonly RefRW<LocalTransform> m_Transform;
readonly RefRO<RotationSpeed> m_Speed;
public void Move(double elapsedTime)
{
m_Transform.ValueRW.Position.y = (float)math.sin(elapsedTime * m_Speed.ValueRO.RadiansPerSecond);
}
}
Code example using EntityQuery:
public partial struct RotationSystem : ISystem
{
[BurstCompile]
public void OnUpdate(ref SystemState state)
{
var elapsedTime = SystemAPI.Time.ElapsedTime;
foreach (var (transform, speed) in SystemAPI.Query<RefRW<LocalTransform>, RefRO<RotationSpeed>>())
{
VerticalMovementHelper.Move(elapsedTime, transform, speed);
}
}
}
static class VerticalMovementHelper
{
public static void Move(double elapsedTime, RefRW<LocalTransform> transform, RefRO<RotationSpeed> speed)
{
transform.ValueRW.Position.y = (float)math.sin(elapsedTime * speed.ValueRO.RadiansPerSecond);
}
}
Migrate InstanceID code to EntityId
In Unity 6.5, the EntityId struct replaces the InstanceID-based APIs as the identifier that's shared between GameObjects and entities, and the obsolete InstanceID APIs produce compilation errors.
EntityId is a 64-bit value, so this change also affects code that never calls the obsolete APIs directly. For example, if your code stores identifiers as int values, or serializes them, the conversion truncates the identifier and Unity can't resolve it back to an object. For migration instructions that cover these scenarios, refer to the EntityId API migration guide.
Journaling API is removed
The Journaling window and the EntitiesJournaling API were deprecated in Unity 6.5 and are now removed, along with the DISABLE_ENTITIES_JOURNALING scripting symbol and the Journaling Editor preferences. Remove dependencies on this API from your project.
To track when components are added to or removed from entities, implement the IDebugOnAdded and IDebugOnRemoved interfaces on a component type. These callbacks are available in the Unity Editor and in development builds. For more information, refer to Component lifecycle callbacks.
Upgrading from Entities 1.3 or earlier
In Unity 6.4, Entities became a core package included with the Unity Editor, and its version changed from 1.4 to 6.4.0. The 6.4.0 version of the package is functionally equivalent to Entities 1.4: it deprecates Entities.ForEach, Job.WithCode, and Aspects, which are then removed in Unity 6.5. To upgrade from Entities 1.x, apply all the sections above, and additionally:
- Replace the
ComponentLookup.GetRefRWOptionalandComponentLookup.GetRefROOptionalmethods, deprecated in Entities 1.4, withComponentLookup.TryGetRefRWandComponentLookup.TryGetRefRO.
Upgrading from Entities 1.0–1.2
If you upgrade from a version earlier than Entities 1.3, also note the following changes:
- The
EntityQueryCaptureMode.AtRecordenum value is deprecated (Entities 1.3). ForEntityCommandBuffermethods that target anEntityQuery, useEntityQueryCaptureMode.AtPlayback, which is also significantly faster. If you need capture-at-record semantics, capture the array of entities that match the query manually and pass the array to the correspondingEntityCommandBuffercommand. - The
EntityQuery.GetEntityQueryDescmethod is deprecated (Entities 1.3) because it only returns the first query description element. UseEntityQuery.GetEntityQueryDescsto get the full list. - The
EntityManager.CopyEntitiesmethod is deprecated (Entities 1.2). UseEntityManager.Instantiateto create copies of existing entities. - Entities are no longer guaranteed to have the same
Entityvalue across worlds (Entities 1.2). If you useEntityManager.CopyAndReplaceEntitiesFrom, pass a remapping table to the method to look up which entity in the destination world corresponds to a given entity in the source world.