struct in UnityEditor
Thank you for helping us improve the quality of Unity Documentation. Although we cannot accept all submissions, we do read each suggested change from our users and will make updates where applicable.
CloseFor some reason your suggested change could not be submitted. Please <a>try again</a> in a few minutes. And thank you for taking the time to help us improve the quality of Unity Documentation.
CloseUnique and stable project-scoped identifier for objects in scenes and in other types of assets for use at authoring time.
Use this struct to obtain unique identifiers to objects that are part of scenes or inside other assets such as prefabs and ScriptableObjects. The identifiers are stable and persistent across editing sessions and data serialization operations, such as changing the active scene and saving and reloading.
You can use GlobalObjectId
in your Unity Editor workflows, including writing authoring tools.
Note: GlobalObjectId
identifiers can't be used at application runtime in the Editor's Play mode or in standalone Player builds.
Note: You can't use AssetDatabase.TryGetGUIDAndLocalFileIdentifier for referencing objects that are inside a scene. Use GlobalObjectId
instead.
You can create a GlobalObjectId
for objects that inherit from UnityEngine.Object
and which are inside scenes or in other types of assets such as prefabs and ScriptableObjects.
The format of the string representation of the ID is GlobalObjectId_V1-{i}-{a}-{l}-{p}
, where:
{i}
is the identifier type represented by an integer (0 = Null, 1 = Imported Asset, 2 = Scene Object, 3 = Source Asset).{a}
is the asset GUID. This is a globally unique identifier that Unity assigns to every newly discovered asset. For more information, refer to Asset Metadata in the Manual.{l}
is the local file ID of the object. For objects inside a prefab instance, this ID is the local file ID of the original source object that is part of the prefab.{p}
is the local file ID of the prefab instance of the object. If the object isn't part of a prefab instance, then {p}
is 0
.
Note: Actual local file IDs are signed 64-bit values and can be negative. But in a GlobalObjectId
, these values are cast to GlobalObjectId.targetObjectId, which is an unsigned 64-bit value (ulong
). Therefore, a negative local file ID will lose its sign when saved to a GlobalObjectId
and you should not rely on the value of targetObjectId
, or the {l}
element from the string representation of a GlobalObjectID, to find an object.
Each of these values is stored separately as a property in the GlobalObjectId
struct. The string is not the native representation but can be obtained from GlobalObjectId.ToString.
The default null ID is GlobalObjectId_V1-0-00000000000000000000000000000000-0-0
.
To obtain the GlobalObjectId
for an object or an array of objects based on the object reference or instance ID, use GlobalObjectId.GetGlobalObjectIdSlow or GlobalObjectId.GetGlobalObjectIdsSlow.
For objects that are inside a scene (those for which GlobalObjectId.identifierType = 2
), the GlobalObjectId
includes the scene ID as the assetGUID
, which means the following:
GlobalObjectId
.GlobalObjectId
for an object in the current scene. Otherwise, the assetGUID
value is null.GlobalObjectId
that refers to an object inside a scene can be resolved back to an instance ID or object only when that scene is already loaded.The following performance considerations apply for GlobalObjectId
in general:
GlobalObjectId
objects, it's always faster to make a single call using the batch methods rather than making individual calls. For example, a single call to GlobalObjectIdentifiersToObjectsSlow
is much faster then making multiple calls to GlobalObjectIdentifierToObjectSlow
.Slow
to indicate that they have performance impacts. If you use these methods in a large project within other performance-sensitive contexts such as ISerializationCallbackReceiver.OnBeforeSerialize or ISerializationCallbackReceiver.OnAfterDeserialize, it's strongly recommended to profile the performance impact.// Create an empty C# in your project and paste in the following code.
using UnityEngine; using UnityEditor; using UnityEditor.SceneManagement;
// The example creates a new Editor menu item called Example. When you select Example > GlobalObjectId, // the code creates a new scene with two GameObjects called MyPlane and MyCube and obtains the // GlobalObjectIds for these objects. The code then reloads the scene and uses the GlobalObjectIds to // obtain references to the original MyPlane and MyCube objects, printing conformation to the console. public class GlobalObjectIdExample { [MenuItem("Example/GlobalObjectId")] static void MenuCallback() { const string testScenePath = "Assets/MyTestScene.unity";
var stringIds = CreateSceneWithTwoObjects(testScenePath);
// These string-formatted IDs can be saved to a file, then retrieved in a later session of Unity. Debug.Log("IDs of new objects " + stringIds[0] + " and " + stringIds[1]);
ReloadSceneAndResolveObjects(testScenePath, stringIds); }
static string[] CreateSceneWithTwoObjects(string testScenePath) { var scene = EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
// Scene must have been serialized at least once prior to generating GlobalObjectIds, so that the asset GUID is available. EditorSceneManager.SaveScene(scene, testScenePath);
// Create objects in scene. var objects = new Object[2]; objects[0] = GameObject.CreatePrimitive(PrimitiveType.Plane); objects[0].name = "MyPlane"; objects[1] = GameObject.CreatePrimitive(PrimitiveType.Cube); objects[1].name = "MyCube";
// Get GlobalObjectId for all objects. var ids = new GlobalObjectId[2]; GlobalObjectId.GetGlobalObjectIdsSlow(objects, ids);
// Save and close the scene. EditorSceneManager.SaveScene(scene, testScenePath); EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
// Return the GlobalObjectId of all objects in the scene. var idsStringFormat = new string[2]; idsStringFormat[0] = ids[0].ToString(); idsStringFormat[1] = ids[1].ToString();
return idsStringFormat; }
// This method resolves the GlobalObjectIDs into object references after the scene is reloaded. static void ReloadSceneAndResolveObjects(string testScenePath, string[] objectIdsAsStrings) { // Convert string IDs into GlobalObjectId objects. var ids = new GlobalObjectId[2]; GlobalObjectId.TryParse(objectIdsAsStrings[0], out ids[0]); GlobalObjectId.TryParse(objectIdsAsStrings[1], out ids[1]);
// Load the scene before the resolving the IDs to objects references. EditorSceneManager.OpenScene(testScenePath);
var objects = new Object[2]; GlobalObjectId.GlobalObjectIdentifiersToObjectsSlow(ids, objects);
// Print the result. Debug.Log("Found " + objects[0].name + " and " + objects[1].name); } }
Additional resources: Object.GetInstanceID, AssetDatabase.AssetPathToGUID, AssetDatabase.TryGetGUIDAndLocalFileIdentifier.
assetGUID | The GUID for the asset that the referenced object belongs to. |
identifierType | The identifier type of the referenced object, represented as an integer. |
targetObjectId | The local file ID of the referenced object. |
targetPrefabId | The ID of the prefab instance that contains the referenced object. |
CompareTo | Compares this unique object identifier with another to determine their relative positions in the sort order. |
Equals | Checks if this unique object identifier and another are equal. |
ToString | Obtains the string representation of the unique object identifier. |
GetGlobalObjectIdSlow | Obtains the unique object identifiers based on an object reference. |
GetGlobalObjectIdsSlow | Creates an array of unique object identifiers based on an array of objects. |
GlobalObjectIdentifiersToInstanceIDsSlow | Creates an array of instance IDs based on an array of unique object identifiers. |
GlobalObjectIdentifiersToObjectsSlow | Creates an array of object references based on an array of unique object identifiers. |
GlobalObjectIdentifierToInstanceIDSlow | Obtains the instance ID of the object from its unique object identifier. |
GlobalObjectIdentifierToObjectSlow | Obtains a reference to an object from its unique object identifier. |
TryParse | Tries to parse the string representation of a GlobalObjectId into a GlobalObjectId struct. |
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.