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

Предварительно проанализированный путь дерева сцены.

Описание

Встроенный тип Variant NodePath представляет собой путь к узлу или свойству в иерархии узлов. Он разработан для эффективной передачи во многие встроенные методы (такие как Node.get_node(), Object.set_indexed(), Tween.tween_property() и т. д.) без жесткой зависимости от узла или свойства, на которые они указывают.

Путь к узлу представлен как String, состоящий из разделенных косой чертой (/) имен узлов и разделенных двоеточием (:) имен свойств (также называемых «подименами»). Подобно пути файловой системы, ".." и "." являются специальными именами узлов. Они ссылаются на родительский узел и текущий узел соответственно.

Следующие примеры являются путями относительно текущего узла:

^"A"     # Указывает на прямого потомка А.
^"A/B"   # Указывает на дочерний элемент А — B.
^"."     # Указывает на текущий узел.
^".."    # Указывает на родительский узел.
^"../C"  # Указывает на родственный узел C.
^"../.." # Указывает на прародительский узел.

Начальная косая черта означает, что путь абсолютный и начинается с SceneTree:

^"/root"            # Указывает на корневое окно SceneTree.
^"/root/Title"      # Может указывать на корневой узел основной сцены с именем «Title».
^"/root/Global"     # Может указывать на автоматически загруженный узел или сцену с именем «Global».

Несмотря на свое название, пути узлов также могут указывать на свойство:

^":position"           # Указывает на положение этого объекта.
^":position:x"         # Указывает на положение данного объекта по оси x.
^"Camera3D:rotation:y" # Указывает на дочернюю камеру Camera3D и ее вращение по оси Y.
^"/root:size:x"        # Указывает на корневое окно и его ширину.

В некоторых ситуациях можно опустить ведущий : при указании на свойство объекта. Например, это касается Object.set_indexed() и Tween.tween_property(), поскольку эти методы вызывают get_as_property_path() под капотом. Однако обычно рекомендуется сохранять префикс :.

Пути узлов не могут проверять, являются ли они допустимыми, и могут указывать на узлы или свойства, которые не существуют. Их значение полностью зависит от контекста, в котором они используются.

Обычно вам не нужно беспокоиться о типе NodePath, поскольку строки автоматически преобразуются в этот тип при необходимости. Бывают случаи, когда определение путей узлов полезно. Например, экспортированные свойства NodePath позволяют вам легко выбирать любой узел в текущей редактируемой сцене. Они также автоматически обновляются при перемещении, переименовании или удалении узлов в редакторе дерева сцены. См. также @GDScript.@export_node_path.

См. также StringName, который является похожим типом, разработанным для оптимизированных строк.

Примечание: В булевом контексте NodePath будет оцениваться как false, если он пуст (NodePath("")). В противном случае NodePath всегда будет оцениваться как true.

Примечание

Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и GDScript.

Обучающие материалы

Демо 2D ролевой игры (РПГ)

Конструкторы

NodePath	NodePath()
NodePath	NodePath(from: NodePath)
NodePath	NodePath(from: String)

Методы

NodePath	get_as_property_path() const
StringName	get_concatenated_names() const
StringName	get_concatenated_subnames() const
StringName	get_name(idx: int) const
int	get_name_count() const
StringName	get_subname(idx: int) const
int	get_subname_count() const
int	hash() const
bool	is_absolute() const
bool	is_empty() const
NodePath	slice(begin: int, end: int = 2147483647) const

Операторы

bool	operator !=(right: NodePath)
bool	operator ==(right: NodePath)

Описания конструктора

NodePath NodePath() 🔗

Создает пустой NodePath.

NodePath NodePath(from: NodePath)

Создает NodePath как копию заданного NodePath.

NodePath NodePath(from: String)

Создает NodePath из String. Созданный путь является абсолютным, если предваряется косой чертой (см. is_absolute()).

"Подимена", необязательно включаемые после пути к целевому узлу, могут указывать на свойства, а также могут быть вложенными.

Следующие строки могут быть допустимыми путями узлов:

# Указывает на узел Sprite2D.
"Level/RigidBody2D/Sprite2D"

# Указывает на узел Sprite2D и его ресурс «texture».
# get_node() извлечет Sprite2D, в то время как get_node_and_resource()
# извлечет как узел Sprite2D, так и ресурс «texture».
"Level/RigidBody2D/Sprite2D:texture"

# Указывает на узел Sprite2D и его свойство «position».
"Level/RigidBody2D/Sprite2D:position"

# Указывает на узел Sprite2D и компонент «x» его свойства «position».
"Level/RigidBody2D/Sprite2D:position:x"

# Указывает на узел RigidBody2D как на абсолютный путь, начинающийся от SceneTree.
"/root/Level/RigidBody2D"

Примечание: В GDScript также можно преобразовать постоянную строку в путь к узлу, добавив к ней префикс ^. ^"path/to/node" эквивалентно NodePath("path/to/node").

