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

Instâncias de nós e cenas

Este guia explica como obter nós, criar nós, adicioná-los como filhos e instanciar cenas a partir do código.

Ver também

Check the Criando instâncias tutorial to learn about Godot's approach to scene instantiation.

Obtendo nós

Você pode obter uma referência para um nó chamando o método Node.get_node(). Para que isso funcione, o nó filho deve estar presente na árvore de cena. Obtê-lo na função _ready() do nó pai garante isso.

If, for example, you have a scene tree like this, and you want to get a reference to the Sprite2D and Camera2D nodes to access them in your script.

../../_images/nodes_and_scene_instances_player_scene_example.webp

Para isso, você pode usar o seguinte código.

var sprite2d
var camera2d

func _ready():
    sprite2d = get_node("Sprite2D")
    camera2d = get_node("Camera2D")

private Sprite2D _sprite2D;
private Camera2D _camera2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = GetNode<Sprite2D>("Sprite2D");
    _camera2D = GetNode<Camera2D>("Camera2D");
}

Observe que você obtém os nós usando seus nomes, não seus tipos. Acima, "Sprite2D" e "Camera2D" são os nomes dos nós na cena.

Se você renomear o nó Sprite2D para Skin na doca Scene, você terá que alterar a linha que obtém o nó para get_node("Skin") no script.

Caminhos dos nós

Ao obter uma referência para um nó, você não está limitado a obter um filho direto. A função get_node() suporta caminhos, um pouco como quando se trabalha com um navegador de arquivos. Adicione uma barra para separar os nós.

Considere o seguinte exemplo de cena, com o script anexado ao nó UserInterface.

../../_images/nodes_and_scene_instances_ui_scene_example.webp

Para obter o nó AnimationPlayer, você usaria o seguinte código.

var animation_player

func _ready():
    animation_player = get_node("ShieldBar/AnimationPlayer")

private AnimationPlayer _animationPlayer;

public override void _Ready()
{
    base._Ready();

    _animationPlayer = GetNode<AnimationPlayer>("ShieldBar/AnimationPlayer");
}

Nota

Assim como com caminhos de arquivo, você pode usar ".." para obter um nó pai. A melhor prática, no entanto, é evitar fazer isso para não quebrar o encapsulamento. Você também pode iniciar o caminho com uma barra direta para torná-lo absoluto, caso em que o nó no topo seria "/root", a viewport raiz predefinida do aplicativo.

Açúcar sintático

Você pode usar dois atalhos para encurtar seu código no GDScript. Primeiramente, colocar a anotação @onready antes de uma variável de membro faz com que ela seja inicializada logo antes do callback _ready().

@onready var sprite2d = get_node("Sprite2D")

Também existe uma notação curta para get_node(): o cifrão, "$". Você o coloca antes do nome ou caminho do nó que deseja obter.

@onready var sprite2d = $Sprite2D
@onready var animation_player = $ShieldBar/AnimationPlayer

Criando nós

Para criar um nó a partir do código, chame seu método new() como para qualquer outro tipo de dados baseado em classe.

Você pode armazenar a referência do nó recém-criado em uma variável e chamar add_child() para adicioná-lo como filho do nó ao qual você anexou o script.

var sprite2d

func _ready():
    sprite2d = Sprite2D.new() # Create a new Sprite2D.
    add_child(sprite2d) # Add it as a child of this node.

private Sprite2D _sprite2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = new Sprite2D(); // Create a new Sprite2D.
    AddChild(_sprite2D); // Add it as a child of this node.
}

Para deletar um nó e liberá-lo da memória, você pode chamar seu método queue_free(). Fazer isso coloca o nó na fila para exclusão ao final do quadro atual, após ele terminar de processar. Nesse ponto, a engine remove o nó da cena e libera o objeto na memória.

sprite2d.queue_free()

_sprite2D.QueueFree();

Antes de chamar sprite2d.queue_free(), a árvore de cena remota se parece com isso.

Depois que a engine liberou o nó, a árvore de cena remota não exibe mais o sprite.

You can alternatively call free() to immediately destroy the node. You should do this with care as any reference to it will instantly become invalid. We recommend using queue_free() unless you know what you're doing.

Quando você libera um nó, isso também libera todos os seus filhos. Graças a isso, para deletar um ramo inteiro da árvore de cena, basta liberar o nó pai mais ao topo.

Instantiating scenes

Scenes are templates from which you can create as many reproductions as you'd like. This operation is called instantiation, and doing it from code happens in two steps:

Carregando a cena da unidade local.
Criando uma instância do recurso carregado PackedScene.

var scene = load("res://my_scene.tscn")

var scene = GD.Load<PackedScene>("res://MyScene.tscn");

Pré-carregar a cena pode melhorar a experiência do usuário, pois a operação de carregamento ocorre quando o compilador lê o script e não em tempo de execução. Esse recurso está disponível apenas no GDScript.

var scene = preload("res://my_scene.tscn")

Nesse ponto, scene é um recurso de cena empacotada (packed scene), não um nó. Para criar o nó real, você precisa chamar PackedScene.instantiate(). Ele retorna uma árvore de nós que você pode usar como filho do seu nó atual.

var instance = scene.instantiate()
add_child(instance)

var instance = scene.Instantiate();
AddChild(instance);

The advantage of this two-step process is you can keep a packed scene loaded and create new instances on the fly. For example, to quickly instantiate several enemies or bullets.