NodePath
Приблизний сюжетний шлях.
Опис
Вбудований тип NodePath Variant представляє шлях до вузла або властивості в ієрархії вузлів. Його розроблено для ефективної передачі в багато вбудованих методів (таких як Node.get_node(), Object.set_indexed(), Tween.tween_property() тощо) без жорсткої залежності від вузла чи властивості, на які вони вказують.
Шлях до вузла представлено як String, що складається з імен вузлів, розділених скісною рискою (/) і розділених двокрапками (:) імен властивостей (також званих «підіменами»). Подібно до шляху файлової системи, ".." і "." є спеціальними іменами вузлів. Вони посилаються на батьківський вузол і поточний вузол відповідно.
Наведені нижче приклади є шляхами відносно поточного вузла:
^"A" # Вказує на пряму дочірню 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 із С#. Більше інформації: ref:doc_c_sharp_differences.
Посібники
Конструктори
NodePath() |
|
Методи
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 |
|
Оператори
operator !=(right: NodePath) |
|
operator ==(right: NodePath) |
Описи конструкторів
Будуємо порожній NodePath.
NodePath NodePath(from: NodePath)
Constructs a NodePath як копія даної NodePath.
NodePath NodePath(from: String)
Створює NodePath із String. Створений шлях є абсолютним, якщо перед ним ставиться коса риска (див. is_absolute()).
«Підімена», необов’язково включені після шляху до цільового вузла, можуть вказувати на властивості, а також можуть бути вкладеними.
Наступні рядки можуть бути дійсними шляхами вузлів:
# Вказує на вузол Sprite2D.
"Level/RigidBody2D/Sprite2D"
# Вказує на вузол Sprite2D і його "текстурний" ресурс.
# get_node() отримає Sprite2D, а get_node_and_resource()
# отримає як вузол Sprite2D, так і ресурс "текстура".
"Level/RigidBody2D/Sprite2D: текстура"
# Вказує на вузол Sprite2D і його властивість "position".
"Level/RigidBody2D/Sprite2D:позиція"
# Вказує на вузол Sprite2D і компонент "x" його властивості "position".
"Level/RigidBody2D/Sprite2D:position:x"
# Вказує на вузол RigidBody2D як абсолютний шлях, що починається від SceneTree.
"/root/Level/RigidBody2D"
Примітка: У GDScript також можна перетворити постійний рядок на шлях до вузла, додавши до нього префікс ^. ^"шлях/до/вузла" еквівалентний NodePath("шлях/до/вузла").
Описи методів
NodePath get_as_property_path() const 🔗
Повертає копію шляху цього вузла з префіксом двокрапки (:), перетворюючи його на чистий шлях властивостей без імен вузла (відносно поточного вузла).
# node_path вказує на властивість "x" дочірнього вузла з назвою "position".
var node_path = ^"position:x"
# property_path вказує на «позицію» на осі «x» цього вузла.
var property_path = node_path.get_as_property_path()
print(property_path) # Виводить ":position:x"
// nodePath вказує на властивість "x" дочірнього вузла з назвою "position".
var nodePath = new NodePath("position:x");
// propertyPath вказує на "положення" на осі "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"
Повертаємо кількість імен вузлів в шляху. Прізвище не входить.
Наприклад, ./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)) # Друкує "текстуру"
print(path_to_name.get_subname(1)) # Виводить "назва_ресурсу"
var pathToName = new NodePath("Sprite2D:texture:resource_name");
GD.Print(pathToName.GetSubname(0)); // Друкує "текстуру"
GD.Print(pathToName.GetSubname(1)); // Виводить "resource_name"
int get_subname_count() const 🔗
Повертаємо кількість майнових імен ("підім'я") в доріці. Кожна підпам'я в контурі вершини перераховується після колонного символу (:).
Наприклад, "Level/RigidBody2D/Sprite2D:texture:resource_name" містить 2 підмені.
Повертає значення 32-бітного хешу, що представляє вміст вершини.
Примітка: Маршрути Node з однаковими значеннями хеш * не* гарантовано бути таким же, як наслідок зіткнень. Відсутні шляхи з різними значеннями хешу гарантовано відрізняються.
Повертає true, якщо шлях вершини абсолютний. На відміну від відносного шляху, абсолютний шлях представлений провідним символом зіткнення (/) і завжди починається з SceneTree. Він може бути використаний для надійного доступу вузлів з кореневого вузла (наприклад, "/root/Global", якщо автозавантаження названо "Global".
Повертає true, якщо шлях вершини був побудований з порожнього String (""").
NodePath slice(begin: int, end: int = 2147483647) const 🔗
Повертаємо розріз NodePath, з begin (включно) до end (виключно), як новий NodePath.
Абсолютне значення begin і end буде зафіксовано до суми get_name_count() і get_subname_count(), тому значення за замовчуванням для end встановлює кінець NodePath кінцем розрізу за замовчуванням (i.e. path.slice(1) є скороченим записом path.slice(1, path.get_name_count() + path.get_subname_count()).
Якщо ж start або end є негативними, вони будуть відносно кінця NodePath (i.e. 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, якщо два шляхи вершини рівні, тобто вони складаються з однакових імен вузлів і підnames в одному порядку.