GetInstanceId() deprecation

Scripting
, ,
1

GetInstanceId() has been deprecated but the replacement methods return different values:

Debug.Log(gameObject.GetInstanceID()); // deprecated
Debug.Log(gameObject.GetEntityId().GetHashCode());
Debug.Log(gameObject.GetEntityId().GetRawData());

I can understand the reasoning behind this if one wanted a better/hashed distribution but in order to minimize risks, could perhaps the Entityid class expose a way to return the same old GetInstanceId() value and make the API Upgrader to replace old references?

2

Yes these are changes as part of the ‘ECS for All’ initiative and they are meant to return different values. There was a post about it here: ECS Development Status - December 2025

The InstanceId type is being removed in 6.5: Planned breaking changes in Unity 6.5

So instance ID as a concept is going away and everything will have an EntityId instead.

3

Ok, so the equivalent seems to be GetRawData() ? It’s worth to specify it in the manual although this method casts the internal int id to an ulong, so strictly speaking it’s not the same thing. What’s the point of casting the returned value to an “ulong” when internally it’s stored as a single int?

I’d also suggest to rename or provide an implicit pure int operator so int objectId = gameObject.GetEntityId(); would be feasible and the API Upgrader could easily swap the old GetInstanceId().

4

In how far would this minimize risks?

Instance and Entity IDs differing shouldn’t be a problem since these are unique per session only, even exiting and entering playmode could change those IDs. So it really only matters to use them consistently, and change the type from int to ulong ahead of time wherever you use it in your own code.

Note that you can use it like this, there’s an implicit conversion:
Debug.Log(gameObject.GetEntityId());

5

At the moment it’s an int internally to match the instance id but in future versions it will be changed to ulong. This is just a transition period until we get ECS for All

Edit: You can read more here ECS Development Status - December 2025

6

Thanks for the link to the ECS page.

My “avoid potential risks” point is basically about migration ergonomics: making the GetInstanceID() → GetEntityId() transition less error‑prone for existing projects.

The risks I’m trying to reduce are:

  • tons of existing Dictionary<int,…> / HashSet code breaking,
  • people choosing the wrong replacement (eg. using EntityId.GetHashCode()/ToString() instead of the GetRawData() wrapper),
  • Asset Store code needing cross‑Unity-version compatibility.

Given Unity’s direction (moving away from int), the best risk reduction isn’t “keep int forever”, but clear docs (and guidance on how to migrate dictionary/set keys…).

Cheers

7

If you are relying on the raw instanceID values, then there is no way for us to avoid breaking you. The values are changing, both in size and in how we allocate them.

EntityId is intended to be usable as a key type for Dictionary, Set, etc. You should not need to use GetRawData(), and if you do, expect the value you get back to not be stable between Editor sessions or versions.

8

This is the key insight, thanks.

9

Hey, dev here working on it. We actually did that. So in 6.2 we exposed GetEntityId, along with the type itself and an implicit conversion. In 6.3 and 6.4 we added most of the EntityId versions for the api that was previously int InstanceID. (and added obsolete to the int versions) Also in 6.4 we made the implicit int conversion obsolete with warning. In 6.5 we fully obsoleted the int versions, so where you would previously get a warning in 6.4, you now get an error in 6.5. This version also makes EntityId 64bit (which is why GetRawData was returning a ulong)