Unity - Scripting API: SceneManager

class in UnityEngine.SceneManagement

Success!

Thank you for helping us improve the quality of Unity Documentation. Although we cannot accept all submissions, we do read each suggested change from our users and will make updates where applicable.

Submission failed

For some reason your suggested change could not be submitted. Please <a>try again</a> in a few minutes. And thank you for taking the time to help us improve the quality of Unity Documentation.

Your name Your email Suggestion*

Cancel

Description

Manage scenes in the Player and in Play mode in the Editor.

You can use the SceneManager to manage and manipulate scenes in the Player.

Scene creation, loading and unloading

To create scenes dynamically at runtime, use SceneManager.CreateScene.
To load scenes from built content, use SceneManager.LoadSceneAsync or SceneManager.LoadScene.
Scenes cannot be saved at runtime.
You can load multiple scenes simultaneously. To add more scenes to the currently open ones, use the LoadSceneMode.Additive option when calling SceneManager.LoadSceneAsync or SceneManager.LoadScene.
You can load the same scene multiple times in both the Player and in Play mode in the Editor. In Edit mode in the Editor, SceneManager cannot be used and a scene can only be loaded once (using EditorSceneManager).
To unload a scene explicitly, use SceneManager.UnloadSceneAsync. All open scenes can be unloaded implicitly by loading another scene with LoadSceneMode.Single.

Scripts can register on these events and then be notified when there are changes in the state of the SceneManager.

The scene list

The Player contains a BuildSettings object which records the list of scenes that are available to load. The contents of this list is exposed by SceneManager.sceneCountInBuildSettings and SceneUtility.GetScenePathByBuildIndex.

The contents of this list is determined when the Player is built:

By default, all the enabled scenes in the EditorBuildSettings.scenes array are included. You can view and edit this list from the active profile in the Build Profiles window.
When building via scripts with BuildPipeline.BuildPlayer, specify scenes using BuildPlayerOptions.scenes.

The scene order is crucial for several reasons:

The first enabled scene in the Scene list (with a build index of 0) loads automatically when the Player starts.
Earlier listed Scenes load faster due to optimized assignment of their dependent content to fewer sharedAsset files.
SceneManager.LoadSceneAsync and SceneManager.LoadScene supports loading scenes by index, determined by the order in EditorBuildSettings.scenes or BuildPlayerOptions.scenes after any disabled scenes are removed.

AssetBundles and Scenes

Additional scenes can be included in AssetBundles. When an AssetBundle that contains scenes is loaded, its scenes become available to the SceneManager and can be loaded by path using SceneManager.LoadSceneAsync or SceneManager.LoadScene.
Scenes from AssetBundles have a Scene.buildIndex of -1.
When loading scenes by path, a match from loaded AssetBundle takes priority over scenes in the Player build.

Scene management in the Editor

Use EditorSceneManager instead of SceneManager for scene authoring and manipulation in the Editor.
The SceneManager API should only be used in Play mode. In Edit mode calls to unsupported methods such as SceneManager.LoadSceneAsync will throw an invalid operation exception.
In Play mode, only scenes listed in EditorBuildSettings are available to load, along with scenes from loaded AssetBundles, simulating Player behavior.

Notes

Loading Scenes by index can be fragile due to potential reordering; the recommended best practice is to load scenes by path for better clarity.
Loading scenes by filename (without a full path) can cause issues if multiple scenes share the same name; full path specification removes that ambiguity.

Additional resources: EditorSceneManager, SceneUtility, Scene.buildIndex, EditorBuildSettingsScene.enabled, AssetBundle.GetAllScenePaths.

Static Methods

Method	Description
CreateScene	Create an empty new Scene at runtime with the given name.
GetActiveScene	Gets the currently active Scene.
GetSceneAt	Get the Scene at index in the SceneManager's list of loaded Scenes.
GetSceneByBuildIndex	Get a Scene struct from a build index.
GetSceneByName	Searches through the Scenes loaded for a Scene with the given name.
GetSceneByPath	Searches all Scenes loaded for a Scene that has the given asset path.
LoadScene	Loads the Scene by its name or index in Build Settings.
LoadSceneAsync	Loads the Scene asynchronously in the background.
MergeScenes	This will merge the source Scene into the destinationScene.
MoveGameObjectsToScene	Move multiple GameObjects, represented by a NativeArray of instance IDs, from their current Scene to a new Scene.
MoveGameObjectToScene	Move a GameObject from its current Scene to a new Scene.
SetActiveScene	Set the Scene to be active.
UnloadSceneAsync	Destroys all GameObjects associated with the given Scene and removes the Scene from the SceneManager.

Events

Event	Description
activeSceneChanged	Subscribe to this event to get notified when the active Scene has changed.
sceneLoaded	Assign a custom callback to this event to get notifications when a Scene has loaded.
sceneUnloaded	Add a delegate to this to get notifications when a Scene has unloaded.