A scene manager addon for Godot. Handles changing scenes, managing transitions, and asynchronous loading all with a simple but flexible API.
You can install the addon manually or through the asset store.
Note
If your version of Godot is not supported by the latest version of the addon you may need to download the addon manually so that you can pick an older version.
- Download the addon from the GitHub Releases page.
- Unzip the addon folder.
- Create an
res://addonsfolder in your Godot project if you do not already have one. - Drag the addon folder into your
res://addonsfolder. - Enable "Scenic" in
Project Settings > Plugins.
- Navigate to the
Asset Storetab in your Godot project. - Locate the "Search" addon and click on it.
- Click the download button.
- Enable "Scenic" in
Project Settings > Plugins.
Scenic works by completely circumventing the regular Godot scene system. Projects made with this addon will define one main scene containing the scene manager that will be loaded throughout the whole duration of the program.
It is recommended that the root node of your main scene is a SceneManager. The scene manager is responsible for managing things like loading and instantiating scenes as well as things like scene transitions.
A basic scene manager set-up with one transition. See Transitions for more information about creating transitions.
Make sure your SceneManager node has global set to true. Scenic lets you use multiple scene managers but only one is allowed to be "global". The global scene can be accessed through the GlobalSceneManager autoload.
Once you have your main scene setup make sure to make it the default scene in Project Settings > General > Application > Run > Main Scene.
You can add scenes to your scene manager by dragging them onto the scenes list in the inspector.
Warning
The root node of any scene must be of type Scene.
From here you can set the properties of your scenes including:
- Name: The name of your scene. Used to reference the scene in code.
- Initial: Whether this scene is initial or not. Initial scenes are instantiated on project load.
- Load on Start: Whether this scene should load when the project starts. Scenes with this setting are kept in memory throughout the whole runtime of the program.
Set at least one scene to initial to get started.
Scenic is designed to be as flexible as possible while keeping the core API simple. Because of this you may not need to read this whole section before you start using the addon. The features are ordered by how important they are to the average user.
This is how you do the very basic scene change that you would expect from any scene manager addon. It will free the previously loaded scene(s) and instantiate the new one.
GlobalSceneManager.queue_set_scene(&"Scene 2")
GlobalSceneManager.apply()Tip
If you don't like typing & in front of all your strings, you don't have to! The & is used to mark the string as a StringName but it isn't required by Godot.
Technically you could stop here and you would be able to manage your scenes, but you'd be missing out on a lot of the benefits of using Scenic.
Before we go any further it is important to explain a few points about how the scene manager handles scenes.
Scene managers in Scenic can have multiple scenes loaded at once. Because of this Scenic offers more control than just queue_set_scene() in the form of.
queue_add_scene()andqueue_add_scenes()queue_reload_scene()andqueue_reload_scenes()queue_remove_scene()andqueue_remove_scenes()
This allows you to do things like swap out the current level without swapping out the HUD or the pause menu.
func _ready() -> void:
GlobalSceneManager.queue_remove_scenes()
GlobalSceneManager.queue_add_scenes([&"Level 1", &"HUD", &"Pause Menu"])
GlobalSceneManager.apply()
func _on_level_1_finished() -> void:
GlobalSceneManager.queue_remove_scene(&"Level 1")
GlobalSceneManager.queue_add_scene(&"Level 2")
GlobalSceneManager.apply()
# Alternative code using queue_set_scene's exclude functionality.
# This code assumes that all scenes we want to keep have the "UI" tag applied in the inspector.
GlobalSceneManager.queue_set_scene(&"Level 2", null, [&"UI"])
GlobalSceneManager.apply()Note
If you don't care about having multiple scenes then you can just use queue_set_scene and it will behave as you would expect.
GlobalSceneManager.queue_set_scene(&"Scene 2")
GlobalSceneManager.apply()As I'm sure you have noticed, Scenic doesn't allow you to directly perform scene operations like set_scene, add_scene, etc. instead requiring you to queue them up and then apply them with apply(). This is because Scenic handles asynchronous scene loading automatically and queuing allows it to start loading the scenes before they need to be instantiated.
This will be especially useful when we start talking about scene transitions because the scenes can start loading at the beginning of the transition animation.
One important feature of Scenic is that it can handle scene transitions for you. To set up a scene transition all you need to do is add it as a child of the scene manager.
To start we will walk through the set up for the built in FadeTransition and then after that we will talk about making custom transitions.
To create a fade transition add a FadeTransition node as a child of your scene manager. It should look something like this.
Note
In this example we rename our FadeTransition to "Fade" for easy access later.
Looking at the FadeTransition in the inspector we can see that it takes in a curtain reference as well as a few other settings. The curtain is the control node that will fade in when we do the transition. Add a Panel node as a child and drag it into the curtain slot.
To use the fade transition, replace your call to apply() with a call to with_transition() like this.
GlobalSceneManager.queue_set_scene(&"Scene 2")
GlobalSceneManager.with_transition(&"Fade") # The name used to reference the transition here is the name of the SceneTransition node.You can also create your own custom transitions. In Scenic transitions are just a type of node so you can create your own by creating a class that extends SceneTransition.
# Include a reference to the icon in all transitions otherwise it will have the wrong icon.
@icon("res://addons/scenic/icons/fast_forward.svg")
class_name MyCustomTransition extends SceneTransition
# Required functions, all transitions must implement these.
func transition_in(time_scale: float = 1.0) -> void:
# ... do transition in to transition screen
func set_in() -> void:
# ... instantly set state to transition screen showing
func transition_out(time_scale: float = 1.0) -> void:
# ... do transition out of transition screen
func set_out() -> void:
# ... instantly set state to transition screen hiddenIf you want to use the fade transition as a reference you can find it in res://assets/scenic/nodes/transitions.
Scenic allows you to pass data along whenever you add, set, or reload a scene using the data parameter like this.
var important_data_1 = 42.0
var important_data_2 = {
"name": "John",
"health": 100.0
}
GlobalSceneManager.queue_set_scene(&"Scene 2", important_data_1)
GlobalSceneManager.queue_add_scene(&"Scene 3", important_data_2)
GlobalSceneManager.apply()This data can then be received by the scene by having it implement the _start method.
@icon("res://addons/scenic/icons/clapperboard.svg")
class_name Scene2Class extends Scene
func _start(data: Variant) -> void:
print("Data received: %d" % data)Warning
This section of the documentation is under construction.
Warning
This section of the documentation is under construction.
Warning
This section of the documentation is under construction.
Warning
This section will be added later.
- If you are struggling with using Scenic, feel free to ask for help in my Discord server.
- If you have found a bug or issue with the addon, please create an issue.
- Node icons & logo from @icons
- Background image from ClickerHappy