Load a scene

To load a scene, you can either use subscenes, or the SceneSystem API.

If you use a subscene, when the AutoLoadScene field is set to true, Unity streams the referenced scene in when the SubScene component is enabled.

To directly control streaming without a SubScene component, use the SceneSystem high level API. The static method to load a scene asynchronously is SceneSystem.LoadSceneAsync. By default, a call to SceneSystem.LoadSceneAsync loads the meta entities and all the contents for the sections. Calls to this method should happen inside the OnUpdate method of a system.

All versions of this method need to receive a parameter that can uniquely identify the scene that you want to load. You can use the following to identify a scene:

• An EntitySceneReference.
• A Hash128 GUID.
• A scene meta Entity.

Note

The build process only detects authoring scenes that are referenced by EntitySceneReference and SubScene MonoBehaviours. The build process doesn't detect scenes referenced by GUIDs, and their entity scene files will be missing from builds. For this reason, you should avoid using GUIDs to identify scenes.

In Play mode, all scenes are always available independently from the method used to reference the scenes. If the corresponding entity scene file is missing or outdated, baking is triggered during loading.

SceneSystem.LoadSceneAsync returns the scene meta Entity for the loading scene when a GUID or an EntitySceneReference is used as a parameter. You can use this scene meta Entity for subsequent calls to refer to the loading scene, for example, to unload the content of a scene and to reload it after.

Use EntitySceneReference to load a scene

Using EntitySceneReference is the recommended way to keep a reference to scenes during baking and to load them at runtime. The following example shows how to store a reference to a scene during baking:

// Runtime component, SceneSystem uses EntitySceneReference to identify scenes.
public struct SceneLoader : IComponentData
{
    public EntitySceneReference SceneReference;
}

#if UNITY_EDITOR
// Authoring component, a SceneAsset can only be used in the Editor
public class SceneLoaderAuthoring : MonoBehaviour
{
    public UnityEditor.SceneAsset Scene;

    class Baker : Baker<SceneLoaderAuthoring>
    {
        public override void Bake(SceneLoaderAuthoring authoring)
        {
            var reference = new EntitySceneReference(authoring.Scene);
            var entity = GetEntity(TransformUsageFlags.None);
            AddComponent(entity, new SceneLoader
            {
                SceneReference = reference
            });
        }
    }
}
#endif

This example shows how to use the stored reference in a system to load the scene:

[RequireMatchingQueriesForUpdate]
public partial class SceneLoaderSystem : SystemBase
{
    private EntityQuery newRequests;

    protected override void OnCreate()
    {
        newRequests = GetEntityQuery(typeof(SceneLoader));
    }

    protected override void OnUpdate()
    {
        var requests = newRequests.ToComponentDataArray<SceneLoader>(Allocator.Temp);

        // Can't use a foreach with a query as SceneSystem.LoadSceneAsync does structural changes
        for (int i = 0; i < requests.Length; i += 1)
        {
            SceneSystem.LoadSceneAsync(World.Unmanaged, requests[i].SceneReference);
        }

        requests.Dispose();
        EntityManager.DestroyEntity(newRequests);
    }
}

During the call to SceneSystem.LoadSceneAsync, only the scene entity is created. Unity uses this entity to control the rest of the loading process internally.

The scene header, the section entities, and their content aren't loaded during this call and they are ready a few frames later.

SceneSystem.LoadSceneAsync can perform structural changes. These structural changes prevent us from calling this function inside a foreach with an query.

Load parameters

The LoadParameters struct is optional, and by default SceneSystem.LoadSceneAsync loads the meta entities and all the content for the sections.

The SceneLoadFlags enum controls the loading, and has the following fields:

• DisableAutoLoad: Unity creates the scene and section meta entities, but doesn't load the content for the sections. When the scene loading is finished, you can access the ResolvedSectionEntity buffer to load the content for individual sections. The AutoLoad property in LoadParameters is a helper to set up DisableAutoLoad.
• BlockOnStreamIn: Unity performs the loading of the scene synchronously. The call to SceneSystem.LoadSceneAsync only returns when the scene is fully loaded.
• NewInstance: Creates a new copy of the scene in the world. This flag is used for scene instancing.

Unload scenes

To unload a scene, use SceneSystem.UnloadScene:

var unloadParameters = SceneSystem.UnloadParameters.DestroyMetaEntities;
SceneSystem.UnloadScene(World.Unmanaged, sceneEntity, unloadParameters);

You can call SceneSystem.UnloadScene with a scene's GUID or an EntitySceneReference instead of the scene meta entity, but this has the following disadvantages:

• The method has to search for the meta entity that represents the scene that matches the GUID, which might affect performance.
• If multiple instances of the same scene are loaded, then unloading by GUID only unloads one instance.

By default, SceneSystem.UnloadScene only unloads the content for the sections, but it keeps the meta entities for the scene and the sections. This is useful if the scene is going to be loaded again later, because having these meta entities ready speeds up the loading of the scene.

To unload the content and delete the meta entities, call SceneSystem.UnloadScene with UnloadParameters.DestroyMetaEntities.

SceneSystem.UnloadScene can perform structural changes.