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

Nodi e istanze di scene

Questa guida spiega come ottenere nodi, creare nodi, aggiungerli come figli e istanziare scene da codice.

Vedi anche

Consulta il tutorial Creazione di istanze per saperne di più sull'approccio di Godot all'istanziazione delle scene.

Ottenere nodi

È possibile ottenere un riferimento a un nodo chiamando il metodo Node.get_node(). Affinché ciò funzioni, il nodo figlio deve essere presente nell'albero di scene. Ottenere il riferimento nella funzione _ready() del nodo padre garantisce questo.

Ad esempio, se hai un albero di scene come questo e vuoi ottenere un riferimento ai nodi Sprite2D e Camera2D per accedervi nel proprio script.

../../_images/nodes_and_scene_instances_player_scene_example.webp

Per fare ciò, puoi utilizzare il seguente codice.

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

Nota che i nodi si ottengono tramite il loro nome, non il loro tipo. Sopra, "Sprite2D" e "Camera2D" sono i nomi dei nodi nella scena.

Se si rinomina il nodo Sprite2D come Skin nel pannello Scena, è necessario modificare la riga che ottiene il nodo in get_node("Skin") nello script.

Percorsi di nodo

Quando si ottiene un riferimento a un nodo, non ci si limita a ottenere un nodo figlio diretto. La funzione get_node() supporta i percorsi, un po' come quando si lavora con un file browser. Aggiungi una barra per separare i nodi.

Prendiamo la seguente scena di esempio, con lo script allegato al nodo UserInterface.

../../_images/nodes_and_scene_instances_ui_scene_example.webp

Per ottenere il nodo AnimationPlayer, useresti il seguente codice.

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

Come per i percorsi dei file, è possibile usare ".." per ottenere un nodo padre. La migliore pratica è però di evitare di farlo per non rompere l'incapsulamento. È anche possibile iniziare il percorso con una barra per renderlo assoluto, nel qual caso il nodo più in alto sarebbe "/root", la viewport radice predefinita dell'applicazione.

Zucchero sintattico

È possibile usare due scorciatoie per abbreviare il codice in GDScript. Innanzitutto, inserendo l'annotazione @onready prima di una variabile membro, questa è inizializzata subito prima del callback _ready().

@onready var sprite2d = get_node("Sprite2D")

Esiste anche una breve notazione per get_node(): il simbolo del dollaro, "$". Deve essere inserito prima del nome o del percorso del nodo che si desidera ottenere.

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

Creare nodi

Per creare un nodo tramite codice, chiama il suo metodo new() come per qualsiasi altro tipo di dati basato su una classe.

È possibile memorizzare il riferimento di un nodo appena creato in una variabile e chiamare add_child() per aggiungerlo come figlio del nodo a cui è stato allegato lo 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.
}

Per eliminare un nodo e liberarlo dalla memoria, è possibile chiamare il suo metodo queue_free(). In questo modo, il nodo viene messo in coda per essere eliminato alla fine del frame attuale, al termine della sua elaborazione. A quel punto, il motore rimuove il nodo dalla scena e libera l'oggetto in memoria.

sprite2d.queue_free()

_sprite2D.QueueFree();

Prima di chiamare sprite2d.queue_free(), l'albero di scene remoto appare così.

Dopo che il motore ha liberato il nodo, l'albero di scene remoto non mostra più lo sprite.

In alternativa, si può chiamare free() per distruggere immediatamente il nodo. Prendi precauzioni però, perché qualsiasi riferimento ad esso diventerà immediatamente null. Ti consigliamo di usare queue_free() a meno che tu non sappia cosa stai facendo.

Quando si libera un nodo, vengono liberati anche tutti i suoi figli. Grazie a questo, per eliminare un intero ramo dell'albero di scene, basta liberare solo il nodo padre più in alto.

Istanziare scene

Le scene sono modelli da cui è possibile creare tutte le riproduzioni desiderate. Questa operazione è detta "istanziazione" e, tramite codice, avviene in due fasi:

Caricare la scena dal disco locale.
Creazione di un'istanza della risorsa PackedScene caricata.

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

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

Precaricare la scena può migliorare l'esperienza dell'utente, poiché l'operazione di caricamento avviene quando il compilatore legge lo script e non durante l'esecuzione. Questa funzionalità è disponibile solo con GDScript.

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

A quel punto, scene è una risorsa scena impacchettata, non un nodo. Per creare il nodo effettivo, devi chiamare PackedScene.instantiate(). Restituisce un albero di nodi che puoi usare come figlio del tuo nodo attuale.

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

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

Il vantaggio di questo processo diviso in due parti è che si può mantenere la scena impacchettata caricata e creare istanze al volo. Ad esempio, per creare parecchi nemici o proiettili.