> For the complete documentation index, see [llms.txt](https://godot-essentials.gitbook.io/addons-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://godot-essentials.gitbook.io/addons-documentation/autoload/scene-transicioner.md).

# 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:

```python
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"})
```

```python
# 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](https://docs.godotengine.org/en/stable/classes/class_resourceloader.html)

```python
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](https://docs.godotengine.org/en/stable/classes/class_resourceloader.html), 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:

<pre class="language-python"><code class="lang-python"><strong>extends GodotEssentialsSceneTransition
</strong>
@onready var progress_bar: ProgressBar = $CenterContainer/ProgressBar

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

</code></pre>

## 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 ](https://docs.godotengine.org/en/stable/classes/class_resourceloader.html)for scene loading

### GodotEssentialsSceneTransition

#### Variables

* *data: Dictionary*
* *progress: Array*
* *load\_status: ThreadLoadStatus*

```python
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`*