Basic Usage

Loading scenes with this package implies that the scenes will always be loaded as Additive. That is simply because there is no advantage in loading scenes in the Single load scene mode when you expect to work with multiple scenes.

You will be using the MySceneManager static class to perform the scene operations.

Loading scenes

You can load scenes by using any of these references:

// Name
MySceneManager.LoadAsync("my-scene");
// Path (relative to the Assets folder)
MySceneManager.LoadAsync("Scenes/my-scene");
// Build Index
MySceneManager.LoadAsync(1);
// Address
MySceneManager.LoadAsync(SceneRef.Address("my-scene-address"));
// Asset Reference
MySceneManager.LoadAsync(mySceneAssetReference);

info

There is no separate addressable API. A plain string is looked up in your build settings first, then in Addressables — so LoadAsync("my-scene") finds your scene wherever it lives.

SceneRef.Address(...) is the override, for when a name exists in both places or when you want to skip the lookup. See Scene Ref.

Additionally, you can also pass an array of scenes:

// Array of build indexes
MySceneManager.LoadAsync(new int[] { 1, 2, 3 });
// Mixed kinds are fine too
MySceneManager.LoadAsync(new SceneRef[] { "scene-a", 2, SceneRef.Address("scene-c") });

The loaded scene can be marked to be set as the active scene, through SceneParameters:

// Loads a scene and sets it as the active scene
MySceneManager.LoadAsync(new SceneParameters("my-scene", true));

// Loads a list of scenes and sets the scene at index 1 as the active scene
MySceneManager.LoadAsync(new SceneParameters(new SceneRef[] { 1, 2, 3 }, 1));

Every operation returns a handle straight away, and progress comes from that:

SceneOperation op = MySceneManager.LoadAsync("my-scene");
op.Progressed += value => progressBar.value = value;

Unloading scenes

You can unload scenes by using any reference, including the scene itself.

// Name
MySceneManager.UnloadAsync("my-scene");
// Path (relative to the Assets folder)
MySceneManager.UnloadAsync("Scenes/my-scene");
// Build Index
MySceneManager.UnloadAsync(1);
// Address
MySceneManager.UnloadAsync(SceneRef.Address("my-scene-address"));
// Asset Reference
MySceneManager.UnloadAsync(mySceneAssetReference);
// Scene
MySceneManager.UnloadAsync(MySceneManager.GetActiveScene());

You can also unload multiple scenes:

// Array of build indexes
MySceneManager.UnloadAsync(new int[] { 1, 2, 3 });

Scene Transitions

To perform scene transitions, first you pass the target scene(s) and then the loading screen (optional). You can use the same references from the LoadAsync method.

// Name
MySceneManager.TransitionAsync("my-target-scene", "my-loading-scene");

// Array of AssetReference
MySceneManager.TransitionAsync(new AssetReference[] { scene1, scene2, scene3 });

info

The target scenes and the loading screen are resolved independently, so they do not have to be the same kind of reference — loading a scene by build index while showing a loading screen named by string is fine.

The loading screen does not even have to be a scene — see Loading Screens.

Check the Loading Scene Examples Sample to try different loading screens when performing Scene Transitions.

Scene Reloading

You can reload the active scene using the ReloadActiveSceneAsync method. A scene reload is also a scene transition internally. It will load the active scene via the same reference it was loaded initially.

Just like with Scene Transitions, you can also pass a loading screen.

MySceneManager.ReloadActiveSceneAsync("my-loading-scene");

// No loading screen:
MySceneManager.ReloadActiveSceneAsync();

Async Programming

Every operation returns a SceneOperation immediately — a handle on the work, which you can await directly:

await MySceneManager.TransitionAsync("my-target-scene", "my-loading-scene");
// Do something after the transition

For coroutines, use ToCoroutine():

yield return MySceneManager.TransitionAsync("my-target-scene", "my-loading-scene").ToCoroutine();
// Do something after the transition

And if a third-party API needs a Task, AsTask() bridges to one:

Task<SceneResult> task = MySceneManager.LoadAsync("my-scene").AsTask();

Cancelling

You cancel through the handle, rather than by passing a token in:

SceneOperation op = MySceneManager.LoadAsync("my-scene");
op.Cancel();

// Or bridge a token you already have:
MySceneManager.LoadAsync("my-scene").CancelWith(destroyCancellationToken);

atenção

Cancelling stops this operation's reporting, its remaining phases and its waiters. The underlying Unity load still runs to completion: a scene the engine has started loading cannot be aborted.