API (Godot 3)

Table of contents

• Methods
  • change_scene()
  • reload_scene()
  • fade_in_place()
  • fade_out()
  • fade_in()
  • set_animation_player()
  • get_entity()
• Variables
  • is_transitioning
• Signals
  • scene_unloaded
  • scene_loaded
  • fade_complete
  • transition_finished
• Deprecation Warnings

Methods

change_scene()

SceneManager.change_scene(scene: (String || PackedScene)?, options: Dictionary = defaultOptions) -> void

This method lets you easily change scenes with transitions. They're highly customizable and we will consider adding progressive loading if it's requested enough.

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(options) function explained further down.

You can pass the following options to this function in a dictionary:

• 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 || Texture) = 'fade': Pattern to use for the transition. Using a simple name will load the premade patterns we have designed (you can see them in addons/scene_manager/shader_patterns). Otherwise, you may pass an absolute path to your own pattern "res://my_pattern.png" or a Texture object. You can also specify 'fade' for a simple fade transition.
• pattern_enter : (String || Texture) = pattern: Same as pattern, but overrides the pattern only for the fade-to-black transition.
• pattern_leave : (String || Texture) = pattern: 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 = ease: Amount of ease the animation should have during the fade-to-black transition.
• ease_leave : float = ease: Amount of ease the animation should have during the fade-from-black transition.
• animation_name : String: Name of an animation set in set_animation_player() which will be played for both in and out transitions
• animation_name_enter : String: Name of an animation set in set_animation_player() which will be played for the fade-to-black transition
• animation_name_leave : String: Name of an animation set in set_animation_player() which will be played for the fade-from-black transition

The following patterns are available out-of-the-box:

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

reload_scene()

SceneManager.reload_scene(options: Dictionary = defaultOptions) -> void

This method functions exactly like change_scene(current_scene_path, options), but you do not have to provide the path and it should be slightly faster since it reloads the scene rather than removing it and instantiating again.

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 functions exactly like reload_scene({ "no_scene_change": true }), it will simply trigger the transition used in options, without modifying anything. You can use the fade_complete signal 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.

yield (SceneManager.fade_out(), "completed")
// 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

set_animation_player()

SceneManager.set_animation_player(animation_player: String || PackedScene)

Set a custom AnimationPlayer make your own transitions easily. 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:

yield(SceneManager, "scene_loaded")
Player = SceneManager.get_entity("Player")

Variables

is_transitioning

SceneManager.is_transitioning: bool

This variable changes depending of wether 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
yield(SceneManager, "scene_loaded")

# connect the method "_on_scene_loaded" from your object so it runs when SceneManager emits the signal
SceneManager.connect("scene_loaded", self, "_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

Deprecation Warnings

The following deprecation warnings are in effect. These features may still work, but will be removed in the future. If you use any of the features below, please follow the instructions:

• type option and FadeTypes enum: remove entirely. For normal fade transitions, use "pattern": "fade".
• shader_pattern option: replace for pattern
• shader_pattern_enter option: replace for pattern_enter
• shader_pattern_leave option: replace for pattern_leave
• no_scene_change option: replace for skip_scene_change
• ease, ease_enter, ease_leave options: do not use bool values. Replace true -> 0.5 and false -> 1.0.