LoadableSceneId

Description

Stable serialized identifier for a Scene asset so it can be packed into content directory builds and loaded asynchronously at runtime.

This type can be used for a field on a ScriptableObject or MonoBehaviour to hold a "pointer" to a scene. When an object with a LoadableSceneId field is included in a ContentDirectory build, the referenced scene is also automatically included in the build.

When authoring content in the Editor, use LoadableSceneIdEditorUtility to create LoadableSceneId objects and assign them to fields on ScriptableObject-derived classes.

A LoadableSceneId is only supported in content built with BuildPipeline.BuildContentDirectory. If a LoadableSceneId is found in serialized data during a Player or AssetBundle build, the reference is set to null in the build output and an error is logged. Suppress this error with BuildOptions.SuppressLoadableErrors for Player builds or BuildAssetBundleOptions.SuppressLoadableErrors for AssetBundle builds.

When a scripting object that has LoadableSceneId fields loads, it does not automatically load the referenced scenes. Instead, scripts can use SceneManager.LoadSceneAsync to load the referenced scene when needed. Similarly, scripts can use SceneManager APIs to unload scenes when no longer needed.

In the Player, SceneManager.LoadSceneAsync loads the scene from built content. In Play mode it loads either the built scene or the live project scene, depending on where the LoadableSceneId came from. A LoadableSceneId reached from built content, for example through a root asset, loads the built scene, while one created with LoadableSceneIdEditorUtility loads the live project scene.

using System.Threading.Tasks;
using Unity.Loading;
using UnityEngine;
using UnityEngine.SceneManagement;

namespace BuildDocExamples
{
    public class LoadableSceneId_Example : MonoBehaviour
    {
        // Example ScriptableObject with a LoadableSceneId field
        public class LevelData : ScriptableObject
        {
            public LoadableSceneId sceneReference;
        }

        async Task LoadLevel(LevelData levelData)
        {
            // Assuming nextLevel is a LoadableSceneId serialized on your ScriptableObject or MonoBehaviour:
            if (levelData.sceneReference.IsValid)
            {
                var loadOp = SceneManager.LoadSceneAsync(levelData.sceneReference, new LoadSceneParameters(LoadSceneMode.Single));
                while (!loadOp.isDone)
                    await Awaitable.NextFrameAsync();
            }
        }
    }
}

Properties