Skip to content

API (Godot 4)

Jump to bottom
jabsatz edited this page Mar 4, 2023 · 6 revisions

Table of contents

Methods

Transition Methods

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.

change_scene()

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.

reload_scene()

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.

fade_in_place()

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.

fade_out()

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

fade_in()

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

Transition Options

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)

Built-in patterns:

  • "fade"
  • "circle"
  • "curtains"
  • "diagonal"
  • "horizontal"
  • "radial"
  • "scribbles"
  • "squares"
  • "vertical"

set_animation_player()

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:

  1. The root node must be a Godot AnimationPlayer
  2. 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.

get_entity()

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

Variables

  • 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 the transition_finished signal does not suit your use-case.

Signals

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
Clone this wiki locally