Skip to content

Home

Jump to bottom
Manolo Cantón edited this page Jul 5, 2024 · 51 revisions

Welcome to the godot-scene-manager wiki!

Introduction

This repository stores a Godot plugin which adds extra options to adds extra options to the limited SceneTree methods for changing scenes. The main feature is to set properties for the next scene from the previous scene. To be able to use this functionality, there is the SceneManager autoload with some methods.

SceneManager.change_scene_to_file("my_scene.tscn", {
    my_next_scene_property = "a value",
})

The previous code loads the scene and sets the property my_next_scene_property with the value "a value". In the same way, you can offer a PackedScene with the following alternative code:

SceneManager.change_scene_to_packed(my_packed_scene, {
    my_next_scene_property = "a value",
})

If you need to reload a scene, you can use:

SceneManager.reload_current_scene({
    my_current_scene_property = "a value",
})

Note: I'll try to keep method names like SceneTree methods. If the names change in future Godot releases, I also change them.

Background Loading

I saw the possibility of loading a PackedScene in the background using ResourceLoader.load_threaded_request, so I wanted to take advantage of this in case you work with very large scenes (at least I haven't gotten to something like that yet). But I've seen people wanting this, so I've tried to add it, as well as putting in a custom loading screen.

That said, it only makes sense for the method SceneManager.change_scene_to_file, which has the optional argument called min_duration. It indicates the minimum loading scene time. I think this is reasonable because it makes no sense to see the loading screen as a flash. Example:

SceneManager.change_scene_to_file("my_scene.tscn", {}, 0.5, {
    loading_screen_property = "a value"
})

In this case, the loading screen has a minimum time of 0.5 seconds. If the PackedScene takes longer, it will last longer, but if it is loaded earlier, it will wait until this time has elapsed.

You can also observe a fourth argument. It works the same as the second properties argument but this is passed to the loading screen.

Appending resources

You can load extra resources to pass to next scene properties. You must use SceneManagerResourceRef which returns the SceneManager.append_resource method in your properties dictionary values. All these classes are parsed with the resources that are loaded in the background. It supports this in Array and Dictionary values too, but it doesn't work with object properties. Since it checks all arrays and dictionaries (supporting cyclic references which are checked once) it is advisable not to include large amounts of data in the properties parameter.

SceneManager.change_scene_to_file("my_scene.tscn", {
    characters = [
        SceneManager.append_resource("my_character1.tres"),
        SceneManager.append_resource("my_character2.tres"),
    ],
}, 1.0)

When the next scene is in the scene tree, parse ref with the resource and set the characters property. You can use SceneManager.reset_options() to remove options which includes to remove appended resources.

Custom loading screens

You can extend LoadingScreen to create your amazing loading screen. You must override methods to change the behavior:

  • _get_range_object Returns a object with value property, which indicates the loading progress. value must be a float and takes values between 0.0 and 100.0.
  • _get_tween_duration Time it takes to reach the new value.
  • handle_load_error This is called when scene cannot be loaded. You can use it to show an error on loading screen.
extends LoadingScreen

func _get_range_object() -> Object:
    return $MyRangeNode

func _get_tween_duration() -> float:
    return 0.1

func handle_load_error() -> void:
    $MyErrorLabel.text = "Scene cannot load..."

You can use your custom one by calling the SceneManager.set_loading_screen() method which has a type param to indicate how to use this loading screen:

  • LoadingScreen.Type.DEFAULT. Replaces the default loading screen and uses it on next loads.
  • LoadingScreen.Type.PERSIST. Uses it on next loads until other loading screen is set. You also can use SceneManager.reset_loading_screen() to set the default loading screen.
  • LoadingScreen.Type.ONE_SHOT. Uses it on one load. After setting the default loading screen.

So you can use SceneManager.set_loading_screen() in your main scene to set a default loading screen or the most efficient would be to change the value of the project setting addons/scene_manager/loading_screen/default_scene_path. When SceneManager is ready, it has loaded the packed scene from the setting value.

Applications

When is this plugin useful? Maybe I can think about more things later, for now I have the following in mind:

  • You have a map where your player moves and you did other amazing scene for your battle. Maybe your map scene has the data to load the battle scene, therefore you pass the data as an initial variable in the battle scene. This way, in your root node script, you handle that data in your _ready method.

  • Loading big scenes. When you change the scene using the path, the PackedScene can be loaded in the background adding a min_duration value greater than 0.0.

Clone this wiki locally