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
A pre-parsed scene tree path.
Descripción
El tipo Variant integrado NodePath representa una ruta a un nodo o propiedad en una jerarquía de nodos. Está diseñado para pasarse de manera eficiente a muchos métodos integrados (como Node.get_node(), Object.set_indexed(), Tween.tween_property(), etc.) sin una dependencia estricta del nodo o propiedad al que apuntan.
Una ruta de nodo se representa como una String compuesta por nombres de nodo separados por barras (/) y nombres de propiedad separados por dos puntos (:) (también llamados "subnombres"). De manera similar a una ruta de sistema de archivos, ".." y "." son nombres de nodo especiales. Hacen referencia al nodo superior y al nodo actual, respectivamente.
Los siguientes ejemplos son rutas relativas al nodo actual:
^"A" # Apunta al hijo directo A.
^"A/B" # Apunta al hijo B de A.
^"." # Apunta al nodo actual.
^".." # Apunta al nodo padre.
^"../C" # Apunta al nodo hermano C.
^"../.." # Apunta al nodo abuelo.
Una barra diagonal inicial significa que la ruta es absoluta y comienza desde SceneTree:
^"/root" # Apunta a la ventana raíz de SceneTree.
^"/root/Title" # Puede apuntar al nodo raíz de la escena principal llamado "Title".
^"/root/Global" # Puede apuntar a un nodo o escena cargados automáticamente llamados "Global".
A pesar de su nombre, las rutas de nodos también pueden apuntar a una propiedad:
^":position" # Apunta a la posición de este objeto.
^":position:x" # Apunta a la posición de este objeto en el eje x.
^"Camera3D:rotation:y" # Apunta a la cámara secundaria Camera3D y su rotación y.
^"/root:size:x" # Apunta a la ventana raíz y su ancho.
En algunas situaciones, es posible omitir el prefijo : inicial cuando se apunta a la propiedad de un objeto. Como ejemplo, este es el caso de Object.set_indexed() y Tween.tween_property(), ya que esos métodos llaman a get_as_property_path() en segundo plano. Sin embargo, generalmente se recomienda mantener el prefijo :.
Las rutas de nodos no pueden comprobar si son válidas y pueden apuntar a nodos o propiedades que no existen. Su significado depende completamente del contexto en el que se utilizan.
Normalmente no hay que preocuparse por el tipo NodePath, ya que las strings se convierten automáticamente al tipo cuando es necesario. Aún hay ocasiones en las que definir rutas de nodos es útil. Por ejemplo, las propiedades NodePath exportadas permiten seleccionar fácilmente cualquier nodo dentro de la escena que se está editando actualmente. También se actualizan automáticamente al mover, renombrar o eliminar nodos en el editor del árbol de escenas. Véase también @GDScript.@export_node_path.
Véase también StringName, que es un tipo similar diseñado para strings optimizadas.
Nota: En un contexto booleano, un NodePath se evaluará como false si está vacío (NodePath("")). De lo contrario, un NodePath siempre se evaluará como true.
Nota
Hay diferencias notables cuando usa esta API con C#. Véase Diferencias de la API de C# con GDScript para más información.
Tutoriales
Constructores
NodePath() |
|
Métodos
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 |
|
Operadores
operator !=(right: NodePath) |
|
operator ==(right: NodePath) |
Descripciones de Constructores
Construye un NodePath vacío.
NodePath NodePath(from: NodePath)
Construye un NodePath como copia del NodePath dado.
NodePath NodePath(from: String)
Construye un NodePath a partir de un String. La ruta creada es absoluta si comienza con una barra (consulta el is_absolute()).
Los "subnombres" opcionales que se incluyen después de la ruta apuntando al nodo objetivo pueden hacer referencia a propiedades, y también pueden estar anidados.
Las siguientes cadenas pueden ser rutas válidas de nodos:
# Apunta al nodo Sprite2D.
"Level/RigidBody2D/Sprite2D"
# Señala al nodo Sprite2D y a su recurso "texture".
# get_node() recuperaría el Sprite2D, mientras que get_node_and_resource()
# recuperaría tanto el nodo Sprite2D como el recurso "texture".
"Level/RigidBody2D/Sprite2D:texture"
# Apunta al nodo Sprite2D y a su propiedad "position".
"Level/RigidBody2D/Sprite2D:position"
# Señala al nodo Sprite2D y al componente "x" de su propiedad "position".
"Level/RigidBody2D/Sprite2D:position:x"
# Apunta al nodo RigidBody2D como una ruta absoluta comenzando desde el SceneTree.
"/root/Level/RigidBody2D"
Nota: En GDScript, también es posible convertir una cadena constante en una ruta de nodo anteponiéndole ^. ^"path/to/node" es equivalente a NodePath("path/to/node").
Descripciones de Métodos
NodePath get_as_property_path() const 🔗
Returns a copy of this node path with a colon character (:) prefixed, transforming it to a pure property path with no node names (relative to the current node).
# node_path points to the "x" property of the child node named "position".
var node_path = ^"position:x"
# property_path points to the "position" in the "x" axis of this node.
var property_path = node_path.get_as_property_path()
print(property_path) # Prints ":position:x"
// nodePath points to the "x" property of the child node named "position".
var nodePath = new NodePath("position:x");
// propertyPath points to the "position" in the "x" axis of this node.
NodePath propertyPath = nodePath.GetAsPropertyPath();
GD.Print(propertyPath); // Prints ":position:x"
StringName get_concatenated_names() const 🔗
Devuelve todos los nombres de nodo concatenados con una barra inclinada (/) como un solo StringName.
StringName get_concatenated_subnames() const 🔗
Returns all property subnames concatenated with a colon character (:) as a single StringName.
var node_path = ^"Sprite2D:texture:resource_name"
print(node_path.get_concatenated_subnames()) # Prints "texture:resource_name"
var nodePath = new NodePath("Sprite2D:texture:resource_name");
GD.Print(nodePath.GetConcatenatedSubnames()); // Prints "texture:resource_name"
StringName get_name(idx: int) const 🔗
Returns the node name indicated by idx, starting from 0. If idx is out of bounds, an error is generated. See also get_subname_count() and get_name_count().
var sprite_path = NodePath("../RigidBody2D/Sprite2D")
print(sprite_path.get_name(0)) # Prints ".."
print(sprite_path.get_name(1)) # Prints "RigidBody2D"
print(sprite_path.get_name(2)) # Prints "Sprite"
var spritePath = new NodePath("../RigidBody2D/Sprite2D");
GD.Print(spritePath.GetName(0)); // Prints ".."
GD.Print(spritePath.GetName(1)); // Prints "PathFollow2D"
GD.Print(spritePath.GetName(2)); // Prints "Sprite"
Returns the number of node names in the path. Property subnames are not included.
For example, "../RigidBody2D/Sprite2D:texture" contains 3 node names.
StringName get_subname(idx: int) const 🔗
Returns the property name indicated by idx, starting from 0. If idx is out of bounds, an error is generated. See also get_subname_count().
var path_to_name = NodePath("Sprite2D:texture:resource_name")
print(path_to_name.get_subname(0)) # Prints "texture"
print(path_to_name.get_subname(1)) # Prints "resource_name"
var pathToName = new NodePath("Sprite2D:texture:resource_name");
GD.Print(pathToName.GetSubname(0)); // Prints "texture"
GD.Print(pathToName.GetSubname(1)); // Prints "resource_name"
int get_subname_count() const 🔗
Devuelve el número de nombres de propiedades ("subnombres") en la ruta. Cada subnombre en la ruta del nodo se lista después de un carácter de dos puntos (:).
Por ejemplo, "Level/RigidBody2D/Sprite2D:texture:resource_name" contiene 2 subnombres.
Devuelve el valor hash de 32 bits que representa el contenido de la ruta del nodo.
Nota: Las rutas de nodo con valores hash iguales no garantizan ser las mismas, como resultado de colisiones de hash. Las rutas de nodo con valores hash diferentes garantizan ser diferentes.
Devuelve true si la ruta del nodo es absoluta. A diferencia de una ruta relativa, una ruta absoluta se representa con un carácter de barra inicial (/) y siempre comienza desde el SceneTree. Se puede utilizar para acceder de forma fiable a los nodos desde el nodo raíz (por ejemplo, "/root/Global" si existe una autocarga llamada "Global").
Devuelve true si la ruta del nodo ha sido construida a partir de una String vacía ("").
NodePath slice(begin: int, end: int = 2147483647) const 🔗
Devuelve una porción de la NodePath, desde begin (inclusive) hasta end (exclusive), como una nueva NodePath.
El valor absoluto de begin y end se ajustará a la suma de get_name_count() y get_subname_count(), por lo que el valor predeterminado de end hace que la porción vaya hasta el final de la NodePath por defecto (es decir, path.slice(1) es una abreviatura de path.slice(1, path.get_name_count() + path.get_subname_count())).
Si begin o end son negativos, serán relativos al final de la NodePath (es decir, path.slice(0, -2) es una abreviatura de path.slice(0, path.get_name_count() + path.get_subname_count() - 2)).
Descripciones de Operadores
bool operator !=(right: NodePath) 🔗
Devuelve true si dos rutas de nodo no son iguales.
bool operator ==(right: NodePath) 🔗
Devuelve true si dos rutas de nodo son iguales, es decir, si están compuestas por los mismos nombres de nodo y subnombres en el mismo orden.