Unity Scene Management

Unity Scene Management

Retrieval Sources

28 rows, all verified against /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/{Manual,ScriptReference} before writing.

Key Guidelines

Sync vs Async Loading

SceneManager.LoadScene (ScriptReference/SceneManagement.SceneManager.LoadScene.html) loads a scene on the main thread and blocks until it's fully loaded — the calling frame stalls for the entire duration, which shows up as a hitch or freeze for anything beyond a tiny scene. SceneManager.LoadSceneAsync (ScriptReference/SceneManagement.SceneManager.LoadSceneAsync.html) starts the same work but returns immediately with an AsyncOperation handle, spreading the load across multiple frames so the game keeps rendering and responding. Both come in three overload shapes: by scene name (string), by build index (int), and by either of those plus a LoadSceneMode or a full LoadSceneParameters struct. Prefer LoadSceneAsync for anything triggered during gameplay (level transitions, streaming in a new zone); reserve LoadScene for cases where a hard stall is acceptable or even desirable, such as an initial splash-to-menu transition where nothing else is happening on screen anyway. In Unity 6, Awaitable.FromAsyncOperation (ScriptReference/Awaitable.FromAsyncOperation.html) lets an async Awaitable method await a scene load directly instead of polling isDone in Update:

using UnityEngine;
using UnityEngine.SceneManagement;

public class SceneLoader : MonoBehaviour
{
    public async Awaitable LoadLevelAsync(string sceneName)
    {
        AsyncOperation op = SceneManager.LoadSceneAsync(sceneName, LoadSceneMode.Single);
        await op; // Awaitable.FromAsyncOperation under the hood
        Debug.Log($"{sceneName} finished loading and is now active.");
    }
}

Single vs Additive Load Mode

LoadSceneMode (ScriptReference/SceneManagement.LoadSceneMode.html) has two values. Single (the default when no mode is specified) unloads every currently loaded scene before loading the new one — this is the classic "go to the next level" behavior and is what happens if you call LoadScene(name) with no mode argument. Additive loads the new scene on top of whatever is already loaded, without touching existing scenes. Use Additive for: streaming an open world in chunks around the player, layering a persistent UI/HUD or audio-manager scene over swappable gameplay scenes, loading a separate lighting/environment scene alongside a separate gameplay-logic scene, or cooperative split-responsibility scenes edited by different team members (see Manual/MultiSceneEditing.html). LoadSceneParameters (ScriptReference/SceneManagement.LoadSceneParameters.html) bundles loadSceneMode together with localPhysicsMode (see Manual/physics-multi-scene.html) for the overloads that accept a single struct instead of positional arguments — set localPhysicsMode to Physics2D/Physics3D when a scene needs its own isolated physics simulation independent of other additively-loaded scenes.

using UnityEngine;
using UnityEngine.SceneManagement;

// Boot flow: load a persistent UI/manager scene, then the first level additively on top.
public class BootLoader : MonoBehaviour
{
    void Start()
    {
        SceneManager.LoadScene("PersistentUI", LoadSceneMode.Single); // clears everything else
        SceneManager.LoadSceneAsync("Level01", LoadSceneMode.Additive); // layers gameplay on top
    }
}

Multi-Scene Workflows

Multiple scenes can be open (in-Editor) or loaded (at runtime) simultaneously — see Manual/MultiSceneEditing.html for the concept, Manual/setupmultiplescenes.html for the Editor workflow, and Manual/scriptmultiplescenes.html for the scripting equivalent. SceneManager.GetAllScenes() and SceneManager.GetSceneAt(int) enumerate every currently loaded scene; sceneCount (ScriptReference/SceneManagement.SceneManager-sceneCount.html) reports how many are loaded right now, loadedSceneCount reports how many have finished loading (relevant while an additive load is still in flight), and sceneCountInBuildSettings reports the total registered in Build Settings regardless of load state. Exactly one loaded scene is the "active" scene at any time — SceneManager.GetActiveScene()/SetActiveScene(Scene) control it, and it determines where newly instantiated GameObjects without an explicit target scene land, which scene's Lighting settings apply, and which scene's static batching/navmesh data is treated as primary. SceneManager.MoveGameObjectToScene reparents an object into a different loaded scene without destroying/recreating it, and SceneManager.CreateScene/MergeScenes create an empty runtime-only scene and fold one scene's contents into another, respectively — useful for organizing dynamically spawned objects (e.g. pooled bullets) into their own scene so they can be bulk-unloaded later.

