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.

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

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

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

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

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 [.c]LoadScene[.c] and [.c]LoadSceneAsync[.c] methods.

In general, you should prefer using [.c]LoadSceneAsync[.c]. [.c]LoadScene[.c] is a synchronous operation and will cause freezes and other performance issues. On the other hand, LoadSceneAsync is an AsyncOperation and will not freeze your game.

Unity SceneManager

[.c]LoadScene[.c] and [.c]LoadSceneAsync[.c] are static methods of the [.c]SceneManager[.c] class. You need to import the [.c]SceneManagement[.c] namespace to your class to access the [.c]SceneManager[.c] class methods.

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

You now have access to the [.c]LoadScene[.c] and [.c]LoadSceneAsync[.c] methods.

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

[.c]SceneManager.LoadScene(...)[.c]

[.c]SceneManager.LoadSceneAsync(...)[.c]

Identify your .Unity Scene

Options to Identify a .Unity Scene

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

SceneBuildIndex

The [.c]sceneBuildIndex[.c] is a unique integer assigned to each scene included in the build. The [.c]sceneBuildIndex[.c] depends on the order of the scenes in your build as defined in your scene build settings. To open your build settings, click Toolbar -> File -> Build Settings. The [.c]sceneBuildIndex[.c] 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. 

‍

SceneName

The [.c]sceneName[.c] is a unique file path associated with the scene file included in your build. [.c]sceneName[.c] 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 [.c]sceneName[.c] is generally not case sensitive, but it is case sensitive in some cases. If you use the [.c]sceneName[.c], 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.

Conclusion

Both options - [.c]sceneBuildIndex[.c] vs. [.c]sceneName[.c] - are bad and prone to manual issues. Pick your poison. I prefer using the filename. 🤷

LoadScene

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

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

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

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 [.c]SceneManagement.LoadSceneMode[.c], so don’t.

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

LoadSceneAsync

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

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

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

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

[.c]LoadSceneAsync[.c] is an asynchronous operation, so the new scene may not load in right away. [.c]LoadSceneAsync[.c] returns an AsyncOperation, which has a [.c]progress[.c] property. You can use the [.c]progress[.c] 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 [.c]LoadScene[.c] and [.c]LoadSceneAsync[.c] 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 [.c]LoadSceneMode[.c] 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 [.c]SceneManager.LoadScene[.c] and [.c]SceneManager.LoadSceneAsync[.c].

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