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...

Уникальные Узлы Сцены

Введение

Использование get_node() для ссылки на узлы из скрипта иногда может быть ненадёжным. При перемещении кнопки в сцене пользовательского интерфейса с одной панели на другую путь к узлу кнопки изменится, а если скрипт использует get_node() с жёстко заданным путём к узлу, скрипт больше не сможет найти кнопку.

В подобных ситуациях узел можно превратить в уникальный узел сцены, чтобы избежать необходимости обновлять скрипт каждый раз при изменении пути к узлу.

Создание и использование

Создать уникальный узел сцены можно двумя способами.

В дереве Сцены щелкните правой кнопкой мыши по узлу и выберите в контекстном меню пункт Доступ как уникальное имя.

После выбора этой опции рядом с именем узла в дереве сцены появится символ процента (%):

Вы также можете сделать это при переименовании узла, добавив "%" в начало имени. После подтверждения рядом с именем появится символ процента.

Теперь вы можете использовать узел в своём скрипте. Например, вы можете обратиться к нему с помощью вызова метода get_node(), введя символ % и имя узла:

GDScriptC#

get_node("%RedButton").text = "Hello"
%RedButton.text = "Hello" # Shorter syntax

Ограничение одной сцены

Уникальный узел сцены может быть получен только узлом внутри той же сцены. Чтобы продемонстрировать это ограничение, рассмотрим пример сцены Player, которая является экземпляром сцены Sword:

Вот результаты вызовов get_node() внутри скрипта Player:

• get_node("%Eyes") возвращает узел Eyes.

• get_node("%Hilt") возвращает null.

Вот результаты вызовов get_node() внутри скрипта Sword:

• get_node("%Eyes") возвращает null.

• get_node("%Hilt") возвращает узел Hilt.

Если скрипт имеет доступ к узлу в другой сцене, он может вызвать get_node() для этого узла, чтобы получить уникальные узлы сцены из сцены этого узла. Это также работает в пути к узлам, что позволяет избежать множественных вызовов get_node(). Вот два способа получить узел Hilt из скрипта Player, используя уникальные узлы сцены:

• get_node("Hand/Sword").get_node("%Hilt") возвращает узел Hilt.

• get_node("Hand/Sword/%Hilt") также возвращает узел Hilt.

Уникальные имена сцены работают не только в конце пути узла. Их можно использовать в середине для навигации от одного узла к другому. Например, узел Sword отмечен как уникальный узел сцены в сцене Player, поэтому возможно следующее:

• get_node("%Sword/%Hilt") возвращает узел Hilt.

Альтернативы

Уникальные узлы сцены — полезный инструмент для навигации по ним. Однако в некоторых ситуациях другие методы могут оказаться более эффективными.

Group позволяет определить местоположение узла (или группы из многих узлов) из любого другого узла, независимо от того, в какой сцене находятся два узла.

Singleton (Autoload) — это всегда загруженный узел, к которому любой узел может получить прямой доступ независимо от сцены. Такие узлы полезны, когда некоторые данные или функции используются глобально.

Node.find_child() находит узел по имени, не зная его полного пути. Это похоже на уникальный узел сцены, но этот метод может находить узлы во вложенных сценах и не требует какой-либо пометки узла в редакторе сцен. Однако этот метод медленный. Уникальные узлы сцены кэшируются Godot и быстро извлекаются, но при каждом вызове метода find_child() необходимо проверить каждого потомка (каждого дочернего элемента, каждого внучатого элемента и так далее).