Описания метода

NodePath get_as_property_path() const 🔗

Возвращает копию этого пути узла с префиксом двоеточия (:), преобразуя его в чистый путь свойства без имен узлов (относительно текущего узла).

# node_path указывает на свойство «x» дочернего узла с именем «position».
var node_path = ^"position:x"

# property_path указывает на «position» по оси «x» этого узла.
var property_path = node_path.get_as_property_path()
print(property_path) # Выводит ":position:x"

// node_path указывает на свойство «x» дочернего узла с именем «position».
var nodePath = new NodePath("position:x");

// property_path указывает на «position» по оси «x» этого узла.
NodePath propertyPath = nodePath.GetAsPropertyPath();
GD.Print(propertyPath); // Выводит ":position:x"

StringName get_concatenated_names() const 🔗

Возвращает все имена узлов, объединенные с помощью символа косой черты (/) как единое StringName.

StringName get_concatenated_subnames() const 🔗

Возвращает все подимена свойств, объединенные символом двоеточия (:) как единое StringName.

var node_path = ^"Sprite2D:texture:resource_name"
print(node_path.get_concatenated_subnames()) # Выводит "texture:resource_name"

var nodePath = new NodePath("Sprite2D:texture:resource_name");
GD.Print(nodePath.GetConcatenatedSubnames()); // Выводит "texture:resource_name"

StringName get_name(idx: int) const 🔗

Возвращает имя узла, указанное idx, начиная с 0. Если idx выходит за пределы, генерируется ошибка. См. также get_subname_count() и get_name_count().

var sprite_path = NodePath("../RigidBody2D/Sprite2D")
print(sprite_path.get_name(0)) # Выводит ".."
print(sprite_path.get_name(1)) # Выводит "RigidBody2D"
print(sprite_path.get_name(2)) # Выводит "Sprite"

var spritePath = new NodePath("../RigidBody2D/Sprite2D");
GD.Print(spritePath.GetName(0)); // Выводит ".."
GD.Print(spritePath.GetName(1)); // Выводит "PathFollow2D"
GD.Print(spritePath.GetName(2)); // Выводит "Sprite"

int get_name_count() const 🔗

Возвращает количество имен узлов в пути. Подимена свойств не включены.

Например, "../RigidBody2D/Sprite2D:texture" содержит 3 имени узлов.

StringName get_subname(idx: int) const 🔗

Возвращает имя свойства, указанное idx, начиная с 0. Если idx выходит за пределы, генерируется ошибка. См. также get_subname_count().

var path_to_name = NodePath("Sprite2D:texture:resource_name")
print(path_to_name.get_subname(0)) # Выводит "texture"
print(path_to_name.get_subname(1)) # Выводит "resource_name"

var pathToName = new NodePath("Sprite2D:texture:resource_name");
GD.Print(pathToName.GetSubname(0)); // Выводит "texture"
GD.Print(pathToName.GetSubname(1)); // Выводит "resource_name"

int get_subname_count() const 🔗

Возвращает количество имен свойств («подимен») в пути. Каждое подимя в пути узла указывается после символа двоеточия (:).

Например, "Level/RigidBody2D/Sprite2D:texture:resource_name" содержит 2 подимени.

int hash() const 🔗

Возвращает 32-битное хэш-значение, представляющее содержимое пути узла.

Примечание: Пути узлов с одинаковыми значениями хэша не гарантированно будут одинаковыми из-за коллизий хэшей. Пути узлов с разными значениями хэшей гарантированно будут разными.

bool is_absolute() const 🔗

Возвращает true, если путь к узлу абсолютный. В отличие от относительного пути, абсолютный путь представлен начальным символом косой черты (/) и всегда начинается с SceneTree. Его можно использовать для надежного доступа к узлам из корневого узла (например, "/root/Global", если существует автозагрузка с именем "Global").

bool is_empty() const 🔗

Возвращает true, если путь к узлу был создан из пустой String ("").

NodePath slice(begin: int, end: int = 2147483647) const 🔗

Возвращает срез NodePath от begin (включительно) до end (исключительно) как новый NodePath.

Абсолютное значение begin и end будет ограничено суммой get_name_count() и get_subname_count(), поэтому значение по умолчанию для end делает его срезом до конца NodePath по умолчанию (т. е. path.slice(1) является сокращением для path.slice(1, path.get_name_count() + path.get_subname_count())).

Если begin или end отрицательны, они будут относительными к концу NodePath (т. е. path.slice(0, -2) является сокращением для path.slice(0, path.get_name_count() + path.get_subname_count() - 2)).

Описания оператора

bool operator !=(right: NodePath) 🔗

Возвращает true, если пути двух узлов не равны.

bool operator ==(right: NodePath) 🔗

Возвращает true, если два пути узлов равны, то есть они состоят из одинаковых имен узлов и подимен в одинаковом порядке.