Load a scene

Use the Addressables.LoadSceneAsync method to load an Addressable scene asset by address or other Addressable key object.

Addressables.LoadSceneAsync uses the Unity Engine SceneManager.LoadSceneAsync method internally. APIs that affect the behavior of SceneManager.LoadSceneAsync also affect Addressables.LoadSceneAsync in the same way, such as Application.backgroundLoadingPriority.

The remaining parameters of the Addressables.LoadSceneAsync method correspond to those used with the SceneManager.LoadSceneAsync method:

• loadMode: Whether to add the loaded scene into the current scene, or to unload and replace the current scene.
• loadSceneParameters: Includes loadMode and localPhysicsMode. This is used when loading the scene to specify whether to create a 2D or 3D physics scene.
• activateOnLoad: Whether to activate the scene as soon as it finishes loading or to wait until you call the SceneInstance object's ActivateAsync method. Corresponds to the AsyncOperation.allowSceneActivation option. Defaults to true.
• priority: The priority of the AsyncOperation used to load the Scene. Corresponds to the AsyncOperation.priority option. Defaults to 100.

Warning

Setting the activateOnLoad parameter to false blocks the AsyncOperation queue, including the loading of any other Addressable assets, until you activate the scene. To activate the scene, call the ActivateAsync method of the SceneInstance returned by LoadSceneAsync. Refer to AsyncOperation.allowSceneActivation for additional information.

The following example loads a scene additively. The component that loads the scene stores the operation handle and uses it to unload and release the scene when the parent GameObject is destroyed.

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.ResourceManagement.ResourceProviders;
using UnityEngine.SceneManagement;

internal class LoadSceneByAddress : MonoBehaviour
{
    public string key; // address string
    private AsyncOperationHandle<SceneInstance> loadHandle;

    void Start()
    {
        loadHandle = Addressables.LoadSceneAsync(key, LoadSceneMode.Additive);
    }

    void OnDestroy()
    {
        Addressables.UnloadSceneAsync(loadHandle);
    }
}

Refer to the Scene loading project in the Addressables samples repository for additional examples.

If you load a Scene with LoadSceneMode.Single, the Unity runtime unloads the current Scene and calls Resources.UnloadUnusedAssets. Refer to Releasing Addressable assets for more information.

Note

In the Editor, you can always load scenes in the current project, even when they're packaged in a remote bundle that's not available and you set the Play Mode Script to Use Existing Build. The Editor loads the scene using the Asset Database.

Use Addressables in a scene

If a scene is Addressable, you can use Addressable assets in the scene just like any other assets. You can place prefabs and other assets in the scene, and assign assets to component properties. If you use an asset that isn't Addressable, that asset becomes an implicit dependency of the scene and the build system packs it in the same AssetBundle as the scene when you make a content build. Addressable assets are packed into their own AssetBundles according to the group they're in.

Note

Implicit dependencies used in more than one place can be duplicated in multiple AssetBundles and in the built-in scene data. Use the Build Layout Report to identify and resolve unwanted asset duplication resulting from your project content organization.

If a scene isn't Addressable, then any Addressable assets you add directly to the scene hierarchy become implicit dependencies and Unity includes copies of those assets in the built-in scene data even if they also exist in an Addressable group. The same is true for any assets, such as materials assigned to a component on a GameObject in the scene.

In custom component classes, you can use AssetReference fields to allow the assignment of Addressable assets in non-Addressable scenes. Otherwise, you can use addresses and labels to load assets at runtime from a script. You must load an AssetReference in code regardless of if the scene is Addressable.