Skip to content

Home

Jump to bottom
Manolo Cantón edited this page Jul 3, 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 dependencies

You can load extra resources to pass to next scene properties. You must use LoadingScreenDependencyRef which returns the SceneManager.append_dependency 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 dictionaries values too, but it doesn't work with object properties.

SceneManager.change_scene_to_file("my_scene.tscn", {
    characters = [
        SceneManager.append_resource("my_character_data.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 LoadingScreenBase 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.

You can set your custom loading screen path in addons/scene_manager/loading_screen project setting (you can find it in Project Settings window). SceneManager will load your loading screen when you run your project next time.

extends LoadingScreenBase

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..."

Since version 1.4, you also can set a default loading screen with SceneManager.set_loading_screen() where type param must be SceneManager.LoadingScreenType.DEFAULT. ONE_SHOT type uses the loading screen on one load, after default screen is set. PERSIST type is used until SceneManager.set_loading_screen() or SceneManager.reset_loading_screen() calls.

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