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...
NodePath
Un percorso dell'albero di scene pre-interpretato.
Descrizione
Il tipo di Variant incorporato NodePath rappresenta un percorso verso un nodo o una proprietà in una gerarchia di nodi. È progettato per essere passato efficientemente a molti metodi integrati (come Node.get_node(), Object.set_indexed(), Tween.tween_property(), ecc.) senza una dipendenza rigida al nodo o alla proprietà a cui puntano.
Un percorso di nodo è rappresentato come una String composta da nomi di nodi separati da barra (/) e nomi di proprietà separati da due punti (:) (chiamati anche "sotto-nomi"). Simili a un percorso di file system, ".." e "." sono nomi di nodo speciali. Si riferiscono rispettivamente al nodo padre e al nodo attuale.
Gli esempi seguenti sono percorsi relativi al nodo attuale:
^"A" # Punta al figlio diretto A.
^"A/B" # Punta al figlio di A, B.
^"." # Punta al nodo attuale.
^".." # Punta al nodo genitore.
^"../C" # Punta al nodo fratello C.
^"../.." # Punta al nodo nonno.
Una barra iniziale indica che il percorso è assoluto e inizia dal SceneTree:
^"/root" # Punta al Window radice di SceneTree.
^"/root/Title" # Può puntare al nodo radice della scena principale denominato "Title".
^"/root/Global" # Può puntare a un nodo o a una scena autoload denominata "Global".
Nonostante il loro nome, i percorsi dei nodi possono anche puntare a una proprietà:
^":position" # Punta alla posizione di questo oggetto.
^":position:x" # Punta alla posizione di questo oggetto sull'asse x.
^"Camera3D:rotation:y" # Punta alla Camera3D figlia e alla sua rotazione y.
^"/root:size:x" # Punta alla Window radice e alla sua larghezza.
In alcune situazioni, è possibile omettere il : iniziale quando si punta alla proprietà di un oggetto. Ad esempio, questo è il caso di Object.set_indexed() e Tween.tween_property(), poiché tali metodi chiamano get_as_property_path() internamente. Tuttavia, in genere si consiglia di mantenere il prefisso :.
I percorsi dei nodi non possono verificare se sono validi e possono puntare a nodi o proprietà inesistenti. Il loro significato dipende interamente dal contesto in cui vengono utilizzati.
Di solito non devi preoccuparti del tipo NodePath, poiché le stringhe vengono automaticamente convertite in questo tipo quando necessario. Ci sono comunque momenti in cui definire i percorsi dei nodi è utile. Ad esempio, le proprietà NodePath esportate ti consentono di selezionare facilmente qualsiasi nodo all'interno della scena attualmente modificata. Sono inoltre aggiornate automaticamente quando sposti, rinomini o elimini nodi nell'editor dell'albero di scene. Vedi anche @GDScript.@export_node_path.
Vedi anche StringName, che è un tipo simile progettato per stringhe ottimizzate.
Nota: In un contesto booleano, un NodePath sarà valutato come false se è vuoto (NodePath("")). Altrimenti, un NodePath sarà sempre valutato come true.
Nota
Ci sono differenze sostanziali quando si usa questa API con C#. Vedi Differenze dell'API C# rispetto a GDScript per maggiori informazioni.
Tutorial
Costruttori
NodePath() |
|
Metodi
get_as_property_path() const |
|
get_concatenated_names() const |
|
get_concatenated_subnames() const |
|
get_name_count() const |
|
get_subname(idx: int) const |
|
get_subname_count() const |
|
hash() const |
|
is_absolute() const |
|
is_empty() const |
|
Operatori
operator !=(right: NodePath) |
|
operator ==(right: NodePath) |
Descrizioni dei costruttori
Costruisce un NodePath vuoto.
NodePath NodePath(from: NodePath)
Costruisce un NodePath come copia del NodePath specificato.
NodePath NodePath(from: String)
Costruisce un NodePath da una String. Il percorso creato è assoluto se preceduto da una barra (vedi is_absolute()).
I "sotto-nomi" facoltativamente inclusi dopo il percorso al nodo di destinazione possono puntare a proprietà e possono anche essere annidati.
Le seguenti stringe possono essere percorsi di nodi validi:
# Punta al nodo Sprite2D.
"Level/RigidBody2D/Sprite2D"
# Punta al nodo Sprite2D e alla sua risorsa "texture".
# get_node() recupererebbe Sprite2D, mentre get_node_and_resource()
# recupererebbe sia il nodo Sprite2D sia la risorsa "texture".
"Level/RigidBody2D/Sprite2D:texture"
# Punta al nodo Sprite2D e alla sua proprietà "position".
"Level/RigidBody2D/Sprite2D:position"
# Punta al nodo Sprite2D e al componente "x" della sua proprietà "position".
"Level/RigidBody2D/Sprite2D:position:x"
# Punta al nodo RigidBody2D come percorso assoluto che parte dal SceneTree.
"/root/Level/RigidBody2D"
Nota: In GDScript, è anche possibile convertire una stringa costante in un percorso di nodo prefissandola con ^. ^"path/to/node" equivale a NodePath("path/to/node").
Descrizioni dei metodi
NodePath get_as_property_path() const 🔗
Restituisce una copia di questo percorso del nodo con un carattere due punti (:) come prefisso, trasformandolo in un percorso di proprietà puro senza nomi di nodo (relativo al nodo attuale).
# node_path punta alla proprietà "x" del nodo figlio denominato "position".
var node_path = ^"position:x"
# property_path punta alla "position" nell'asse "x" di questo nodo.
var property_path = node_path.get_as_property_path()
print(property_path) # Stampa ":position:x"
// node_path punta alla proprietà "x" del nodo figlio denominato "position".
var nodePath = new NodePath("position:x");
// property_path punta alla "position" nell'asse "x" di questo nodo.
NodePath propertyPath = nodePath.GetAsPropertyPath();
GD.Print(propertyPath); // Stampa ":position:x"
StringName get_concatenated_names() const 🔗
Restituisce tutti i nomi dei nodi concatenati con un carattere barra (/) come un singolo StringName.
StringName get_concatenated_subnames() const 🔗
Restituisce tutti i sotto-nomi di proprietà concatenati con un carattere due punti (:) come un singolo StringName.
var node_path = ^"Sprite2D:texture:resource_name"
print(node_path.get_concatenated_subnames()) # Stampa "texture:resource_name"
var nodePath = new NodePath("Sprite2D:texture:resource_name");
GD.Print(nodePath.GetConcatenatedSubnames()); // Stampa "texture:resource_name"
StringName get_name(idx: int) const 🔗
Restituisce il nome del nodo indicato dall'indice idx, a partire da 0. Se idx è fuori dai limiti, viene generato un errore. Vedi anche get_subname_count() e get_name_count().
var sprite_path = NodePath("../RigidBody2D/Sprite2D")
print(sprite_path.get_name(0)) # Stampa ".."
print(sprite_path.get_name(1)) # Stampa "RigidBody2D"
print(sprite_path.get_name(2)) # Stampa "Sprite"
var spritePath = new NodePath("../RigidBody2D/Sprite2D");
GD.Print(spritePath.GetName(0)); // Stampa ".."
GD.Print(spritePath.GetName(1)); // Stampa "PathFollow2D"
GD.Print(spritePath.GetName(2)); // Stampa "Sprite"
Restituisce il numero di nomi di nodi nel percorso. I sotto-nomi delle proprietà non sono inclusi.
Ad esempio, "../RigidBody2D/Sprite2D:texture" contiene 3 nomi di nodi.
StringName get_subname(idx: int) const 🔗
Restituisce il nome di proprietà indicato dall'indice idx, a partire da 0. Se idx è fuori dai limiti, viene generato un errore. Vedi anche get_subname_count().
var path_to_name = NodePath("Sprite2D:texture:resource_name")
print(path_to_name.get_subname(0)) # Stampa "texture"
print(path_to_name.get_subname(1)) # Stampa "resource_name"
var pathToName = new NodePath("Sprite2D:texture:resource_name");
GD.Print(pathToName.GetSubname(0)); // Stampa "texture"
GD.Print(pathToName.GetSubname(1)); // Stampa "resource_name"
int get_subname_count() const 🔗
Restituisce il numero di nomi di proprietà ("sotto-nomi") nel percorso. Ogni sottonome nel percorso del nodo è elencato dopo un carattere due punti (:).
Ad esempio, "Level/RigidBody2D/Sprite2D:texture:resource_name" contiene 2 sottonomi.
Restituisce il valore di hash a 32 bit che rappresenta il contenuto del percorso di nodo.
Nota: I percorsi di nodo con valori uguali di hash non sono garantiti che siano gli stessi, a causa delle collisioni di hash. I percorsi di nodo con valori diversi di hash sono sicuramente diversi.
Restituisce true se il percorso del nodo è assoluto. A differenza di un percorso relativo, un percorso assoluto è rappresentato da un carattere barra iniziale (/) e parte sempre dal SceneTree. Può essere utilizzato per accedere in modo affidabile ai nodi dal nodo radice (ad esempio "/root/Global" se esiste un autoload denominato "Global").
Restituisce true se il percorso di nodo è stato costruito da una stringa vuota ("").
NodePath slice(begin: int, end: int = 2147483647) const 🔗
Restituisce la porzione del NodePath, da begin (incluso) a end (escluso), come un nuovo NodePath.
Il valore assoluto di begin e end sarà limitato alla somma di get_name_count() e get_subname_count(), quindi il valore predefinito per end lo fa suddividere fino alla fine di NodePath per impostazione predefinita (ad esempio, path.slice(1) è un'abbreviazione di path.slice(1, path.get_name_count() + path.get_subname_count())).
Se begin o end sono negativi, saranno relativi alla fine del NodePath (ad esempio, path.slice(0, -2) è un'abbreviazione di path.slice(0, path.get_name_count() + path.get_subname_count() - 2)).
Descrizioni degli operatori
bool operator !=(right: NodePath) 🔗
Restituisce true se due percorsi di nodo non sono uguali.
bool operator ==(right: NodePath) 🔗
Restituisce true se due percorsi di nodo sono uguali, cioè sono composti dagli stessi nodi e sotto-nomi nello stesso ordine.