Uninomicon

Documenting the dark corners of the Unity Engine.

User Tools

Site Tools


scenemanager

SceneManager

When does scene loading happen?

Scene loading and unloading happens at the start of the Update loop, within the EarlyUpdate.UpdatePreloading phase of the PlayerLoop, and once during the Initialization phase of the player, before the first Update loop.

Player Loop Phases:

  • Initialization (Scene Loading happens here)
  • Game Loop
    • Early Update
      • UpdatePreloading (Scene Loading happens here)
    • FixedUpdate
    • Update

The Scene Loading Queue

The scene loading queue is a pipeline, and only one AsyncOperation can progress at a time. Calling SceneManager.LoadSceneAsync or SceneManager.UnloadSceneAsync adds a new AsyncOperation onto the end of the queue.

During the UpdatePreloading phase, Unity will execute the next operation in the scene loading queue.

The scene loading pipeline only seems to execute a single operation, every other frame.[research needed] If you have 3 small scenes in the pipeline (Scene1, Scene2, Scene3), loading additively, the engine will load them at the following times:

  • Frame N+0: Scene1
  • Frame N+1: —
  • Frame N+2: Scene 2
  • Frame N+3: —
  • Frame N+4: Scene 3

Initialization

The Engine fully “flushes” the scene loading queue during initialization. This works differently than the way Unity loads scenes during the EarlyUpdate.

All AsyncOperations that are queued during initialization are fully loaded during initialization. For example, if SceneManager.LoadSceneAsync is called in the Awake of the very first scene1), the engine will load this new scene before finishing Initialization.

Scene unloads are probably flushed if they are in the pipeline, too.[research needed]

Build Pipeline

Scenes are built during standalone build in the following way:

  1. The active scenes are closed.
  2. Each Scene in the BuildSettings is opened. At this point prefabs are still prefab instances.
  3. EditorSceneManager.sceneOpened callback is called.
  4. Prefabs in the scene are flattened (turned into normal game objects).
  5. IProcessScene and PostProcessScene callbacks are called.
  6. The final scene file is saved into the standalone build file.
  7. Repeat for next scene.

Sample Scene Load (Editor)

Here is an example of a scene loading additively in the middle of a game, in the editor. Note that:

  • Prefabs.MergePrefabs (turning prefabs into gameobjects) happens before any other callback. (editor only)
  • Lightmapping is applied / loaded after Awake/OnEnable.
  • SceneManager.sceneLoaded happens after PostProcessScene.

Scattered Notes

  • During a scene load (ie. Awake) the loading scene has scene.isLoaded=false.
  • During a scene unload (ie. Destroy) the unloading scene has scene.isLoaded=false. 2)
  • ISerializationCallbackReceiver.OnAfterDeserialize is called before the async loading of heavy scene resources (e.g. textures) so can be used for running scene-specific thread-aware code early in the loading process.3)
  • When using LoadSceneMode.Additive, using the SceneManager.sceneLoaded callback and setting SceneManager.SetActiveScene(scene) within this callback results in Unity replacing the currently loaded occlusion culling data with the occlusion culling data from this newly loaded scene. This goes directly against what is documented, which states Unity will only use the culling data from the first loaded scene. This undocumented behavior has been tested in 2018.4-2020.3, and may or may not work in other versions of Unity.

API Notes:

SceneManager.sceneLoaded

  • Called after the loaded Scene Awakes.
1)
ie. called before the first Update
2)
You might expect during the unload phase that isLoaded=true, but this is not the case, even though all of the Scene objects are still perfectly loaded and accessible
3)
Unlike MonoBehaviour events which are called at the end.
scenemanager.txt · Last modified: 2022/01/30 19:55 by narry