🎬Scene Transicioner

This handler facilitates seamless transitions between scenes, offering the option to include a loading screen, particularly useful for larger scenes.

Getting started

The singleton can be accessed through GodotEssentialsSceneTransitioner. This manager utilizes the foundational class GodotEssentialSceneTransition to manage scene transitions.

To effectively utilize this system, you are required to create your transition scenes by extending the foundational class GodotEssentialSceneTransition. These transition scenes should incorporate the essential signals and parameters necessary for seamless integration with the singleton.

The GodotEssentialSceneTransition primarily functions as a container for managing additional parameters and emitting the appropriate signals.

For example, consider a real use case, such as a fade scene where you can specify the animation name to choose between different types of fades (e.g., 'fade_in' or 'fade_out').

The target_scene parameter can be provided as either a PackedScene or the file path to the desired scene:

var target_scene = preload("res://example.tscn") # or "res://example.tscn"
var your_transition_scene = preload("res://transitions/fade.tscn")

GodotEssentialSceneTransitioner.transition_to(target_scene, your_transition_scene, {"animation": "fade_in"})

# This is your transition_scene
extends GodotEssentialsSceneTransition

@onready var animation_player: AnimationPlayer = $AnimationPlayer

func _ready():
	animation_player.animation_finished.connect(on_animation_finished)
	animation_player.play(data["animation"])
	

func on_animation_finished(name: String):
	if name in animation_player.get_animation_list():
		finished_transition.emit(data)
		queue_free()

It's important to note that the finished_transition signal must be manually emitted. This design choice provides flexibility in determining precisely when a transition is considered complete.

Transition with loading screen

This class offers a function designed for working with a loading screen as a transition. To utilize this functionality, your custom loading scene must also extend from GodotEssentialSceneTransition to receive progression data.

In this case, the finished_transition signal is emitted after the progress value reachs 1 when the scene load is completed.

This feature is particularly beneficial for large scenes where loading times may be longer. When providing the scene, it should be passed as a file path since our class internally leverages the ResourceLoader

var target_scene = "res://large_scene_example.tscn"
var loading_scene = preload("res://transitions/loading.tscn")

GodotEssentialSceneTransitioner.transition_to_with_loading(target_scene, loading)

In the loading scene, you gain access to progress and load status data retrieved from the ResourceLoader, which you can utilize to display relevant information. Below is a basic example to demonstrate this functionality.

To ensure proper functionality, it's essential to call the parent _process() function; failing to do so will result in the information not being updated:

extends GodotEssentialsSceneTransition

@onready var progress_bar: ProgressBar = $CenterContainer/ProgressBar

func _process(delta):
	super._process(delta)
	progress_bar.value = progress[0]

API reference

GodotEssentialsSceneTransicioner

transition_to(scene, transition: PackedScene, data: Dictionary = {})

The primary function responsible for initiating the transition to the target scene is the transition_to function. Any data passed to this function will be accessible within the transition scene, enabling the incorporation of external parameters as needed.

It is focused on transitioning pre-loaded scenes.

The scene parameter can be received as PackedScene or String file path

It's worth noting that the transition scene is added to the viewport, not the scene tree. This approach ensures that the transition will execute even if nodes in the main tree are freed

transition_to_with_loading(scene: String, loading_scene: PackedScene, data: Dictionary = {})

It behaves identically to transition_to, but with one key distinction: the scene parameter must be provided as a file path string. This requirement is due to the transitioner's utilization of the ResourceLoader for scene loading

GodotEssentialsSceneTransition

Variables

• data: Dictionary

• progress: Array

• load_status: ThreadLoadStatus

enum  ThreadLoadStatus:

● THREAD_LOAD_INVALID_RESOURCE = 0
The resource is invalid, or has not been loaded with load_threaded_request().
● THREAD_LOAD_IN_PROGRESS = 1
The resource is still being loaded.
● THREAD_LOAD_FAILED = 2
Some error occurred during loading and it failed.
● THREAD_LOAD_LOADED = 3
The resource was loaded successfully and can be accessed via load_threaded_get().

Signals

• started_transition(data:Dictionary)

• finished_transition(data:Dictionary, next_scene) next_scene it's only provided on transition_to_with_loading