using UnityEngine;
using UnityEngine.SceneManagement;

public class ZoneManager : MonoBehaviour
{
    // After loading a new zone additively, make it the active scene so
    // newly spawned enemies/pickups and its Lighting settings take effect.
    public void OnZoneLoaded(Scene loadedZone)
    {
        SceneManager.SetActiveScene(loadedZone);

        foreach (Scene scene in GetAllLoadedZones())
        {
            Debug.Log($"{scene.name}: loaded={scene.isLoaded}, buildIndex={scene.buildIndex}");
        }
    }

    System.Collections.Generic.IEnumerable<Scene> GetAllLoadedZones()
    {
        for (int i = 0; i < SceneManager.sceneCount; i++)
            yield return SceneManager.GetSceneAt(i);
    }
}

Persistence Across Scenes (DontDestroyOnLoad)

Object.DontDestroyOnLoad (ScriptReference/Object.DontDestroyOnLoad.html) marks a GameObject's entire hierarchy so it survives a Single-mode scene load, which would otherwise destroy every object in the outgoing scene. This is required for anything that must persist across level transitions: an audio manager, a game-state/save-data singleton, a network connection manager, or a persistent input-handling object. It has no effect on Additive loads or unloads — those never destroy objects outside the scene being unloaded, so DontDestroyOnLoad is specifically insurance against a future Single load. Objects marked this way are moved into a special hidden scene (visible in the Hierarchy as DontDestroyOnLoad in the Editor) that never gets unloaded; guard against calling DontDestroyOnLoad on the same singleton twice (e.g. if its home scene is re-loaded additively) by checking for an existing instance first.

using UnityEngine;

public class GameManager : MonoBehaviour
{
    public static GameManager Instance { get; private set; }

    void Awake()
    {
        if (Instance != null && Instance != this)
        {
            Destroy(gameObject); // a duplicate was created by re-loading this scene
            return;
        }
        Instance = this;
        DontDestroyOnLoad(gameObject);
    }
}

Scene Events

SceneManager.sceneLoaded and SceneManager.sceneUnloaded (ScriptReference/SceneManagement.SceneManager-sceneLoaded.html, ScriptReference/SceneManagement.SceneManager-sceneUnloaded.html) fire after a load/unload completes, with the affected Scene (and, for sceneLoaded, the LoadSceneMode used) passed to the handler — this is the correct place to run logic that depends on the new scene's objects existing (spawning the player, wiring up references, starting AI), rather than assuming ordering relative to Start()/Awake() on scripts in the loading scene. SceneManager.activeSceneChanged (ScriptReference/SceneManagement.SceneManager-activeSceneChanged.html) fires when SetActiveScene changes which scene is active, passing the previous and new Scene. Always unsubscribe in OnDestroy/OnDisable to avoid a dangling delegate reference keeping a destroyed listener's closure alive or throwing on a stale scene reference.

using UnityEngine;
using UnityEngine.SceneManagement;

public class SceneEventLogger : MonoBehaviour
{
    void OnEnable()
    {
        SceneManager.sceneLoaded += HandleSceneLoaded;
        SceneManager.sceneUnloaded += HandleSceneUnloaded;
        SceneManager.activeSceneChanged += HandleActiveSceneChanged;
    }

    void OnDisable()
    {
        SceneManager.sceneLoaded -= HandleSceneLoaded;
        SceneManager.sceneUnloaded -= HandleSceneUnloaded;
        SceneManager.activeSceneChanged -= HandleActiveSceneChanged;
    }

    void HandleSceneLoaded(Scene scene, LoadSceneMode mode) =>
        Debug.Log($"Loaded '{scene.name}' with mode {mode}");

    void HandleSceneUnloaded(Scene scene) =>
        Debug.Log($"Unloaded '{scene.name}'");

    void HandleActiveSceneChanged(Scene previous, Scene next) =>
        Debug.Log($"Active scene: {previous.name} -> {next.name}");
}

Memory Reclamation on Unload

SceneManager.UnloadSceneAsync (ScriptReference/SceneManagement.SceneManager.UnloadSceneAsync.html) destroys a scene's GameObjects and removes it from the loaded-scenes list, but it does not free the underlying assets (textures, meshes, materials, audio clips) those objects referenced — Unity keeps them cached in memory in case another loaded scene (or a fresh load of the same scene) needs them again. Call Resources.UnloadUnusedAssets() (ScriptReference/Resources.UnloadUnusedAssets.html) afterward to actually scan for and free assets with no remaining references; it also returns an AsyncOperation since the scan can be expensive on large projects. Resources.UnloadUnusedAssets only unloads assets that were loaded as part of a scene or via Resources.Load/AssetBundle — it does not garbage-collect managed C# objects, so pair it with System.GC.Collect() when profiling shows managed memory is also the culprit (use sparingly; forcing a full GC has its own frame-time cost). Do not call UnloadUnusedAssets every frame or on a timer — it's relatively expensive and should be triggered by actual scene-transition events.

