Using LoadScene and LoadSceneAsync in Unity

May 25, 2023

Important Declarations

In this section, I enumerate the most relevant declarations related to loading a scene in Unity. The Unity API docs include additional declarations.

public static void LoadScene(
  int sceneBuildIndex, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

public static void LoadScene(
  string sceneName, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

public static AsyncOperation LoadSceneAsync(
  int sceneBuildIndex, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

public static AsyncOperation LoadSceneAsync(
  string sceneName, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

What you will learn

In this article, you will learn how to load a scene in Unity. By the end of this article, you will feel comfortable using the Unity SceneManager class to load scenes using the LoadScene and LoadSceneAsync methods.

What you need to know

Use LoadSceneAsync.
LoadScene is a synchronous operation and will cause freezes and other performance issues.
LoadSceneAsync is an AsyncOperation and will not freeze your game.

Unity SceneManager

LoadScene and LoadSceneAsync are static methods of the SceneManager class. You need to import the SceneManagement namespace to your class. This lets you access the SceneManager class methods.

To import the namespace, add using UnityEngine.SceneManagement to the top of your class, before any namespace declarations.

You now have access to the LoadScene and LoadSceneAsync methods.

Both of these methods are static methods of the SceneManager class. Therefore, you will always need to call them by first writing out the class reference, like this:

SceneManager.LoadScene(...)
SceneManager.LoadSceneAsync(...)

Identify your .Unity Scene

Options to Identify a .Unity Scene

Both LoadScene and LoadSceneAsync expect you to provide either an int sceneBuildIndex or a string sceneName as an input argument. This is a unique identifier for your scene.

What is a SceneBuildIndex?

The sceneBuildIndex is a unique integer assigned to each scene included in the build. The sceneBuildIndex depends on the order of the scenes in your build. This is defined in your scene build settings.

To open your build settings, click Toolbar -> File -> Build Settings.

The scene build index is the number to the right of each scene included in the build settings. This number will change if you move the scene up or down in the list.

What is a SceneName?

The sceneName is a unique file path associated with the scene file included in your build. The scene name can accept just the filename without extension (e.g., “MyScene.unity” -> “MyScene”). But, this does not work consistently if you have multiple scenes with the same name.

The sceneName is generally not case sensitive, but it is case sensitive in some cases.

If you use the sceneName, you should generally use a case sensitive filename for the scene, and you should always require scenes to have a unique filename.

These two simple steps will help you to avoid running into confusing edge cases.

Should I use the scene build index or scene name?

Both the scene build index and scene name are bad options. Both options have a few edge scenarios where it won’t work how you expect. And both are prone to manual error. Pick your poison.

I prefer using the filename. 🤷

How do I use LoadScene?

The full method declarations for LoadScene are written in the Declarations section at the top of this document. I’ll re-write the most relevant method declarations here.

public static void LoadScene(
  int sceneBuildIndex, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

public static void LoadScene(
  string sceneName, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

To load the scene, simply call this method with the identifier you chose from the previous section. In general, you don’t need to override the SceneManagement.LoadSceneMode, so don’t.

using UnityEngine;
using UnityEngine.SceneManagement;

public class LoadScene : MonoBehaviour
{
  [SerializeField]
  public string scenePath;
  
  void Update()
  {
    if (Input.GetKeyDown(KeyCode.Space))
    {
      SceneManager.LoadScene(scenePath);
    }
  }
}

As mentioned earlier, LoadScene is a synchronous operation. It will cause your game to stutter, freeze, or drop frames. In general, don’t use Load Scene. Instead, use LoadSceneAsync. Load Scene Async does not have these problems.

How do I use LoadSceneAsync?

The full method declarations for LoadSceneAsync are written in the Declarations section at the top of this document. Like I did for LoadScene, I’ll re-write those method declarations here for your convenience.

public static AsyncOperation LoadSceneAsync(
  int sceneBuildIndex, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

public static AsyncOperation LoadSceneAsync(
  string sceneName, 
  SceneManagement.LoadSceneMode mode = LoadSceneMode.Single
);

To load the scene, simply call this method with the identifier you chose from the previous section.

using UnityEngine;
using UnityEngine.SceneManagement;

public class LoadSceneAsync : MonoBehaviour
{
  [SerializeField]
  public string scenePath;
  
  void Update()
  {
    if (Input.GetKeyDown(KeyCode.Space))
    {
      SceneManager.LoadSceneAsync(scenePath);
    }
  }
}

LoadSceneAsync is an asynchronous operation, so the new scene may not load in right away. LoadSceneAsync returns an AsyncOperation, which has a progress property. You can use the progress property to create a nifty loading screen. We will do that in a separate tutorial.

Conclusion

Thanks for reading! As promised, you have learned how to load a scene in Unity. I hope that you now feel comfortable using Unity’s SceneManager.LoadScene and SceneManager.LoadSceneAsync.

If you have any further questions on scene loading in Unity, feel free to join my game dev Discord.