Introduction

Godot's scene system, while powerful and flexible, has a drawback: there is nomethod for storing information (e.g. a player's score or inventory) that isneeded by more than one scene.

It's possible to address this with some workarounds, but they come with theirown limitations:

• You can use a "master" scene that loads and unloads other scenes asits children. However, this means you can no longer run those scenesindividually and expect them to work correctly.

• Information can be stored to disk inuser:// and then loaded by scenesthat require it, but frequently saving and loading data is cumbersome andmay be slow.

TheSingleton pattern isa useful tool for solving the common use case where you need to storepersistent information between scenes. In our case, it's possible to reuse thesame scene or class for multiple singletons as long as they have differentnames.

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 can give us these characteristics.

Autoload

You can create an Autoload to load a scene or a script that inherits fromNode.

To autoload a scene or script, start from the menu and navigate toProject > Project Settings > Globals > Autoload.

Here you can add any number of scenes or scripts. Each entry in the listrequires a name, which is assigned as the node'sname property. The order ofthe entries as they are added to the global scene tree can be manipulated usingthe up/down arrow keys. Like regular scenes, the engine will read these nodesin top-to-bottom order.

If theEnable column is checked (which is the default), then the singleton canbe accessed directly in GDScript:

PlayerVariables.health-=10

TheEnable column has no effect in C# code. However, if the singleton is aC# script, a similar effect can be achieved by including a static propertycalledInstance and assigning it in_Ready():

publicpartialclassPlayerVariables:Node{publicstaticPlayerVariablesInstance{get;privateset;}publicintHealth{get;set;}publicoverridevoid_Ready(){Instance=this;}}

This allows the singleton to be accessed from C# code withoutGetNode() andwithout a typecast:

PlayerVariables.Instance.Health-=10;

Note that autoload objects (scripts and/or scenes) are accessed just like anyother 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 autoloads.For basic scene switching, you can use theSceneTree.change_scene_to_file()method (seeUsing SceneTree for details). However, if you need morecomplex behavior when changing scenes, this method provides more functionality.

To begin, download the template from here:singleton_autoload_starter.zipand open it in Godot.

A window notifying you that the project was last opened in an older Godot versionmay appear, that's not an issue. ClickOk to open the project.

The project contains two scenes:scene_1.tscn andscene_2.tscn. Eachscene contains a label displaying the scene name and a button with itspressed() signal connected. When you run the project, it starts inscene_1.tscn. However, pressing the button does nothing.

Creating the script

Open theScript window and create a new script calledglobal.gd.Make sure it inherits fromNode:

The next step is to add this script to the autoLoad list.Starting from the menu, openProject > Project Settings > Globals > Autoload andselect the script by clicking the browse button or typing its path:res://global.gd. PressAdd to add it to the autoload listand name it "Global", which is required for scripts to access itby the name "Global":

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) andglobal.gd are children of root, but autoloaded nodes are always first. Thismeans that the last child of root is always the loaded scene.

GDScriptC#

extendsNodevarcurrent_scene=nullfunc_ready():varroot=get_tree().root# Using a negative index counts from the end, so this gets the last child node of `root`.current_scene=root.get_child(-1)

Now we need a function for changing the scene. This function needs to free thecurrent scene and replace it with the requested one.

GDScriptC#

funcgoto_scene(path):# This function will usually be called from a signal callback,# or some other function in the current scene.# Deleting the current scene at this point is# a bad idea, because it may still be executing code.# This will result in a crash or unexpected behavior.# The solution is to defer the load to a later time, when# we can be sure that no code from the current scene is running:_deferred_goto_scene.call_deferred(path)func_deferred_goto_scene(path):# It is now safe to remove the current scene.current_scene.free()# Load the new scene.vars=ResourceLoader.load(path)# Instance the new scene.current_scene=s.instantiate()# Add it to the active scene, as child of root.get_tree().root.add_child(current_scene)# Optionally, to make it compatible with the SceneTree.change_scene_to_file() API.get_tree().current_scene=current_scene

UsingObject.call_deferred(),the second function will only run once all code from the current scene hascompleted. Thus, the current scene will not be removed while it isstill being used (i.e. its code is still running).

Finally, we need to fill the empty callback functions in the two scenes:

GDScriptC#

# Add to 'scene_1.gd'.func_on_button_pressed():Global.goto_scene("res://scene_2.tscn")

and

GDScriptC#

# Add to 'scene_2.gd'.func_on_button_pressed():Global.goto_scene("res://scene_1.tscn")

Run the project and test that you can switch between scenes by pressingthe button.

Note

When scenes are small, the transition is instantaneous. However, if yourscenes 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.

Alternatively, if the loading time is relatively short (less than 3 seconds or so),you can display a "loading plaque" by showing some kind of 2D element just beforechanging the scene. You can then hide it just after the scene is changed. This canbe used to indicate to the player that a scene is being loaded.