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.

Player and AssetBundle builds do not pull scenes referenced by LoadableSceneId into the build. Only the scenes listed in EditorBuildSettings.scenes are included. However, a LoadableSceneId field in any built content can be used to load the scene at runtime if it is available inside a registered ContentDirectory.

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. The loading capability is available in both Editor play mode and in the Player. Similarly, scripts can use SceneManager APIs to unload scenes when no longer needed.

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