Godot’s scene system, while powerful and flexible, has a drawback: there is no method for storing information (e.g. a player’s score or inventory) that is needed by more than one scene.
It’s possible to address this with some workarounds, but they come with their own limitations:
- You can use a “master” scene that loads and unloads other scenes as its children. However, this means you can no longer run those scenes individually and expect them to work correctly.
- Information can be stored to disk in
user://and then loaded by scenes that require it, but frequently saving and loading data is cumbersome and may be slow.
The Singleton Pattern is a useful tool for solving the common use case where you need to store persistent information between scenes.
Using this concept, you can create objects that:
- Are always loaded, no matter which scene is currently running
- Can store global variables, such as player information
- Can handle switching scenes and between-scene transitions
- Act like a singleton, since GDScript does not support global variables by design
Autoloading nodes and scripts caters to this need.
You can use AutoLoad to load a scene or a script that inherits from Node. Note: when autoloading a script, a Node will be created and the script will be attached to it. This node will be added to the root viewport before any other scenes are loaded.
To autoload a scene or script, select
Project -> Project Settings from the
menu and switch to the “AutoLoad” tab.
Here you can add any number of scenes or scripts. Each entry in the list
requires a name, which assigned as the node’s
This means that any node can access a singleton named “PlayerVariables” with:
Or even simpler using the name directly:
Note that autoload objects (scripts and/or scenes) are accessed just like any other node in the scene tree. In fact, if you look at the running scene tree, you’ll see the autoloaded nodes appear:
Custom scene switcher¶
This tutorial will demonstrate building a scene switcher using autoload. For basic scene switching, you can use the SceneTree.change_scene() method (see SceneTree for details). However, if you need more complex behavior when changing scenes, this method provides more functionality.
To begin, download the template from here:
autoload.zip and open it in Godot.
The project contains two scenes:
scene contains a label displaying the scene name and a button with its
pressed() signal connected. When you run the project, it starts in
Scene1.tscn. However, pressing the button does nothing.
Switch to the “Script” tab and create a new script called Global.gd. Make sure
it inherits from
The next step is to add this script to the autoLoad list. Open
Project > Project Settings from the menu, switch to the “AutoLoad” tab and
select the script by clicking the
.. button or typing its path:
res://Global.gd. Press “Add” to add it to the autoload list:
Now whenever we run any scene in the project, this script will always be loaded.
Returning to the script, it needs to fetch the current scene in the
_ready() function. Both the current scene (the one with the button) and
global.gd are children of root, but autoloaded nodes are always first. This
means that the last child of root is always the loaded scene.
Now we need a function for changing the scene. This function needs to free the current scene and replace it with the requested one.
As mentioned in the comments above, we need to avoid the situation of deleting the current scene while it is still being used (i.e. its code is still running), so using Object.call_deferred() is required at this point. The result is that the second function will run at a later time when any code from the current scene has completed.
Finally, we need to fill the empty callback functions in the two scenes:
Run the project and test that you can switch between scenes by pressing the button!
Note: When scenes are small, the transition is instantaneous. However, if your scenes are more complex, they may take a noticeable amount of time to appear. To learn how to handle this, see the next tutorial: Background loading