Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

Singletons (Autoload)

Introduction

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. In our case, it's possible to reuse the same scene or class for multiple singletons as long as they have different names.

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.

Note

Godot won't make an Autoload a "true" singleton as per the singleton design pattern. It may still be instanced more than once by the user if desired.

Tip

If you're creating an autoload as part of an editor plugin, consider registering it automatically in the Project Settings when the plugin is enabled.

Autoload

You can create an 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 is assigned as the node's name property. The order of the entries as they are added to the global scene tree can be manipulated using the up/down arrow keys. Like regular scenes, the engine will read these nodes in top-to-bottom order.

This means that any node can access a singleton named "PlayerVariables" with:

GDScriptC#

var player_vars = get_node("/root/PlayerVariables")
player_vars.health -= 10

If the Enable column is checked (which is the default), then the singleton can be accessed directly in GDScript, without requiring get_node():

GDScript

PlayerVariables.health -= 10

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:

Warning

Autoloads must not be removed using free()