Singletons (Chargement Automatique)

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.

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.

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

  • 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.

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.

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.

../../_images/singleton.png

To autoload a scene or script, select Project > Project Settings from the menu and switch to the AutoLoad tab.

../../_images/autoload_tab.png

Ici, vous pouvez ajouter un nombre illimité de scènes ou de scripts. Chaque entrée de la liste nécessite un nom, qui est assigné comme propriété name du nœud. L'ordre des entrées telles qu'elles sont ajoutées à l'arborescence de scène globale peut être manipulé à l'aide des touches fléchées haut/bas.

../../_images/autoload_example.png

Cela veut dire que n'importe quel nœud peut accéder à un singleton appelé "PlayerVariables" avec :

var player_vars = get_node("/root/PlayerVariables")
player_vars.health -= 10
var playerVariables = (PlayerVariables)GetNode("/root/PlayerVariables");
playerVariables.Health -= 10; // Instance field.

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

PlayerVariables.health -= 10
// Static members can be accessed by using the class name.
PlayerVariables.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 :

../../_images/autoload_runtime.png

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() method (see L'arbre de scène for details). However, if you need more complex behavior when changing scenes, this method provides more functionality.

D'abord télécharger le modèle à partir d'ici : autoload.zip , ensuite, ouvrez le dans Godot.

Le projet contient deux scènes : Scene1.tscn et Scene2.tscn. Chaque scène contient une étiquette(label) affichant le nom de la scène et un bouton avec son signal pressed() connecté. Quand vous exécutez le projet, il démarre à Scene1.tscn. Cependant, appuyer sur le bouton ne fait rien.

Global.gd

Switch to the Script tab and create a new script called Global.gd. Make sure it inherits from Node:

../../_images/autoload_script.png

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 browse button or typing its path: res://Global.gd. Press Add to add it to the autoload list:

../../_images/autoload_tutorial1.png

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().get_root()
    current_scene = root.get_child(root.get_child_count() - 1)
using Godot;
using System;

public class Global : Godot.Node
{
    public Node CurrentScene { get; set; }

    public override void _Ready()
    {
        Viewport root = GetTree().GetRoot();
        CurrentScene = root.GetChild(root.GetChildCount() - 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:

    call_deferred("_deferred_goto_scene", 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.instance()

    # Add it to the active scene, as child of root.
    get_tree().get_root().add_child(current_scene)

    # Optionally, to make it compatible with the SceneTree.change_scene() API.
    get_tree().set_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(nameof(DeferredGotoScene), path);
}

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

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

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

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

    // Optionally, to make it compatible with the SceneTree.change_scene() API.
    GetTree().SetCurrentScene(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 'Scene1.gd'.

func _on_Button_pressed():
    Global.goto_scene("res://Scene2.tscn")
// Add to 'Scene1.cs'.

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

et

# Add to 'Scene2.gd'.

func _on_Button_pressed():
    Global.goto_scene("res://Scene1.tscn")
// Add to 'Scene2.cs'.

public void OnButtonPressed()
{
    var global = (Global)GetNode("/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

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: Chargement en arrière-plan.

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 before changing the scene. You can then hide it just after the scene is changed. This can be used to indicate to the player that a scene is being loaded.