Overview
As game development progresses, needs arise like "I want to carry over the player's HP to the next stage," "I want to record a high score," or "I want to centrally manage game-wide settings." However, in Godot, when you switch scenes with change_scene_to_file(), all information from the old scene is normally discarded.
The easiest and most powerful way to solve this problem and persist data across scenes is the Autoload feature. This is a mechanism that easily implements the design pattern commonly known as a "singleton" in Godot.
This article covers the Autoload concept and usage, helping you master game-wide shared data management.
What is Autoload (Singleton)?
Autoload is a node (or just a script) that is automatically loaded when the game starts and remains in memory until the game ends. Once registered with Autoload, it becomes accessible like a global variable from any script in any scene.
Primary Uses:
- Global State Management: Information shared across the entire game, like player score, money, and lives
- Universal Functionality: Features you want to call from anywhere, like sound management, scene transition effects, and settings
- Manager Nodes: A master entity that manages overall game progression
How to Set Up Autoload
Autoload setup takes just a few clicks from project settings.
1. Create a Global Script
First, create a script with the data or functionality you want to manage. For example, create a script named GlobalState.gd with the following content:
extends Node
var current_score = 0
var high_score = 0
func add_score(amount):
current_score += amount
if current_score > high_score:
high_score = current_score
func reset_score():
current_score = 0
2. Open Project Settings
From the menu bar, select "Project" → "Project Settings".
3. Navigate to Autoload Tab
Select "Autoload" from the tabs at the top.
4. Register the Script
Click the folder icon next to "Path" and select the GlobalState.gd you created. The "Node Name" automatically becomes GlobalState (same as the script name, but can be changed). Press the "Add" button to complete registration.
Accessing from Scripts
The node registered with Autoload (GlobalState in this example) functions like a global variable using the registered node name. You can access it directly from any script without prior get_node() or @onready declarations.
# Processing when defeating an enemy
func _on_enemy_defeated():
# Directly call GlobalState function
GlobalState.add_score(100)
print("Current Score: ", GlobalState.current_score)
# Game over screen processing
func _ready():
# Directly reference GlobalState variable
$HighScoreLabel.text = "High Score: %d" % GlobalState.high_score
As shown, accessing anywhere with the name GlobalState makes passing data across scenes very simple.
Summary
Autoload is fundamental to global data management in Godot and is a very powerful tool. When you want to persist information across scenes or create convenient functions callable from anywhere, consider using Autoload first.
However, registering everything with Autoload can make code dependencies complex and reduce clarity. The secret to maintaining a clean project is identifying data and functions that truly need to be "global."