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 univoci di scena

Introduzione

Usare get_node() per fare riferimento ai nodi da uno script può talvolta essere fragile. Se si sposta un pulsante in una scena dell'interfaccia utente da un pannello all'altro, il percorso di nodo del pulsante cambia e, se uno script usa get_node() con un percorso di nodo codificato, lo script non sarà più in grado di trovare il pulsante.

In situazioni come questa, il nodo può essere convertito in un nodo univoco di scena per evitare di dover aggiornare lo script ogni volta che il percorso del nodo viene modificato.

Creazione e utilizzo

Ci sono due modi per creare un nodo univoco di scena.

Nel pannello Scena, fai clic destro su un nodo e seleziona Accedi come nome univoco nel menu contestuale.

Dopo aver selezionato l'opzione, il nodo avrà un simbolo di percentuale (%) accanto al suo nome nell'albero di scene:

Puoi farlo anche mentre rinomini il nodo, aggiungendo "%" all'inizio del nome. Una volta confermato, il simbolo percentuale apparirà accanto al nome.

Ora puoi utilizzare il nodo nel tuo script. Ad esempio, puoi farvi riferimento con una chiamata al metodo get_node() inserendo il simbolo %, seguito dal nome del nodo:

GDScriptC#

get_node("%RedButton").text = "Hello"
%RedButton.text = "Hello" # Shorter syntax

Limite della stessa scena

È possibile recuperare un nodo univoco di scena soltanto da un nodo all'interno della stessa scena. Per dimostrare questa limitazione, considera questo l'esempio di una scena Player che istanzia una scena Sword:

Ecco i risultati delle chiamate a get_node() all'interno dello script Player:

• get_node("%Eyes") restituisce il nodo Eyes.

• get_node("%Hilt") restituisce null.

Questi sono i risultati delle chiamate a get_node() all'interno dello script Sword:

• get_node("%Eyes") restituisce null.

• get_node("%Hilt") restituisce il nodo Hilt.

Se uno script ha accesso a un nodo in un'altra scena, può chiamare get_node() su quel nodo per ottenere nodi univoci dalla scena di quel nodo. Questo funziona anche in un percorso di nodo, evitando più chiamate a get_node(). Ecco due modi per ottenere il nodo Hilt dallo script Player tramite nodi univoci:

• get_node("Hand/Sword").get_node("%Hilt") restituisce il nodo Hilt.

• get_node("Hand/Sword/%Hilt") restituisce egualmente il nodo Hilt.

I nomi univoci delle scene non funzionano solo alla fine di un percorso di nodi. Si possono usare anche al centro per navigare da un nodo all'altro. Ad esempio, il nodo Sword è segnato come nodo univoco nella scena Player, quindi il seguente è possibile:

• get_node("%Sword/%Hilt") restituisce il nodo Hilt.

Alternative

I nodi univoci delle scene sono uno strumento utile per navigare in una scena. Tuttavia, ci sono alcune situazioni in cui altre tecniche potrebbero essere migliori.

Un gruppo consente di individuare un nodo (o un gruppo di molti nodi) da qualsiasi altro nodo, a prescindere dalla scena in cui si trovano i due nodi.

Un singleton (autoload) è un nodo sempre caricato a cui è possibile accedere direttamente da qualsiasi nodo, a prescindere dalla scena. Sono utili quando alcuni dati o funzionalità sono condivisi globalmente.

Node.find_child() trova un nodo per nome senza conoscerne il percorso completo. Sembra simile a un nodo univoco, ma questo metodo è in grado di trovare nodi in scene annidate e non richiede in alcun modo di segnare il nodo nell'editor di scene. Tuttavia, questo metodo è lento. I nodi univoci delle scene sono memorizzati nella cache da Godot e sono veloci da recuperare, ma ogni volta che il metodo viene chiamato, find_child() deve verificare ogni discendente (ogni figlio, nipote e così via).