Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Singletons (Autoload)

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.
Informações podem ser armazenadas no disco em user:// e então carregadas por cenas que as necessitam, mas salvar e carregar dados frequentemente é 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 won't make an Autoload a "true" singleton as per the singleton design pattern. It may still be instantiated more than once by the user if desired.

Dica

Se você estiver criando um autoload como parte de um plugin do editor, considere registrá-lo automaticamente nas Configurações do Projeto quando o plugin for ativado.

Autoload

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

Nota

Ao fazer autoload de um script, um Node será criado e o script será anexado a ele. Este nó será adicionado à viewport raiz antes que qualquer outra cena seja carregada.

Para fazer autoload de uma cena ou script, comece pelo menu e navegue até Projeto > Configurações do Projeto > Globais > Autoload.

Aqui você pode adicionar qualquer número de cenas ou roteiros. Cada entrada na lista requer um nome, que é atribuído como propriedade do nó name. A ordem das entradas à medida que são adicionadas à árvore de cena global pode ser manipulada utilizando as teclas de seta para cima/baixo. Como nas cenas normais, o engine lerá estes nós em ordem de cima para baixo.

Se a coluna Habilitar estiver marcada (o que é o padrão), então o singleton pode ser acessado diretamente no GDScript:

PlayerVariables.health -= 10

A coluna Enable não tem efeito no código C#. No entanto, se o singleton for un script C#, um efeito semelhante pode ser alcançado incluindo uma propriedade estática chamada Instance e atribuindo-a em _Ready():

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

    public int Health { get; set; }

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

Isso permite que o singleton seja acessado a partir do código C# sem o GetNode() e sem um typecast:

PlayerVariables.Instance.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:

Aviso

Os Autoloads não devem ser removidos usando free() ou queue_free() em tempo de execução, caso contrário a engine irá travar.

Comutador de cena personalizado

Este tutorial demonstrará a construção de um alternador de cenas usando autoloads. Para alternância básica de cenas, você pode usar o método SceneTree.change_scene_to_file() (veja Usando Árvore de cena para detalhes). No entanto, se você precisar de um comportamento mais complexo ao trocar de cena, este método oferece mais funcionalidade.

Para começar, baixe o modelo aqui: singleton_autoload_starter.zip e abra-o no Godot.

Uma janela notificando que o projeto foi aberto pela última vez em uma versão anterior do Godot pode aparecer — isso não é um problema. Clique em Ok para abrir o projeto.

O projeto contém duas cenas: scene_1.tscn e scene_2.tscn. Cada cena contém um rótulo exibindo o nome da cena e um botão com seu sinal pressed() conectado. Quando você executa o projeto, ele inicia em scene_1.tscn. No entanto, pressionar o botão não faz nada.

Criando o script

Abra a janela Script e crie um novo script chamado global.gd. Certifique-se de que ele herde de Node:

O próximo passo é adicionar este script à lista de autoload. No menu, abra Projeto > Configurações do Projeto > Globais > Autoload e selecione o script clicando no botão de busca ou digitando seu caminho: res://global.gd. Pressione Adicionar para incluir na lista e nomeie-o como "Global”, o que é necessário para que outros scripts o acessem pelo nome "Global":

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

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:

    _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)

    # Instantiate 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);

    // Instantiate 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;
}

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

e

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

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.