GlobalObjectId

Description

Struct providing an API for stable, project-global object identifiers.

Provides a project-scoped object identifier, which can be serialized and resolved back to the original object at a later time. It supports referencing objects inside scenes and in other types of assets (Prefabs, ScriptableObjects, etc).

The ID is persistent and unique for a given Unity Object.

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.
{l} is the local file ID of the object. For objects inside a prefab instance this is the local file ID of the source object in the prefab.
{p} is the local file ID of the prefab instance of the object (or 0 when the object is not part of a prefab instance).

The default null ID is "GlobalObjectId_V1-0-00000000000000000000000000000000-0-0".

Caveats:
- The ID changes when the object is moved to a new scene, because the scene ID (assetGUID) is part of the GlobalObjectId.
- A GlobalObjectId referring to an object inside a scene can only be resolved back to an InstanceID or Object when that scene is already loaded.
- GlobalObjectIds cannot be requested for objects in the current scene until the scene has been saved at least once, otherwise the assetGUID value will be null.
- When converting multiple objects to or from GlobalObjectIds it is 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.

Additional resources: Object.GetInstanceID, AssetDatabase.AssetPathToGUID, AssetDatabase.TryGetGUIDAndLocalFileIdentifier

using UnityEngine;
using UnityEditor;
using UnityEditor.SceneManagement;

public class GlobalObjectIdExample
{
    [MenuItem("Example/GlobalObjectId")]
    static void MenuCallback()
    {
        const string testScenePath = "Assets/MyTestScene.unity";

        var stringIds = CreateSceneWithTwoObjects(testScenePath);

        // These string formatted ids could 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);

        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";

        var ids = new GlobalObjectId[2];
        GlobalObjectId.GetGlobalObjectIdsSlow(objects, ids);

        EditorSceneManager.SaveScene(scene, testScenePath);

        // Close the scene
        EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);

        var idsStringFormat = new string[2];
        idsStringFormat[0] = ids[0].ToString();
        idsStringFormat[1] = ids[1].ToString();

        return idsStringFormat;
    }

    static void ReloadSceneAndResolveObjects(string testScenePath, string[] objectIdsAsStrings)
    {
        var ids = new GlobalObjectId[2];
        GlobalObjectId.TryParse(objectIdsAsStrings[0], out ids[0]);
        GlobalObjectId.TryParse(objectIdsAsStrings[1], out ids[1]);

        // The scene must be loaded before the ids to objects it contains can be resolved
        EditorSceneManager.OpenScene(testScenePath);

        var objects = new Object[2];
        GlobalObjectId.GlobalObjectIdentifiersToObjectsSlow(ids, objects);

        // Found MyPlane and MyCube
        Debug.Log("Found " + objects[0].name + " and " + objects[1].name);
    }
}

Properties

Public Methods

Static Methods