These are instructions for using the SceneLoader autoload to load resources asynchronously. This is especially useful for large scenes, but can be used throughout a project. The plugin comes with an example loading screen as well.
By default, calling SceneLoader.load_scene(path_to_scene) will unload the current scene and replace it with a loading screen, until the next scene is fully loaded. At that point, the loading screen will be removed and replaced with the next scene.
It is intended to replace calls to get_tree().change_scene_to_file(path_to_scene) that open large scenes and may cause a stutter. It can also replace calls to get_tree().change_scene_to_packed(loaded_packed_scene), that may require large scenes to already be loaded into memory.
Calling SceneLoader.load_scene(path_to_scene, true) will load the scene in the background (hence the in_background argument being set to true).
There are a number of ways to then show the scene when it is ready, or even switch to foreground loading in case it is not.
A scene can be loaded as soon as it is ready, by listening for the scene_loaded signal from the SceneLoader.
An example of this is in level_loader.gd of Maaack's Game Template, which loads scenes in the background and displays a loading screen, but doesn't change the whole scene when the next one is ready. Instead, it loads the next level into a container.
Below is an example of reacting to SceneLoader signals to open the loaded scene in an optional container node, or switch to it entirely.
SceneLoader.load_scene(path_to_scene, true)
await SceneLoader.scene_loaded
if container:
# Has a container, so will open the loaded scene in it
var resource = SceneLoader.get_resource()
var instance = resource.instantiate()
container.add_child(instance)
else:
# Has no container, so will switch to the loaded scene
SceneLoader.change_scene_to_resource()
A scene could load the next scene based on a timer, or when the player indicates that they are ready.
An example is in opening.gd of Maaack's Game Template, which starts loading the main menu immediately, and switches to it when its animations finish. Player's input can speed them up the animations, so by the end, if the next scene is not ready, a loading screen can be shown instead.
Below is an example of starting the load of the next scene.
func _ready() -> void:
# Immediately starting to load the next scene in the background
SceneLoader.load_scene(path_to_scene, true)
Below is an example of reacting to the player's input to either show the next scene or a loading screen.
func _unhandled_input(event : InputEvent) -> void:
var status = SceneLoader.get_status()
if status != ResourceLoader.THREAD_LOAD_LOADED:
# Resource is not loaded, so show the loading screen
SceneLoader.change_scene_to_loading_screen()
else:
# Resource is loaded, so switch to the loaded scene
SceneLoader.change_scene_to_resource()