using System.Collections;
using UnityEngine;
using UnityEngine.SceneManagement;

public IEnumerator UnloadZoneAndReclaim(string sceneName)
{
    AsyncOperation unload = SceneManager.UnloadSceneAsync(sceneName);
    yield return unload; // waits for GameObjects to be destroyed

    AsyncOperation cleanup = Resources.UnloadUnusedAssets();
    yield return cleanup; // waits for orphaned assets to be freed

    Debug.Log($"{sceneName} fully unloaded and its assets reclaimed.");
}

Common Mistakes

Quick Reference

Advanced Notes

Scene streaming for large open worlds. A common architecture for open-world or seamless-level games splits the world into a grid or graph of small additive scenes (streaming cells) plus one persistent scene holding the player, camera, and manager singletons (loaded Single once at boot, never touched again). At runtime, a streaming controller tracks the player's position, computes which cells should be loaded (typically the current cell plus a ring of neighbors), and diff's that against what's currently loaded: cells that just entered range are LoadSceneAsync'd additively, cells that just left range are UnloadSceneAsync'd and followed by a debounced Resources.UnloadUnusedAssets() call (batched, not called per-cell, since it's relatively expensive). Keep multiple loads in flight concurrently rather than sequentially awaiting each one — AsyncOperation.priority can hint the scheduler which of several concurrent loads should be favored when there's contention. Because occlusion-culling and lightmap data are baked per-scene-setup (Manual/occlusion-culling-scene-loading.html, Manual/bakemultiplescenes.html), open-world projects generally need to bake with the actual multi-scene streaming layout active rather than each cell scene in isolation, or bake lighting into a lightweight lower-fidelity fallback and rely on realtime GI/light probes for boundary seams. Pair scene streaming with texture mip-streaming (Manual/TextureStreaming.html) so large per-cell texture sets don't spike memory the instant a cell's scene finishes loading — texture streaming trims mip levels independently of scene load state, based on camera distance and screen coverage.

Loading-screen patterns. The standard approach: LoadSceneAsync the target scene with allowSceneActivation = false immediately after starting the operation, then drive a progress bar off AsyncOperation.progress (remember it caps at 0.9 while activation is withheld — treat progress >= 0.9f as "ready", not progress >= 1f). Once the loading-screen fade-out/transition animation is ready to play, set allowSceneActivation = true and wait for isDone (or the completed callback) before tearing down the loading UI. For a two-scene loading-screen setup (a dedicated LoadingScreen scene loaded Single first, which then kicks off the real target scene additively and unloads itself once the target is active), sequence it as: unload old gameplay scene(s) → load LoadingScreen (Single) → LoadSceneAsync(target, Additive) with activation withheld → drive progress bar → activate → SetActiveScene(target) → UnloadSceneAsync("LoadingScreen"). For loads composed of multiple parallel operations (e.g. streaming in several cells at once, or a scene plus an Addressables bundle), aggregate progress by averaging each operation's progress rather than showing only the slowest one, and gate the "ready" state on every operation's isDone being true.

using System.Collections;
using UnityEngine;
using UnityEngine.SceneManagement;

public class LoadingScreenController : MonoBehaviour
{
    public UnityEngine.UI.Slider progressBar;

    public IEnumerator TransitionTo(string targetScene)
    {
        AsyncOperation op = SceneManager.LoadSceneAsync(targetScene, LoadSceneMode.Additive);
        op.allowSceneActivation = false;

        while (op.progress < 0.9f)
        {
            progressBar.value = op.progress / 0.9f; // normalize 0..0.9 -> 0..1
            yield return null;
        }
        progressBar.value = 1f;

        // Play a fade-out, wait for input, etc., then release activation:
        yield return new WaitForSeconds(0.5f);
        op.allowSceneActivation = true;

        yield return op; // now completes for real

        Scene loaded = SceneManager.GetSceneByName(targetScene);
        SceneManager.SetActiveScene(loaded);
        yield return SceneManager.UnloadSceneAsync("LoadingScreen");
    }
}