Skip to content

API Reference

Jump to bottom
github-actions[bot] edited this page Aug 20, 2026 · 2 revisions

API Reference

Contents

SceneManager

Inherits Node2D.

Scene transitions with animated fades, a drop-in replacement for SceneTree.change_scene_to_file.

Autoloaded as SceneManager, so it is reachable from anywhere without a preload. Every method takes an options dictionary merged over default_options, so a call only names the keys it changes:

SceneManager.change_scene("res://levels/two.tscn", { "pattern": "squares" })

Large scenes can be loaded off the main thread so the load overlaps the fade instead of stalling it, optionally behind a loading screen:

SceneManager.change_scene("res://levels/big.tscn", {
    "loading_screen": true,
    "min_loading_time": 1.0,
})

Use preload_scene to start that load earlier still. Every method can be awaited to continue once the transition is over.

Defaults live under Project > Project Settings > Scene Manager, and set_animation_player swaps the built-in shader fade for animations of your own.

Full documentation

Methods

change_scene

change_scene(path: Variant, setted_options: Dictionary = {}) -> void

Swaps in a new scene, fading out before the swap and back in after it. Await it to continue once the whole transition is over.

path takes a String path, an already loaded PackedScene, or null to reload the current scene. setted_options is merged over default_options.

If the load fails the swap is abandoned and the screen fades back in, leaving the current scene running.

reload_scene

reload_scene(setted_options: Dictionary = {}) -> void

Reloads the current scene from disk, with the same transition change_scene uses.

fade_out

fade_out(setted_options: Dictionary = {}) -> void

Covers the screen, playing the fade forwards. Await it to continue once the screen is fully hidden. Pair it with fade_in to drive a transition by hand, or with skip_fade_out to get work done while the screen is covered:

await SceneManager.fade_out()
# ... reposition the player, save the game, whatever needs hiding ...
SceneManager.change_scene("res://levels/two.tscn", { "skip_fade_out": true })

Reads speed, color, pattern_enter, invert_on_enter, ease_enter and animation_name_enter; the rest of the options do not apply.

fade_in

fade_in(setted_options: Dictionary = {}) -> void

Reveals the screen again, playing the fade backwards. Await it to continue once the screen is clear — useful on its own for an opening transition when the game starts.

Reads speed, color, pattern_leave, invert_on_leave, ease_leave and animation_name_leave; the rest of the options do not apply.

fade_in_place

fade_in_place(setted_options: Dictionary = {}) -> void

Fades out and back in without changing scene, useful for covering work done in an on_fade_out callable such as repositioning the player.

preload_scene

preload_scene(path: String, cache_mode: int = 0) -> void

Starts loading path on a worker thread so a later change_scene can swap it in with no wait. Does nothing if that scene is already loaded or in flight.

Track it with background_load_progress and background_load_finished, or poll get_load_progress and is_scene_ready.

is_scene_ready

is_scene_ready(path: String) -> bool

Returns true if path has finished preloading and is waiting to be handed over.

get_load_progress

get_load_progress(path: String) -> float

Returns how far along the threaded load of path is, from 0.0 to 1.0. Returns 1.0 once the scene is ready, and 0.0 for a path that was never requested.

drop_preloaded_scene

drop_preloaded_scene(path: String) -> void

Throws away a scene kept by preload_scene, freeing the memory it holds.

Godot cannot cancel a threaded request, so a load still in flight is not stopped: it is marked and discarded the moment it arrives.

set_animation_player

set_animation_player(animation_player: Variant) -> void

Registers a custom AnimationPlayer so a project can transition with its own animations instead of the built-in shader fade.

animation_player is a path to a scene, or an already loaded PackedScene, whose root node is an AnimationPlayer. Pass null to go back to the built-in fade. SceneManager instantiates the scene and holds on to it, so it outlives the scene swaps it animates. It can also be set once under Project > Project Settings > Scene Manager.

The scene must set AnimationMixer.root_node to NodePath(".") so its tracks resolve against itself, and should carry a RESET animation that parks every visual offscreen, since the player is always rendered over the game.

An animation named DEFAULT_ANIMATION_NAME takes over every transition on its own. Any other animation is opt-in per call and per side, through the animation_name, animation_name_enter and animation_name_leave options:

SceneManager.set_animation_player("res://transitions/roll.tscn")
SceneManager.change_scene("res://levels/two.tscn", {
    "animation_name_enter": "roll",  # custom animation covers the screen
    "pattern_leave": "squares",      # built-in shader fade reveals it
})

Passing null for a side forces the built-in fade there. Whichever of the two is not animating is cleared instantly the moment the other takes over.

Only speed applies to custom animations: pattern, color, invert_on_* and ease shape the built-in shader fade alone.

Properties

is_transitioning

is_transitioning: bool = false

true while a transition is running. Check it before starting another one, so a button mashed twice cannot fire two overlapping transitions.

default_options

default_options: Dictionary

Options used by every call, check full docs here

Signals

fade_started

fade_started()

Emitted when a fade begins, in either direction.

fade_complete

fade_complete()

Emitted when a fade out ends, with the screen fully covered.

scene_unloaded

scene_unloaded()

Emitted after the outgoing scene has been freed.

scene_loaded

scene_loaded()

Emitted once a new scene is in the tree. Also fires for scene changes made by other code, such as a direct SceneTree.change_scene_to_file call.

transition_finished

transition_finished()

Emitted when a transition is completely over and the screen is clear again.

