# Migrate from InstanceID to EntityId > Update code that uses InstanceID-based APIs to the EntityId APIs that Unity uses to identify objects. Unity identifies every object it loads or creates with an object identifier. The [`EntityId`](/engine/6000.3/script-reference/unityengine/entityid.md) struct is the type of that identifier, and it replaces the `int`-based `InstanceID` APIs. `EntityId` unifies the way GameObjects and entities identify Unity objects, and removes legacy assumptions about how object identifiers behave. The `int`-based object identity APIs are obsolete. They still compile and produce deprecation warnings that mention the `EntityId` API. `EntityId` also converts implicitly to and from `int`, so scripts that contain object identifiers in integers keep working without changes. Storing object identity in an `int` assumes that the value has a meaningful sign, a reliable order, and a stable serialized form. None of that is true. Change the types, not just the API names. This migration affects code that uses object identifiers directly. Common examples include Editor extensions, object lookup code, selection code, custom [TreeView](/engine/6000.3/manual/uitoolkits/uielements/uie-element-ref/uie-uxml-element-tree-view.md) implementations, [custom serialization](/engine/6000.3/manual/programming-environment/code-reload-serialization/script-serialization/custom-serialization.md), caches, [object pools](/engine/6000.3/manual/analysis/performance-memory/managed-memory/optimizing-code-managed-memory/reusable-code.md), and packages that store Unity object identifiers in `int` fields. This guide is relevant for Unity object identity APIs. It doesn't apply to shader and GPU instancing identifiers such as `unity_InstanceID` or `SV_InstanceID`. ## Find affected code Because the obsolete APIs produce warnings rather than errors, and because `EntityId` converts implicitly to and from `int`, a clean compile doesn't mean your project is migrated. Use both the deprecation warnings and search for API to update manually. 1. Update Unity packages, embedded packages, and Asset Store packages. 2. Fix the deprecation warnings that name an `EntityId` replacement. 3. Search your project and embedded packages for the following identifiers and patterns: * `GetInstanceID`, `InstanceID`, `instanceID`, `instanceIDs`. * `objectInstanceId` and other field or property names that contain `InstanceID`. * `GetHashCode` calls on `UnityEngine.Object` or `EntityId`. * `int.Parse` or `int.TryParse` near identifier strings. * `ToString` on an `EntityId` or `Object` that is then stored, parsed, or compared. * Sorting and sign checks on identifier values, such as `OrderBy(obj => obj.GetInstanceID())`, `FindObjectsSortMode.InstanceID`, or `id < 0`. 4. Inspect third-party package code if the package vendor hasn't released a version that uses the `EntityId` APIs. For more information, refer to [Handle third-party packages](#handle-third-party-packages). Unity's [automatic script updater](/engine/6000.3/manual/upgrade-guides/apiupdater.md) doesn't migrate the main `InstanceID` APIs such as `GetInstanceID` for you. Use the deprecation warnings, IDE warnings, and a manual code search to find affected code, then update the surrounding data types manually. ## Replace InstanceID APIs Use `EntityId` APIs when the value represents Unity object identity. The following table lists common replacements. | Old API or pattern | Replacement | Check when you migrate | | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `Object.GetInstanceID()` | `Object.GetEntityId()` | Change the receiving type from `int` to `EntityId`. | | `Resources.InstanceIDToObject(int)` | [`Resources.EntityIdToObject(EntityId)`](/engine/6000.3/script-reference/unityengine/resources/entityidtoobject.md) | Pass an `EntityId`, not an integer that you reconstructed by hand. | | `Resources.InstanceIDIsValid(int)` | `Resources.EntityIdIsValid(EntityId)` | Keep validity checks typed as `EntityId`. | | `Resources.InstanceIDToObjectList(NativeArray, List)` | [`Resources.EntityIdsToObjectList(NativeArray, List)`](/engine/6000.3/script-reference/unityengine/resources/entityidstoobjectlist.md) | Change the full array or list pipeline to `EntityId`. | | `Resources.InstanceIDsToValidArray(...)` | `Resources.EntityIdsToValidArray(...)` | Change both NativeArray and Span call sites to `EntityId`. | | `Selection.instanceIDs`, `Selection.activeInstanceID`, `Selection.Contains(int)` | [`Selection.entityIds`](/engine/6000.3/script-reference/unityeditor/selection/entityids.md), [`Selection.activeEntityId`](/engine/6000.3/script-reference/unityeditor/selection/activeentityid.md), [`Selection.Contains(EntityId)`](/engine/6000.3/script-reference/unityeditor/selection/contains.md) | Change selection storage from `int[]` to `EntityId[]`. | | `EditorUtility.InstanceIDToObject(int)` | [`EditorUtility.EntityIdToObject(EntityId)`](/engine/6000.3/script-reference/unityeditor/editorutility/entityidtoobject.md) | This is an Editor API. Use runtime APIs for runtime code. | | `EditorUtility.IsDirty(int)`, `EditorUtility.GetDirtyCount(int)` | [`EditorUtility.IsDirty(EntityId)`](/engine/6000.3/script-reference/unityeditor/editorutility/isdirty.md), [`EditorUtility.GetDirtyCount(EntityId)`](/engine/6000.3/script-reference/unityeditor/editorutility/getdirtycount.md) | Change the identifier that feeds the call, not just the call. | | `LazyLoadReference.instanceID` | [`LazyLoadReference.entityId`](/engine/6000.3/script-reference/unityengine/lazyloadreference1/entityid.md) | Check serialized data that stored the old integer value. | | `[OnOpenAsset]` callback with an `int` parameter | [`[OnOpenAsset]`](/engine/6000.3/script-reference/unityeditor/callbacks/onopenassetattribute.md) callback with an `EntityId` parameter | Search your codebase. The attribute accepts both signatures, so the `int` version compiles without a warning. | | `Physics.BakeMesh(int, bool)` | [`Physics.BakeMesh(EntityId, bool)`](/engine/6000.3/script-reference/unityengine/physics/bakemesh.md) | Change any mesh ID arrays or pools that feed the call. | | `RaycastHit.colliderInstanceID` | [`RaycastHit.colliderEntityId`](/engine/6000.3/script-reference/unityengine/raycasthit/colliderentityid.md) | Change the field or collection that stores the result. | | `TransformAccessArray.Add(int)` | [`TransformAccessArray.Add(EntityId)`](/engine/6000.3/script-reference/unityengine/jobs/transformaccessarray/add.md) | Change the identifier source, including job data. | | `TreeView`, `TreeViewItem`, `TreeViewState` with implicit `int` IDs | [`TreeView`](/engine/6000.3/script-reference/unityeditor/imgui/controls/treeview1.md), [`TreeViewItem`](/engine/6000.3/script-reference/unityeditor/imgui/controls/treeviewitem1.md), [`TreeViewState`](/engine/6000.3/script-reference/unityeditor/imgui/controls/treeviewstate1.md) | Use `EntityId` only when the tree item ID is a Unity object identity. | | `HierarchyProperty` | `HierarchyIterator` | For more information, refer to [Migrate hierarchy iteration](#migrate-hierarchy-iteration). | The table isn't exhaustive. Many other Unity APIs follow the same pattern. For example, `GlobalObjectId`, `EditorUtility`, `InternalEditorUtility`, `GameObject`, `SceneManager`, `DragAndDrop`, `Lightmapping`, `Terrain`, `ContactPoint`, the profiler frame data APIs, and various render pipeline APIs add `EntityId`-typed members alongside the obsolete `int`-typed ones. Any API that accepts, returns, stores, or compares an object `InstanceID` needs the same review. When you migrate, distinguish identifier `int` variables from ordinary `int` variables. An `int` that contains a `UnityEngine.Object` reference must become an `EntityId`. An `int` that stores a temporary local value unrelated to Unity object identity can stay as `int`. ## Change identity data structures to EntityId Don't replace a Unity object identifier with an `int` hash. If the value identifies a Unity object, store the full `EntityId`. Before: ```lang-cs Dictionary states = new(); int id = target.GetInstanceID(); states[id] = state; ``` After: ```lang-cs Dictionary states = new(); EntityId id = target.GetEntityId(); states[id] = state; ``` Use `HashSet` and `Dictionary` for identity maps and sets. These collections can use `EntityId.GetHashCode` internally while still comparing the full `EntityId` value for equality. Don't use `EntityId.GetHashCode` or `Object.GetHashCode` as a stored identifier. The hash code is derived from the internal representation of the `EntityId` and isn't part of the API contract. It isn't a stable serialized format, and it isn't a replacement for the old `int` `InstanceID`. ## Don't rely on the int conversion `EntityId` converts implicitly to and from `int`, so the following code still compiles, and Unity does not display a deprecation warning: ```lang-cs int id = target.GetEntityId(); ``` Treat this only as an intermediate state for code you haven't migrated yet. Change the field, parameter, property, or collection key type: ```lang-cs EntityId id = target.GetEntityId(); ``` Don't derive an identifier from a hash: ```lang-cs int id = target.GetEntityId().GetHashCode(); ``` Some unrelated Unity APIs still use `int` IDs. For example, an IMGUI control ID isn't a Unity object identifier. Don't pass an `EntityId` hash to those APIs unless the API needs only a temporary, non-persistent control ID and your code doesn't depend on unique object identity. To check whether an `EntityId` is set to a value other than `EntityId.None`, use the `EntityId.IsValid` instance method. To check whether the identified object is currently loaded, use `Resources.EntityIdIsValid`. ## Don't infer meaning from the numeric value The old `InstanceID` value was an implementation detail, but some projects used its numeric value to infer object state. Those inferences were never guaranteed behavior, and they don't apply to `EntityId`. Don't use `EntityId` values to infer: * Creation order. * Scene hierarchy order. * Load order. * Runtime-created versus asset-loaded state. * Prefab instance state. * Persistence. In particular, don't check whether an ID is negative. Old code sometimes used `instanceID < 0` to guess whether an object was created at runtime. The sign of an object identifier isn't a supported indicator of anything. After Unity destroys an object, it can reuse that object's identifier value for a different object. Because of this reuse, two objects created one after another can have `EntityId` values in any order. For Editor code that needs to know whether an object is persistent, use the Editor-only API [`EditorUtility.IsPersistent`](/engine/6000.3/script-reference/unityeditor/editorutility/ispersistent.md). To perform similar checks in runtime code, use a project-specific data model instead of interpreting the identifier value. ## Sort by the property you need Don't sort by `InstanceID` or `EntityId` to recover creation order. `EntityId` ordering is arbitrary. Comparison operators and `CompareTo` are useful only when a data structure needs a consistent ordering, such as a sorted collection or binary search. Before: ```lang-cs var objectsInCreationOrder = objects.OrderBy(obj => obj.GetInstanceID()); ``` After: ```lang-cs var objectsByName = objects.OrderBy(obj => obj.name); ``` If your code needs creation order, record creation order explicitly: ```lang-cs readonly List m_CreationOrder = new(); public void Register(GameObject instance) { m_CreationOrder.Add(instance); } ``` If your code needs hierarchy order, sort by hierarchy data such as sibling index, transform path, or another domain-specific key. ### FindObjects APIs [`Object.FindObjectsByType`](/engine/6000.3/script-reference/unityengine/object/findobjectsbytype.md) can sort its results by object identifier when you pass `FindObjectsSortMode.InstanceID`, and [`Object.FindFirstObjectByType`](/engine/6000.3/script-reference/unityengine/object/findfirstobjectbytype.md) returns the first result in that ordering. Neither ordering reflects creation order, hierarchy order, or load order. Identifier sorting is also slow. The Unity engine team measured that the `InstanceID` sort accounted for most of the time spent in `FindObjectsOfType`. Pass `FindObjectsSortMode.None` when order doesn't matter: ```lang-cs var renderers = Object.FindObjectsByType(FindObjectsSortMode.None); ``` If order matters, sort the result by the property your code actually needs: ```lang-cs var renderers = Object.FindObjectsByType(FindObjectsSortMode.None) .OrderBy(renderer => renderer.transform.GetSiblingIndex()) .ToArray(); ``` [`Object.FindAnyObjectByType`](/engine/6000.3/script-reference/unityengine/object/findanyobjectbytype.md) is the single-result API that doesn't depend on identifier ordering. Use it when any matching object is acceptable. If your code needs a specific result, implement an explicit ordered lookup on a batch result. ## Update serialization and saved data Audit any code that stores `InstanceID` values in serialized fields, save files, Editor preferences, caches, or custom asset formats. Examples include: * `[SerializeField] int m_InstanceId`. * `Dictionary` serialized through a custom format. * String data created from `instanceID.ToString`. * Cache files that store object IDs as numbers. * Public plugin APIs that expose object IDs as `int`. Changing an `int` field to `EntityId` changes the structure of serialized data. Unity can't know that an arbitrary serialized `int` field contained an old `InstanceID`. Plan a data migration if the data must survive the upgrade. Object identifiers aren't stable across sessions. Unity assigns them when it loads or creates an object, and the same object gets a different identifier the next time you open the project or start the Player. Don't persist an object identifier and expect it to resolve later, in either its `int` or its `EntityId` form. Don't serialize `EntityId` with `ToString` and parse the result later. The string format is an implementation detail that can change between Unity versions. `ToString` is for display and debugging only. For save games, network protocols, analytics, or similar data, use your own stable identifier. In the Editor, use [`GlobalObjectId`](/engine/6000.3/script-reference/unityeditor/globalobjectid.md) when you need a persistent reference to an asset or scene object. ## Update Editor callbacks For asset-open callbacks, change the `[OnOpenAsset]` callback parameter from `int` to `EntityId`: ```lang-cs using UnityEditor; using UnityEditor.Callbacks; using UnityEngine; public static class OpenAssetHandler { [OnOpenAsset] public static bool OnOpenAsset(EntityId entityId, int line) { Object asset = EditorUtility.EntityIdToObject(entityId); // Custom open behavior. return false; } } ``` `[OnOpenAsset]` recognizes both the `int` and the `EntityId` parameter signatures, so the `int` version compiles without a deprecation warning. Search your codebase explicitly, because neither the compiler nor the IDE-side updater flags the `[OnOpenAsset]` signature for you. Some user-defined callback methods can't be marked obsolete at the declaration site. Search for old callback signatures and fix analyzer warnings from your IDE or Unity tooling. ## Update TreeView code If your Editor extension uses IMGUI [`TreeView`](/engine/6000.3/script-reference/unityeditor/imgui/controls/treeview1.md) APIs, migrate the identifier type deliberately. The non-generic `TreeView`, `TreeViewItem`, and `TreeViewState` types are obsolete. The generic versions let you choose the identifier type: ```lang-cs using UnityEditor.IMGUI.Controls; using UnityEngine; class ObjectTreeView : TreeView { public ObjectTreeView(TreeViewState state) : base(state) { } protected override TreeViewItem BuildRoot() { return new TreeViewItem { id = EntityId.None, depth = -1, displayName = "Root" }; } } ``` Use `EntityId` as the `TIdentifier` only when the tree item represents a Unity object. If the tree item represents another concept, use a stable identifier that belongs to that concept. Existing code that never stored object identity in the tree item ID can move to `TreeView`, `TreeViewItem`, and `TreeViewState` unchanged. Pinning the generic types to `` with a `using` alias reduces the number of edits in large files. Check for type-name collisions. An alias also makes it harder to see which identifier type each tree uses. ## Migrate hierarchy iteration ##migrate-hierarchy-iteration If your Editor code iterates the hierarchy with `HierarchyProperty`, migrate to `HierarchyIterator`. `HierarchyProperty` is obsolete. The class, every method that takes or returns identifiers, and the expanded-set arrays change from `int` to `EntityId`: ```lang-cs // Before var prop = new HierarchyProperty(HierarchyType.GameObjects); int[] expanded = Array.Empty(); while (prop.Next(expanded)) { int id = prop.instanceID; Debug.Log($"Object: {prop.name}, id={id}"); } // After var iter = new HierarchyIterator(HierarchyType.GameObjects); EntityId[] expanded = Array.Empty(); while (iter.Next(expanded)) { EntityId id = iter.entityId; Debug.Log($"Object: {iter.name}, id={id}"); } ``` If your code stores expanded-state arrays as `int[]`, change the storage type to `EntityId[]`. For custom scene search engines, replace `ISceneSearchEngine` with `ISceneSearchEngineV2`, update the `Filter` method signature from `HierarchyProperty` to `HierarchyIterator`, and call the matching `SceneSearch.RegisterEngine` and `SceneSearch.UnregisterEngine` overloads. If your code reads `SceneSearchContext.rootProperty`, switch to `SceneSearchContext.rootIterator`. ## Handle third-party packages A package that still uses the obsolete `InstanceID` APIs compiles, but its deprecation warnings can hide warnings in your own code. If a package still uses the obsolete `InstanceID` APIs: * Update the package through Package Manager or the Asset Store. * Check whether the package is embedded in the `Packages` folder or cached in `Library/PackageCache`. * Remove the package if the project doesn't use it. * Contact the vendor for a version that uses the `EntityId` APIs. * Patch an embedded copy if you must keep using the package before the vendor ships an update. If you maintain code that must support multiple Unity versions, use version guards around the old and new API paths. Choose the version symbol for the first Unity version that contains the replacement API you call. Don't assume one symbol covers every `EntityId` replacement. ## Update automated tests If your project or package includes automated tests, update tests that depend on `InstanceID` ordering or sign. Tests that fail after the migration often rely on old accidental ordering. Don't restore the old behavior by sorting on `EntityId`. Change the test to express the actual requirement. Use order-independent assertions when order isn't part of the contract: ```lang-cs CollectionAssert.AreEquivalent(expectedObjects, actualObjects); ``` Use explicit ordering when order is part of the contract: ```lang-cs var actualObjects = Object.FindObjectsByType(FindObjectsSortMode.None) .OrderBy(component => component.name) .ToArray(); ``` Test Editor extensions and package code after the project compiles. Callback migrations, serialized data migrations, and package patches can fail outside the initial warning list. ## EntityId binary layout Ensure that your code doesn't depend on the binary representation of `EntityId`. The struct doesn't expose its internal fields, and its layout is an implementation detail that can change between Unity versions. Avoid the following: * Storing state in `EntityId` bits. * Performing arithmetic, bitwise operations, or sign checks on `EntityId` values. * Comparing raw bytes of structs that contain `EntityId` fields. * Depending on padding around `EntityId` fields. * Hard-coding an assumption about `sizeof(EntityId)`. Compare struct fields explicitly rather than using raw byte comparisons, and compare `EntityId` values through the `EntityId` API. Use `EntityId.IsValid` to check whether a value is set to a value other than `EntityId.None`. Store `EntityId` values in `EntityId`-typed fields, not in `IntPtr`, `void*`, `nint`, or `int` fields. Aliasing an object identifier with a pointer-sized or integer field makes an assumption about the size of the identifier that isn't part of the API design. The pointer size itself differs between 64-bit platforms such as the Unity Editor and 32-bit runtime platforms. ## Migration checklist Use the following checklist to review your project: * Replace `InstanceID` API calls with the equivalent `EntityId` API calls. * Change identity-related `int` fields, parameters, properties, arrays, and collection keys to `EntityId`, rather than relying on the implicit `int` conversion. * Replace `[OnOpenAsset]` callbacks that take an `int` parameter with the `EntityId` signature. * Update `TreeView` code to use the correct generic identifier type. * Migrate `HierarchyProperty` code to `HierarchyIterator`, including expanded-set arrays. * Remove sign checks such as `id < 0`. * Don't perform arithmetic or bitwise operations on `EntityId` values. * Stop sorting by `InstanceID` or `EntityId` to recover creation order, and pass `FindObjectsSortMode.None` when order doesn't matter. * Stop using `GetHashCode` as an object identifier. * Stop using `ToString` plus integer parsing for serialization. * Audit serialized data and save formats that used `InstanceID`. * Audit code that stores identifiers in pointer-sized fields (`IntPtr`, `void*`, `nint`, `int`). * Update or patch third-party packages that still use `InstanceID` APIs. * Update automated tests that relied on old ordering or sign behavior. ## Additional resources * [`EntityId`](/engine/6000.3/script-reference/unityengine/entityid.md) * [Unity 6.3 upgrade guide](/engine/6000.3/manual/upgrade-guides/upgrade-guide-unity63.md)