Up to date

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

Singletons (Autoload)

Introduction

Bien que puissant et flexible, le gestionnaire de scène de Godot présente un inconvénient : il n'y a pas de méthode pour stocker des informations (comme le score d'un joueur ou son inventaire) nécessaires à plusieurs scènes.

Il a différentes solutions pour contourner ceci, mais celles-ci ont leurs propres limites :

Vous pouvez utiliser une scène "maître" qui charge et décharge d'autres scènes comme ses enfants. Toutefois, cela signifie que vous ne pouvez plus exécuter ces scènes individuellement et vous attendre à ce qu'elles fonctionnent correctement.
Bien que des informations puissent être enregistrées sur le disque dans user:// et ensuite qu'elles puissent être chargées par les scènes qui en ont besoin, sauvegarder et charger fréquemment des données peut être lourd et éventuellement lent.

Le Patron de Conception Singleton est un outil utile pour résoudre le cas d'utilisation courante où vous devez stocker des informations persistantes entre les scènes. Dans notre cas, il est possible de réutiliser la même scène ou classe pour plusieurs singletons, à condition qu'ils aient des noms différents.

En utilisant ce concept, vous pouvez créer des objets qui :

Sont toujours chargés, quelle que soit la scène en cours d'exécutions.
Peuvent stocker des variables globales telles que les informations du joueur.
Peuvent s'occuper des changements de scènes et des transitions.
Agissent comme un singleton, puisque GDScript ne supporte pas les variables globales du fait de sa conception.

Les nœuds Autoload et les scripts répondent à ce besoin.

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.

Astuce

Si vous créez un chargement automatique dans le cadre d'un plugin d'éditeur, considérez l'enregistrer automatiquement dans les paramètres du projet quand le plugin est activé.

Autoload

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

Note

Lors de l'auto-chargement d'un script, un Node sera créé et le script y sera attaché. Ce nœud sera ajouté au viewport racine avant que d'autres scènes ne soient chargées.

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

Vous pouvez y ajouter un nombre quelconque de scènes ou de scripts. Chaque entrée de la liste nécessite un nom, qui est attribué comme propriété du nœud name. L'ordre des entrées au fur et à mesure qu'elles sont ajoutées à l'arbre de scène global peut être manipulé à l'aide des touches fléchées haut/bas. Comme pour les scènes ordinaires, le moteur lira ces nœuds dans l'ordre de haut en bas.

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

PlayerVariables.health -= 10

The Enable column has no effect in C# code. However, if the singleton is a C# script, a similar effect can be achieved by including a static property called Instance and assigning it in _Ready():

public partial class PlayerVariables : Node
{
    public static PlayerVariables Instance { get; private set; }

    public int Health { get; set; }

    public override void _Ready()
    {
        Instance = this;
    }
}

This allows the singleton to be accessed from C# code without GetNode() and without a typecast:

PlayerVariables.Instance.Health -= 10;

Notez que les objets chargés automatiquement (scripts et/ou scènes) sont accessibles comme n'importe quel autre nœud dans l'arborescence de la scène. En fait, si vous examinez l'arborescence de la scène en cours d'exécution, vous verrez que les nœuds auto-chargés apparaissent :

Avertissement

Les chargements automatiques ne doivent pas être retirés en utilisant free() ou queue_free() en cours d'exécution, ou le moteur plantera.

Changeur de scène personnalisé

This tutorial will demonstrate building a scene switcher using autoloads. For basic scene switching, you can use the SceneTree.change_scene_to_file() method (see Utilisation de 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: singleton_autoload_starter.zip and open it in Godot.

A window notifying you that the project was last opened in an older Godot version may appear, that's not an issue. Click Ok to open the project.

The project contains two scenes: scene_1.tscn and scene_2.tscn. Each scene contains a label displaying the scene name and a button with its pressed() signal connected. When you run the project, it starts in scene_1.tscn. However, pressing the button does nothing.

Creating the script

Open the Script window and create a new script called global.gd. Make sure it inherits from Node:

The next step is to add this script to the autoLoad list. Starting from the menu, open Project > Project Settings > Globals > Autoload and select the script by clicking the browse button or typing its path: res://global.gd. Press Add to add it to the autoload list:

Maintenant, chaque fois que vous lancez n'importe laquelle de vos scènes, le script sera toujours chargé.

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.

extends Node

var current_scene = null

func _ready():
    var root = 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)

using Godot;

public partial class Global : Node
{
    public Node CurrentScene { get; set; }

    public override void _Ready()
    {
        Viewport root = GetTree().Root;
        // Using a negative index counts from the end, so this gets the last child node of `root`.
        CurrentScene = root.GetChild(-1);
    }
}

Il nous faut maintenant une fonction pour changer de scène. Cette fonction doit libérer la scène actuelle et la remplacer par la scène demandée.

func goto_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.
    var s = 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

public void GotoScene(string path)
{
    // This function will usually be called from a signal callback,
    // or some other function from 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:

    CallDeferred(MethodName.DeferredGotoScene, path);
}

public void DeferredGotoScene(string path)
{
    // It is now safe to remove the current scene.
    CurrentScene.Free();

    // Load a new scene.
    var nextScene = GD.Load<PackedScene>(path);

    // Instance the new scene.
    CurrentScene = nextScene.Instantiate();

    // Add it to the active scene, as child of root.
    GetTree().Root.AddChild(CurrentScene);

    // Optionally, to make it compatible with the SceneTree.change_scene_to_file() API.
    GetTree().CurrentScene = CurrentScene;
}

Avec Object.call_deferred (), la deuxième fonction ne sera exécutée que lorsque tout le code de la scène actuelle sera terminé. Ainsi, la scène en cours ne sera pas supprimée tant qu’elle est encore utilisée (c’est-à-dire que son code est toujours en cours d’exécution).

Enfin, nous devons remplir les fonctions de rappel vides dans les deux scènes :

# Add to 'scene_1.gd'.

func _on_button_pressed():
    Global.goto_scene("res://scene_2.tscn")

// Add to 'Scene1.cs'.

private void OnButtonPressed()
{
    var global = GetNode<Global>("/root/Global");
    global.GotoScene("res://Scene2.tscn");
}

et

# Add to 'scene_2.gd'.

func _on_button_pressed():
    Global.goto_scene("res://scene_1.tscn")

// Add to 'Scene2.cs'.

private void OnButtonPressed()
{
    var global = GetNode<Global>("/root/Global");
    global.GotoScene("res://Scene1.tscn");
}

Maintenant, si vous lancez le projet, vous pouvez basculer entre les deux scènes en appuyant sur le bouton.

Note

Lorsque les scènes sont petites, la transition est instantanée. Cependant, si vos scènes sont plus complexes, leur affichage peut prendre un certain temps. Pour apprendre à gérer cela, consultez le tutoriel suivant : Chargement en arrière-plan.

Alternativement, si le temps de chargement est relativement court (moins de 3 secondes environ), vous pouvez afficher une "plaque de chargement" en montrant une sorte d'élément 2D juste avant de changer de scène. Vous pouvez ensuite la cacher juste après le changement de scène. Cela peut être utilisé pour indiquer au joueur qu'une scène est en cours de chargement.