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.
Description
The NodePath built-in Variant type represents a path to a node or property in a hierarchy of nodes. It is designed to be efficiently passed into many built-in methods (such as Node.get_node(), Object.set_indexed(), Tween.tween_property(), etc.) without a hard dependence on the node or property they point to.
A node path is represented as a String composed of slash-separated (/) node names and colon-separated (:) property names (also called "subnames"). Similar to a filesystem path, ".." and "." are special node names. They refer to the parent node and the current node, respectively.
The following examples are paths relative to the current node:
^"A" # Points to the direct child A.
^"A/B" # Points to A's child B.
^"." # Points to the current node.
^".." # Points to the parent node.
^"../C" # Points to the sibling node C.
^"../.." # Points to the grandparent node.
A leading slash means the path is absolute, and begins from the SceneTree:
^"/root" # Points to the SceneTree's root Window.
^"/root/Title" # May point to the main scene's root node named "Title".
^"/root/Global" # May point to an autoloaded node or scene named "Global".
Despite their name, node paths may also point to a property:
^":position" # Points to this object's position.
^":position:x" # Points to this object's position in the x axis.
^"Camera3D:rotation:y" # Points to the child Camera3D and its y rotation.
^"/root:size:x" # Points to the root Window and its width.
In some situations, it's possible to omit the leading : when pointing to an object's property. As an example, this is the case with Object.set_indexed() and Tween.tween_property(), as those methods call get_as_property_path() under the hood. However, it's generally recommended to keep the : prefix.
Node paths cannot check whether they are valid and may point to nodes or properties that do not exist. Their meaning depends entirely on the context in which they're used.
You usually do not have to worry about the NodePath type, as strings are automatically converted to the type when necessary. There are still times when defining node paths is useful. For example, exported NodePath properties allow you to easily select any node within the currently edited scene. They are also automatically updated when moving, renaming or deleting nodes in the scene tree editor. See also @GDScript.@export_node_path.
See also StringName, which is a similar type designed for optimized strings.
Note: In a boolean context, a NodePath will evaluate to false if it is empty (NodePath("")). Otherwise, a NodePath will always evaluate to true.
Note
Il y a des différences notables dans l'utilisation de cette API en C#. Voir Différences de l'API C# par rapport à GDScript pour plus d'informations.
Tutoriels
Constructeurs
NodePath() |
|
Méthodes
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 |
|
Opérateurs
operator !=(right: NodePath) |
|
operator ==(right: NodePath) |
Descriptions des constructeurs
Construit un NodePath vide.
NodePath NodePath(from: NodePath)
Construit un NodePath en tant que copie du NodePath donné.
NodePath NodePath(from: String)
Construit un NodePath depuis une chaîne de caractères String. Le chemin créé est absolu s'il commence par une barre oblique ("/") (voir is_absolute()).
Les "sous-noms" facultatifs inclus après le chemin du nœud cible peuvent pointer vers une ressource ou une propriété, et peuvent aussi être imbriqués.
Les chaînes suivantes peuvent êtres des chemins de nœud valides :
# Pointe vers le nœud Sprite2D.
"Niveau/RigidBody2D/Sprite2D"
# Pointe vers le nœud Sprite2D et sa ressource "texture".
# "get_node()" récupérera le Sprite2D, alors que get_node_and_resource()
# récupérera à la fois le nœud Sprite2D et sa ressource "texture".
"Niveau/RigidBody2D/Sprite2D:texture"
# Pointe vers le nœud Sprite2D et sa propriété "position".
"Niveau/RigidBody2D/Sprite2D:position"
# Pointe vers le nœud Sprite2D et à la composante "x" de sa propriété "position".
"Niveau/RigidBody2D/Sprite2D:position:x"
# Pointe vers le nœud RigidBody2D avec un chemin absolu commençant du départ du SceneTree.
"/root/Niveau/RigidBody2D"
Note : En GDScript, il est également possible de convertir une chaîne constante en chemin de nœud en la préfixant avec ^. ^"chemin/vers/noeud" est équivalent à NodePath("chemin/vers/noeud").
Descriptions des méthodes
NodePath get_as_property_path() const 🔗
Renvoie une copie de ce chemin de nœud avec un deux-points (:) en préfixe, le transformant en un chemin de propriété pur sans nom de nœud (relatif au nœud actuel).
# chemin_noeud pointe vers la propriété "x" du nœud enfant nommé "position".
var chemin_noeud = ^"position:x"
# chemin_propriete pointe vers la "position" sur l'axe "x" de ce nœud.
var chemin_propriete = chemin_noeud.get_as_property_path()
print(chemin_propriete) # Affiche ":position:x"
// cheminNoeud pointe vers la propriété "x" du nœud enfant nommé "position".
var cheminNoeud = new NodePath("position:x");
// cheminPropriete pointe vers la "position" sur l'axe "x" de ce nœud.
NodePath cheminPropriete = cheminNoeud.GetAsPropertyPath();
GD.Print(cheminPropriete); // Affiche ":position:x"
StringName get_concatenated_names() const 🔗
Renvoie tous les noms de nœuds concaténés avec un caractère slash (/) en un seul StringName.
StringName get_concatenated_subnames() const 🔗
Renvoie tous les sous-noms de propriété concaténés avec un deux-points (:) en un seul StringName.
var chemin_noeud = ^"Sprite2D:texture:resource_name"
print(chemin_noeud.get_concatenated_subnames()) # Affiche "texture:resource_name"
var cheminNoeud = new NodePath("Sprite2D:texture:resource_name");
GD.Print(cheminNoeud.GetConcatenatedSubnames()); // Affiche "texture:resource_name"
StringName get_name(idx: int) const 🔗
Renvoie le nom du nœud indiqué par l'index idx, à partir de 0. Si idx est hors des limites, une erreur est générée. Voir aussi get_subname_count() et get_name_count().
var chemin_sprite = NodePath()./RigidBody2D/Sprite2D")
print(chemin_sprite.get_name(0)) # Affiche ".."
print(chemin_sprite.get_name(1)) # Affiche "RigidBody2D"
print(chemin_sprite.get_name(2)) # Affiche "Sprite"
var cheminSprite = new NodePath("./RigidBody2D/Sprite2D");
GD.Print(cheminSprite.GetName(0)); // Affiche ".."
GD.Print(cheminSprite.GetName(1)); // Affiche "RigidBody2D"
GD.Print(cheminSprite.GetName(2)); // Affiche "Sprite"
Renvoie le nombre de noms de nœuds dans le chemin. Les sous-noms de propriété ne sont pas inclus.
Par exemple, "../RigidBody2D/Sprite2D:texture" contient 3 noms de nœuds.
StringName get_subname(idx: int) const 🔗
Renvoie le nom de la propriété indiquée par l'index idx, à partir de 0. Si idx est hors des limites, une erreur est générée. Voir aussi get_subname_count().
var chemin_vers_nom = NodePath("Sprite2D:texture:resource_name")
print(chemin_vers_nom.get_subname(0)) # Affiche "texture"
print(chemin_vers_nom.get_subname(1)) # Affiche "resource_name"
var cheminVersNom = new NodePath("Sprite2D:texture:resource_name");
GD.Print(cheminVersNom.GetSubname(0)); // Affiche "texture"
GD.Print(cheminVersNom.GetSubname(1)); // Affiche "resource_name"
int get_subname_count() const 🔗
Renvoie le nombre de noms de propriété (« sous-noms ») dans le chemin. Chaque sous-nom dans le chemin de nœud est listé après un deux-points (:).
Par exemple, "Niveau/RigidBody2D/Sprite2D:texture:resource_name" contient 2 sous-noms.
Renvoie la valeur de hachage sur 32 bits représentant le contenu du chemin de nœud.
Note : Les chemins de nœud avec des valeurs de hachage égales ne sont pas garantis pour être les mêmes, en raison des collisions de hachage. Les chemins de nœud avec différentes valeurs de hachage sont garantis d'être différents.
Renvoie true si le chemin de nœud est absolu. Contrairement à un chemin relatif, un chemin absolu est représenté par un caractère de slash de départ (/) et commence toujours du SceneTree. Il peut être utilisé pour accéder de façon fiable à des nœuds depuis le nœuds racine (par exemple "/root/Global" si un chargement automatique (autoload) nommé «Global» existe).
Renvoie true si le chemin de nœud a été construit à partir d'un String vide (").
NodePath slice(begin: int, end: int = 2147483647) const 🔗
Renvoie la tranche du NodePath, de begin (inclusive) à end (exclusive), en tant que nouveau NodePath.
La valeur absolue de begin et end sera bornée à la taille du tableau, de sorte que la valeur par défaut pour end le fait trancher à la taille du tableau par défaut (c.a.d. arr.slice(1) est un raccourci pour arr.slice(1, arr.size())).
Si begin ou end sont négatifs, ils seront par rapport à la fin du tableau (c.a.d. arr.slice(0, -2) est un raccourci pour arr.slice(0, arr.size() - 2)).
Descriptions des opérateurs
bool operator !=(right: NodePath) 🔗
Renvoie true si les deux chemins de nœud ne sont pas égaux.
bool operator ==(right: NodePath) 🔗
Renvoie true si les deux chemins de nœud sont égaux, c'est-à-dire qu'ils sont composés des mêmes noms et sous-noms de nœuds dans le même ordre.