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

Using get_node() to reference nodes from a script can sometimes be fragile. If you move a button in a UI scene from one panel to another, the button's node path changes, and if a script uses get_node() with a hard-coded node path, the script will not be able to find the button anymore.

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.

../../_images/unique_name.webp

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

../../_images/percent.webp

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

You can now use the node in your script. For example, you can reference it with a get_node() method call by typing the % symbol, followed by the node's name:

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

Limite della stessa scena

A scene unique node can only be retrieved by a node inside the same scene. To demonstrate this limitation, consider this example Player scene that instances a Sword scene:

../../_images/unique_name_scene_instance_example.webp

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