Singletons (Carregamento Automático)

Introdução

O sistema de cenas de Godot, embora poderoso e flexível, tem uma desvantagem: não existe um método para armazenar informações (por exemplo, pontuação ou inventário de um jogador) que seja necessário em mais de uma cena.

É possível resolver isso com algumas soluções alternativas, mas elas vêm com suas próprias limitações:

  • Embora seja possível que uma cena carregue e descarregue outras cenas como seus filhos para armazenar informações comuns a essas cenas filhas, não será mais possível executar essas cenas sozinhas e esperar que elas funcionem corretamente.

  • Embora a informação possa ser armazenada no disco em ``user: // `` e esta informação possa ser carregada por cenas que a exijam, salvar e carregar continuamente esses dados ao alterar cenas é trabalhoso e pode ser lento.

O padrão Singleton é uma ferramenta útil para se usar quando é necessário armazenar informações entre cenas. No nosso caso é possível reusar a mesma cena ou classe para múltiplos singletons, contanto que eles tenham diferentes nomes.

Usando esse conceito, você pode criar objetos que:

  • São sempre carregados, independentemente da cena em execução.

  • Pode armazenar variáveis globais, como informações do jogador.

  • Pode lidar com troca de cenas e transições entre cenas.

  • Atua como um singleton, já que o GDScript não suporta variáveis globais por projeto.

Carregamento automático de nós e scripts atendem a essa necessidade.

Nota

Godot não tornará AutoLoad um singleton "true" de acordo com o design pattern. Ele ainda pode ser instanciado mais de uma vez pelo usuário, se desejado.

AutoLoad

Você pode criar um Autoload para carregar a cena ou um script que herda Node.

Nota

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

Aqui você pode adicionar qualquer número de cenas ou scripts. Cada entrada na lista requer um nome, designada como a propriedade nome do nó. A ordem em que as entradas são adicionadas à árvore da cena global pode ser manipulada usando as setas para cima e para baixo.

../../_images/autoload_example.png

Isso significa que qualquer nó pode acessar um singleton chamado "PlayerVariables" com:

var player_vars = get_node("/root/PlayerVariables")
player_vars.health -= 10
var playerVariables = GetNode<PlayerVariables>("/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;

Note que objetos carregados automaticamente (scripts e/ou cenas) são acessadas como qualquer outro nó na árvore de cenas. Se você olhar numa cena executando, você verá os nós carregados automaticamente aparecerem:

../../_images/autoload_runtime.png

Comutador de cena personalizado

This tutorial will demonstrate building a scene switcher using autoloads. For basic scene switching, you can use the SceneTree.change_scene() method (see Using SceneTree for details). However, if you need more complex behavior when changing scenes, this method provides more functionality.

Primeiro faça o download do modelo aqui: autoload.zip e abra-o com Godot.

O projeto contém duas cenas: Scene1.tscn e Scene2.tscn. Cada cena contém um Label exibindo o nome da cena e um botão com seu sinal pressed() conectado. Quando você executar o projeto, ele começará em Scene1.tscn. No entanto, ao pressionar o botão, nada acontecerá.

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

Agora, todas as vezes que você executar qualquer uma das suas cenas, o script sempre será carregado.

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);
    }
}

Em seguida vem a função para trocar de cena. Esta função libera a cena atual e a substitui pela cena requisitada.

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);
}

Usando Object.call_deferred(), a segunda função irá somente rodar uma vez que todo o código dessa cena has completed. Thus, the current scene will not be removed while it is still being used (i.e. its code is still running).

Finalmente, tudo que resta é completar as funções vazias nas duas cenas:

# Add to 'Scene1.gd'.

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

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

e

# Add to 'Scene2.gd'.

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

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

Rode o projeto e veja se você consegue trocar de cena apertando o botão.

Nota

Quando as cenas são pequenas, a transição é instantânea. No entanto, se suas cenas forem mais complexas, elas podem demorar um pouco para aparecer. Para aprender como lidar com isso, veja o próximo tutorial: Carregamento em segundo plano.

Alternativamente, se o tempo de carregamento é relativamente curto (menos que 3 segundos ou por aí), você pode exibir uma "placa de carregamento" mostrando algum tipo de elemento 2D logo antes de trocar a cena. Você pode, então, escondê-lo logo após a cena ser trocada. Isto pode ser usado para indicar ao jogador que uma cena está sendo carregada.