background_load_started

background_load_started(path: String)

Emitted when a threaded load of path starts.

background_load_progress

background_load_progress(path: String, progress: float)

Reports threaded loading progress for path, from 0.0 to 1.0. Emitted per path, since several loads can be in flight at once.

background_load_finished

background_load_finished(path: String)

Emitted when path has finished loading and is ready to be swapped in.

background_load_failed

background_load_failed(path: String)

Emitted when path failed to load. The scene swap is abandoned and the screen fades back in rather than stranding the player behind an opaque overlay.

Constants

DEFAULT_LOADING_SCREEN

DEFAULT_LOADING_SCREEN

The loading screen used when loading_screen is true: a progress bar centred on a transparent background.

DEFAULT_ANIMATION_NAME

DEFAULT_ANIMATION_NAME = "Fade"

The animation every transition plays by default, on the built-in player and on a custom one alike. A player set through set_animation_player takes over the whole transition simply by defining an animation with this name.

DefaultLoadingScreen

Inherits Control.

The loading screen shown when loading_screen is true.

A progress bar centred on a transparent background. To use your own instead, pass a PackedScene as loading_screen; the only thing SceneManager asks of it is a set_progress method, which is called every frame while the scene loads. Anything without one is still shown, just never told how far along the load is.

Methods

set_progress

set_progress(value: float) -> void

Called every frame with the load progress, from 0.0 to 1.0.

SceneManagerSettings

Inherits RefCounted.

Project Settings backing SceneManager.default_options.

The editor plugin calls register to make these show up under Project > Project Settings > Scene Manager; the autoload calls build_defaults as it is created. The two never have to agree on anything but the DEFINITIONS table, which is where every default value is written down once. The Callable options are the only ones absent, having nothing Project Settings could show. Options that a single transition usually flips rather than a project — the skip_* switches and cache_mode — are marked advanced, so they sit behind the Advanced Settings toggle instead of cluttering the panel.

Methods

register

register() -> void

Declares every setting so the editor shows it with the right widget. Values equal to their initial value are not written to project.godot, so this leaves the project file untouched until someone actually changes something.

build_defaults

build_defaults() -> Dictionary

Builds the configurable half of SceneManager.default_options — every option this table covers, read from the project and falling back to the shipped default. A project where register never ran therefore behaves exactly as the shipped defaults do.

get_animation_player_path

get_animation_player_path() -> String

Reads the configured custom animation player scene, or an empty string when there is none.

Constants

DEFINITIONS

DEFINITIONS = [{"default": 2.0, "hint": 1, "hint_string": "0.1,20,0.1,or_greater", "key": "speed", "setting": "scene_manager/defaults/speed", "type": 3}, {"default": Color(0, 0, 0, 1), "hint": 0, "hint_string": "", "key": "color", "setting": "scene_manager/defaults/color", "type": 20}, {"default": "fade", "hint": 3, "hint_string": "fade,circle,curtains,diagonal,horizontal,radial,scribbles,squares,vertical", "key": "pattern", "setting": "scene_manager/defaults/pattern", "type": 4}, {"default": 0.5, "hint": 1, "hint_string": "0,5,0.05,or_greater", "key": "wait_time", "setting": "scene_manager/defaults/wait_time", "type": 3}, {"default": false, "hint": 0, "hint_string": "", "key": "invert_on_enter", "setting": "scene_manager/defaults/invert_on_enter", "type": 1}, {"default": true, "hint": 0, "hint_string": "", "key": "invert_on_leave", "setting": "scene_manager/defaults/invert_on_leave", "type": 1}, {"default": 1.0, "hint": 1, "hint_string": "0.1,5,0.1,or_greater", "key": "ease", "setting": "scene_manager/defaults/ease", "type": 3}, {"default": "Fade", "hint": 0, "hint_string": "", "key": "animation_name", "setting": "scene_manager/defaults/animation_name", "type": 4}, {"default": true, "hint": 0, "hint_string": "", "key": "background_loading", "setting": "scene_manager/defaults/background_loading", "type": 1}, {"default": "", "hint": 13, "hint_string": "*.tscn", "key": "loading_screen", "setting": "scene_manager/defaults/loading_screen", "type": 4}, {"default": 0.0, "hint": 1, "hint_string": "0,10,0.1,or_greater", "key": "min_loading_time", "setting": "scene_manager/defaults/min_loading_time", "type": 3}, {"default": "", "hint": 13, "hint_string": "*.tscn", "key": "", "setting": "scene_manager/animation_player", "type": 4}, {"advanced": true, "default": 0, "hint": 2, "hint_string": "Ignore:0,Reuse:1,Replace:2,Ignore Deep:3,Replace Deep:4", "key": "cache_mode", "setting": "scene_manager/defaults/cache_mode", "type": 2}, {"advanced": true, "default": false, "hint": 0, "hint_string": "", "key": "skip_scene_change", "setting": "scene_manager/defaults/skip_scene_change", "type": 1}, {"advanced": true, "default": false, "hint": 0, "hint_string": "", "key": "skip_fade_out", "setting": "scene_manager/defaults/skip_fade_out", "type": 1}, {"advanced": true, "default": false, "hint": 0, "hint_string": "", "key": "skip_fade_in", "setting": "scene_manager/defaults/skip_fade_in", "type": 1}]

One entry per setting. key is the SceneManager.default_options key it feeds, or an empty string for a setting that is not an option.

Home

Guides

Reference

Clone this wiki locally