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

Autoloads versus nós normais

A Godot oferece um recurso para carregar nós automaticamente na raiz do seu projeto, permitindo que você os acesse globalmente, o que pode cumprir o papel de um Singleton: Singletons (Autoload). Esses nós carregados automaticamente não são liberados quando você altera a cena por código com SceneTree.change_scene_to_file.

Neste guia, você aprenderá quando usar a funcionalidade Autoload e as técnicas que você pode usar para evitá-lo.

O problema do corte de áudio

Outros motores podem encorajar o uso da criação de classes de gerenciador, singletons que organizam muita funcionalidade em um objeto globalmente acessível. O Godot oferece muitas maneiras de evitar o estado global graças à árvore de nós e aos sinais.

Por exemplo, digamos que estamos construindo um jogo de plataforma e queremos coletar moedas que reproduzam um efeito sonoro. Há um nó para isso: o AudioStreamPlayer. Mas se chamarmos o AudioStreamPlayer enquanto ele já está tocando um som, o novo som interrompe o primeiro.

Uma solução é programar uma classe gerenciadora global de sons carregada automaticamente (autoload). Ela gera um pool de nós AudioStreamPlayer que são reutilizados conforme novas solicitações de efeitos sonoros chegam. Supondo que essa classe se chame Sound, você pode utilizá-la em qualquer lugar do projeto chamando Sound.play("coin_pickup.ogg"). Isso resolve o problema no curto prazo, mas cria outros problemas:

  1. Estado global: um objeto agora é responsável pelos dados de todos os objetos. Se a classe Sound tem erros ou não tem um AudioStreamPlayer disponível, todos os nós que o chamam podem quebrar.

  2. Acesso global: agora que qualquer objeto pode chamar Sound.play(sound_path) de qualquer lugar, não há mais uma maneira fácil de encontrar a origem de um bug.

  3. Alocação global de recursos*: com um conjunto de nós AudioStreamPlayer armazenados desde o início, você pode ou ter muito poucos e enfrentar bugs, ou muitos e utilizar mais memória do que você precisa.

Nota

Sobre o acesso global, o problema é que qualquer código em qualquer lugar pode enviar dados incorretos para o autoload Sound do nosso exemplo. Como resultado, a área de investigação para corrigir um erro passa a abranger o projeto inteiro.

Quando você mantém o código dentro de uma cena, apenas um ou dois scripts podem estar envolvidos no áudio.

Contraste isto com cada cena mantendo tantos nós AudioStreamPlayer quantos forem necessários dentro de si e todos estes problemas desaparecem:

  1. Cada cena gerencia suas próprias informações de estado. Se houver um problema com os dados, isso causará problemas apenas naquela cena.

  2. Cada cena acessa apenas seus próprios nós. Agora, se houver um bug, é fácil descobrir qual nó é o culpado.

  3. Cada cena aloca exatamente a quantidade de recursos de que precisa.

Gestão de funcionalidades ou dados compartilhados

Outra razão para usar um Autoload pode ser que você queira reutilizar o mesmo método ou dados em muitas cenas.

No caso de funções, você pode criar um novo tipo de Node que fornece esse recurso para uma cena individual usando a palavra-chave class_name no GDScript.

Quando se trata de dados, você pode:

  1. Cria um novo tipo de Resource para compartilhar os dados.

  2. Armazenar os dados em um objeto ao qual cada nó tem acesso, por exemplo utilizando a propriedade owner para acessar o nó raiz da cena.

Quando você deve usar um Autoload

GDScript suporta a criação de funções static usando static func`. Quando combinado com class_name, isso torna possível criar bibliotecas de funções auxiliares sem ter que criar uma instância para chamá-los. A limitação de funções estáticas é que elas não podem referenciar variáveis de membros, funções não estáticas ou self.

Desde o Godot 4.1, o GDScript também suporta variáveis static usando static var. Isso significa que agora é possível compartilhar variáveis entre instâncias de uma classe sem precisar criar um autoload separado.

Ainda assim, nós carregados automaticamente podem simplificar o código de sistemas com escopo amplo. Se o autoload gerencia suas próprias informações sem invadir os dados de outros objetos, então ele é uma excelente forma de criar sistemas responsáveis por tarefas de grande abrangência. Por exemplo, um sistema de missões ou diálogos.

Nota

Um autoload não é necessariamente um singleton. Nada impede você de instanciar cópias de um nó carregado automaticamente. Um autoload é apenas uma ferramenta que faz com que um nó seja carregado automaticamente como um filho da raiz da sua árvore de cenas, independentemente da estrutura de nós do seu jogo ou de qual cena você execute, por exemplo, pressionando a tecla F6.

Como resultado, você pode obter o nó carregado automaticamente, por exemplo um autoload chamado Sound, chamando get_node("/root/Sound").