-
Notifications
You must be signed in to change notification settings - Fork 18
API (Godot 4)
These functions are the bread and butter of scene manager. They allow you to change and reload scenes, or just use transitions without any effect. They're all configurable through an optional "options" parameter, so you can make your transition just right.
SceneManager.change_scene(scene: (String || PackedScene)?, options: Dictionary = defaultOptions) -> void
This method lets you easily change scenes with transitions.
The scene
paremeter accepts an absolute file path for your new scene (i.e: 'res://demo/test.tscn') or a PackedScene
. If null
is passed as the scene, it will reload the current scene,
but for ease-of-use we recommend using the reload_scene()
function explained further down.
SceneManager.reload_scene(options: Dictionary = defaultOptions) -> void
This method reloads your current scene scene, resetting it to it's initial state.
Of note, is that this method will not trigger the scene_unloaded
signal, since nothing is being unloaded. It will however trigger the scene_loaded
signal. If a legitimate use-case for a scene_reloaded
signal arises please open an issue and we will change it.
SceneManager.fade_in_place(options: Dictionary = defaultOptions)
This method will simply trigger the transition, without modifying anything. You can use the fade_complete
signal or the on_fade_out
callback if you want to change something while the screen is completely black.
SceneManager.fade_out(options: Dictionary = defaultOptions)
This method fades out the screen, useful when you want to fade to black and do some calculations/processing manually. Works well in conjunction with the "skip_fade_out"
option.
await SceneManager.fade_out()
// Do something
SceneManager.change_scene(new_scene, { "skip_fade_out": true })
It can take the following options, with the same defaults as change_scene
:
speed
color
pattern
ease
SceneManager.fade_in(options: Dictionary = defaultOptions)
This method fades in the screen, useful to do if you want an initial transition when opening the game.
It can take the following options, with the same defaults as change_scene
:
speed
color
pattern
invert_on_leave
ease
All the above functions optionally take a simple godot Dictionary as a parameter. You can define some or all of the following options, and the remaining ones will stay as their default value.
For example, if you write something like this:
SceneManager.reload_scene({ "speed": 4 })
Your scene will reload with a transition that is twice as fast, but all the other parameters (animation, color, wait time, etc.) will stay the same.
Here are all the possible options with their type, default value, and explanation:
Key | Type | Default value | Explanation |
---|---|---|---|
speed | float | 2 | Speed of the moving transition. (Also affects custom animations) |
color | Color | Color('#000000') | Color to use for the transition screen. It's black by default. |
wait_time | float | 0.5 | Time spent in the transition screen while switching scenes. Leaving it at 0 with fade will result in the screen not turning black, so it waits a little bit by default. |
skip_scene_change | Bool | false | If set to true, skips the actual scene change/reload, leaving only the transition. |
skip_fade_out | Bool | false | If set to true, skips the initial "fade" part of the transition |
skip_fade_in | Bool | false | If set to true, skips the final "fade" part of the transition |
pattern | String or Texture | 'fade' | Pattern to use for the transition. Using a simple name will load the premade patterns we have designed (check the list down below!). Otherwise, you may pass an absolute path to your own pattern "res://my_pattern.png" or a Texture object. |
pattern_enter | String or Texture | Same as 'pattern' value | Same as pattern , but overrides the pattern only for the fade-to-black transition. |
pattern_leave | String or Texture | Same as 'pattern' value | Same as pattern , but overrides the pattern only for the fade-from-black transition. |
invert_on_leave | Bool | true | Wether the transition should invert when fading out of black. This usually looks better on, the effect is that the first pixels that turned black are the first ones that fade into the new screen. This generally works for "sweep" transitions like "horizontal" , but others such as "curtains" might look better with this flag turned off |
ease | float | 1.0 | Amount of ease the animation should have during the transition. |
ease_enter | float | Same as 'ease' value | Amount of ease the animation should have during the fade-to-black transition. |
ease_leave | float | Same as 'ease' value | Amount of ease the animation should have during the fade-from-black transition. |
animation_name | String | null | Name of an animation set in set_animation_player() which will be played for both in and out transitions |
animation_name_enter | String | Same as 'animation_name' value | Same as animation_name , but overrides the pattern only for the fade-to-black transition. |
animation_name_leave | String | Same as 'animation_name' value | Same as animation_name , but overrides the pattern only for the fade-from-black transition. |
on_tree_enter | Callable(new_scene: Node) | Empty Callable | Custom callback called when the new scene enters the tree hierarchy |
on_ready | Callable(new_scene: Node) | Empty Callable | Custom callback called when the new scene is ready |
on_fade_out | Callable | Empty Callable | Custom callback called when the fade_out is finished (screen completely black) |
on_fade_in | Callable | Empty Callable | Custom callback called when the fade_in is finished (transition completely finished) |
"fade"
"circle"
"curtains"
"diagonal"
"horizontal"
"radial"
"scribbles"
"squares"
"vertical"
SceneManager.set_animation_player(animation_player: String || PackedScene)
Set a custom AnimationPlayer
to make your own transitions easily. This is NOT necessary for built-in transitions, and you can still use built-in transitions if you set a custom AnimationPlayer
.
We recommend doing this only once as early as possible in your game, for example in the _ready()
method of an autoload or your first scene.
This method receives a path to (or a PackedScene
of) the location of your AnimationPlayer
scene.
SceneManager.set_animation_player('res://demo/animation_player.tscn')
Your AnimationPlayer
scene must follow these rules:
- The root node must be a Godot
AnimationPlayer
- The animation player must have a
RESET
animation that keeps all your graphics outside of the viewport. This is because the animation player will always be rendered on top of your screen, so any leftovers will always be rendered (you should notice right away if this is the case)
Add your animations to this AnimationPlayer
and then use their names in the options of any SceneManager transition function as animation_name
, animation_name_enter
or animation_name_leave
Please check the demo files in this repository for a complete example.
This feature has become largely irrelevant thanks to the Node Unique Names added in Godot 4. It is not recommended you use it, and it might be removed in the future.
SceneManager.get_entity(entity_name: String)
Get a reference to a named entity (node) in your scene. To define entity names go to the desired node in the editor inspector and you'll see two new properties: Singleton entity
and Entity name
. Check the Singleton entity
checkbox to have this node saved to the SceneManager entity dictionary and write a friendly Entity name
to be used in this function. Afterwards, you'll be able to access it within the scene.
NOTE: If accessing the node in a _ready()
method within your scene, get_entity
will throw an error. This is because saving the entities to the SceneManager requires the scene to be completely loaded, which hasn't happened yet in the _ready()
method. To circumvent this problem, you will have to wait until the scene is completely loaded. To do this, you can take advantage of the scene_loaded
signal provided by SceneManager
, like so:
await SceneManager.scene_loaded
Player = SceneManager.get_entity("Player")
-
SceneManager.is_transitioning: bool
: This variable changes depending on whether a transition is active or not. You can use this to make sure a transition is finished before starting a new one if thetransition_finished
signal does not suit your use-case.
Signals are useful to connect methods to them, or wait for them to happen before executing the next line.
# wait for the "scene_loaded" signal to be emitted
await SceneManager.scene_loaded
# connect the method "_on_scene_loaded" from your object so it runs when SceneManager emits the signal
SceneManager.scene_loaded.connect(_on_scene_loaded)
-
scene_unloaded
: Emitted when the first scene is unloaded -
scene_loaded
: Emitted when the new scene is loaaded -
fade_complete
: Emitted when the fade-to-black animation finishes -
transition_finished
: Emitted when the transition finishes