Using LoadScene and LoadSceneAsync in Unity

by Michael Sacco Published May 25, 2023
The cover for Using LoadScene and LoadSceneAsync in Unity

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.

Recommended Reading and Next Steps

Now that you are comfortable using LoadScene and LoadSceneAsync to load scenes in your Unity game, you should review Unity’s documentation on these methods to better familiarize yourself with them. You can find Unity’s API docs for the SceneManager class here.

You should also familiarize yourself with Additive vs. Single loading of Scene assets. You can use Additive scene loading to dynamically adjust your scene on-the-fly without unloading an existing scene. You can learn more about Additive loading and Single loading (collectively, the LoadSceneMode on Unity’s API docs here.

Apart from that, try creating your own scenes, setting up a scene loading scripts in each one, then bouncing back and forth between them to familiarize yourself with using the scene loading methods.

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.

Free download: Indie Game Marketing Checklist

Download now

Category

programming

Don't forget to share this post!

Popular assets for Unity

See all assets ->
    Cutting-edge volumetric fog and volumetric lighting with support for transparent materials.
    Volumetric clouds, day night cycles, dynamic skies, global lighting, weather effects, and planets and moons.
    A lightweight procedural skybox ideal for semi-stylized projects.
    Image-based Outlines for 2D and 3D games with variable line weight, color, and displacement options.
    Drag-and-drop ready-to-use ambient, impact, and spell particle effects.
    Per-pixel gaussian blur on your entire screen, part of the UI, or in-scene objects.

Free Indie Game Marketing Checklist

Learn how to make your game successful with this handy checklist.

Download for free