SceneTree

Наследует: MainLoop < Object

Управляет игровым циклом через иерархию узлов.

Описание

Как один из самых важных классов, SceneTree управляет иерархией узлов в сцене, а также самими сценами. Узлы можно добавлять, извлекать и удалять. Все дерево сцены (и, следовательно, текущую сцену) можно приостанавливать. Сцены можно загружать, переключать и перезагружать.

Вы также можете использовать SceneTree для организации узлов в groups: каждый узел можно добавлять в столько групп, сколько вы хотите создать, например, в группу «enemy». Затем вы можете перебирать эти группы или даже вызывать методы и задавать свойства для всех узлов, принадлежащих любой заданной группе.

SceneTree — это реализация MainLoop по умолчанию, используемая движком, и, таким образом, отвечает за игровой цикл.

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

Свойства

bool	auto_accept_quit	`true`
Node	current_scene
bool	debug_collisions_hint	`false`
bool	debug_navigation_hint	`false`
bool	debug_paths_hint	`false`
Node	edited_scene_root
bool	multiplayer_poll	`true`
bool	paused	`false`
bool	physics_interpolation	`false`
bool	quit_on_go_back	`true`
Window	root

Методы

void	call_group(group: StringName, method: StringName, ...) vararg
void	call_group_flags(flags: int, group: StringName, method: StringName, ...) vararg
Error	change_scene_to_file(path: String)
Error	change_scene_to_packed(packed_scene: PackedScene)
SceneTreeTimer	create_timer(time_sec: float, process_always: bool = true, process_in_physics: bool = false, ignore_time_scale: bool = false)
Tween	create_tween()
Node	get_first_node_in_group(group: StringName)
int	get_frame() const
MultiplayerAPI	get_multiplayer(for_path: NodePath = NodePath("")) const
int	get_node_count() const
int	get_node_count_in_group(group: StringName) const
Array[Node]	get_nodes_in_group(group: StringName)
Array[Tween]	get_processed_tweens()
bool	has_group(name: StringName) const
bool	is_accessibility_enabled() const
bool	is_accessibility_supported() const
void	notify_group(group: StringName, notification: int)
void	notify_group_flags(call_flags: int, group: StringName, notification: int)
void	queue_delete(obj: Object)
void	quit(exit_code: int = 0)
Error	reload_current_scene()
void	set_group(group: StringName, property: String, value: Variant)
void	set_group_flags(call_flags: int, group: StringName, property: String, value: Variant)
void	set_multiplayer(multiplayer: MultiplayerAPI, root_path: NodePath = NodePath(""))
void	unload_current_scene()

Сигналы

node_added(node: Node) 🔗

Выдается, когда node входит в это дерево.

node_configuration_warning_changed(node: Node) 🔗

Выдается при вызове Node.update_configuration_warnings() node. Выдается только в редакторе.

node_removed(node: Node) 🔗

Вызывается, когда node покидает это дерево.

node_renamed(node: Node) 🔗

Вызывается при изменении Node.name node.

physics_frame() 🔗

Создается непосредственно перед вызовом Node._physics_process() на каждом узле в этом дереве.

process_frame() 🔗

Создается непосредственно перед вызовом Node._process() на каждом узле в этом дереве.

scene_changed() 🔗

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

# Этот код должен быть внутри автозагрузки.
get_tree().change_scene_to_file(other_scene_path)
await get_tree().scene_changed
print(get_tree().current_scene) # Выводит новую сцену.

tree_changed() 🔗

Генерируется каждый раз при изменении иерархии дерева (перемещении, переименовании узлов и т. д.).

tree_process_mode_changed() 🔗

Выдается при изменении Node.process_mode любого узла внутри дерева. Выдается только в редакторе для обновления видимости отключенных узлов.

Перечисления

enum GroupCallFlags: 🔗

GroupCallFlags GROUP_CALL_DEFAULT = 0

Вызов узлов внутри группы без специального поведения (по умолчанию).

GroupCallFlags GROUP_CALL_REVERSE = 1

Вызов узлов внутри группы в обратном порядке иерархии дерева (все вложенные дочерние узлы вызываются раньше соответствующих им родительских узлов).

GroupCallFlags GROUP_CALL_DEFERRED = 2

Вызов узлов внутри группы в конце текущего кадра (может быть как кадр процесса, так и физический кадр), аналогично Object.call_deferred().

GroupCallFlags GROUP_CALL_UNIQUE = 4

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

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

Описания свойств

bool auto_accept_quit = true 🔗

void set_auto_accept_quit(value: bool)
bool is_auto_accept_quit()

Если true, приложение автоматически принимает запросы на выход.

Для мобильных платформ см. quit_on_go_back.

Node current_scene 🔗

void set_current_scene(value: Node)
Node get_current_scene()

Корневой узел текущей загруженной основной сцены, обычно как прямой потомок root. См. также change_scene_to_file(), change_scene_to_packed() и reload_current_scene().

Предупреждение: Установка этого свойства напрямую может не работать так, как ожидается, поскольку она не добавляет и не удаляет какие-либо узлы из этого дерева.

bool debug_collisions_hint = false 🔗

void set_debug_collisions_hint(value: bool)
bool is_debugging_collisions_hint()

Если true, формы столкновений будут видны при запуске игры из редактора для целей отладки.

Примечание: Это свойство не предназначено для изменения во время выполнения. Изменение значения debug_collisions_hint во время выполнения проекта не даст желаемого эффекта.

bool debug_navigation_hint = false 🔗

void set_debug_navigation_hint(value: bool)
bool is_debugging_navigation_hint()

Если true, навигационные полигоны будут видны при запуске игры из редактора для целей отладки.

Примечание: Это свойство не предназначено для изменения во время выполнения. Изменение значения debug_navigation_hint во время выполнения проекта не даст желаемого эффекта.

bool debug_paths_hint = false 🔗

void set_debug_paths_hint(value: bool)
bool is_debugging_paths_hint()

Если true, кривые от Path2D и Path3D будут видимы во время работы игры из редактора для откладки.

Примечание: Это свойство не изменяемо по время выполнения. Попытки изменить значение debug_paths_hint пока проект выполняется не приведёт к желательному эффекту.

Node edited_scene_root 🔗

void set_edited_scene_root(value: Node)
Node get_edited_scene_root()

Корень сцены, которая в данный момент редактируется в редакторе. Обычно это прямой потомок root.

Примечание: Это свойство ничего не делает в сборках релиза.

bool multiplayer_poll = true 🔗

void set_multiplayer_poll_enabled(value: bool)
bool is_multiplayer_poll_enabled()

Если true (значение по умолчанию), включает автоматический опрос MultiplayerAPI для этого SceneTree во время process_frame.

Если false, вам необходимо вручную вызвать MultiplayerAPI.poll() для обработки сетевых пакетов и доставки RPC. Это позволяет запускать RPC в другом цикле (например, физика, поток, определенный временной шаг) и для ручной защиты Mutex при доступе к MultiplayerAPI из потоков.

bool paused = false 🔗

void set_pause(value: bool)
bool is_paused()

Если true, дерево сцены считается приостановленным. Это приводит к следующему поведению:

2D и 3D физика будут остановлены, а также обнаружение столкновений и связанные с ними сигналы.
В зависимости от Node.process_mode каждого узла, их методы обратного вызова Node._process(), Node._physics_process() и Node._input() могут больше не вызываться.

bool physics_interpolation = false 🔗

void set_physics_interpolation_enabled(value: bool)
bool is_physics_interpolation_enabled()

Если true, рендерер будет интерполировать преобразования объектов (как физических, так и не физических) между двумя последними преобразованиями, так что плавное движение будет видно даже тогда, когда физические тики не совпадают с отрисованными кадрами.

Значение этого свойства по умолчанию контролируется ProjectSettings.physics/common/physics_interpolation.

Примечание: Хотя это глобальная настройка, более точное управление отдельными ветвями SceneTree возможно с помощью Node.physics_interpolation_mode.

bool quit_on_go_back = true 🔗

void set_quit_on_go_back(value: bool)
bool is_quit_on_go_back()

Если true, приложение автоматически завершает работу при возврате назад (например, с помощью системной кнопки «Назад» на Android).

Для обработки кнопки «Назад», когда эта опция отключена, используйте DisplayServer.WINDOW_EVENT_GO_BACK_REQUEST.

Window root 🔗

Window get_root()

Корень дерева Window. Это самый верхний Node дерева сцены, и он всегда присутствует. Абсолютный NodePath всегда начинается с этого узла. Потомки корневого узла могут включать загруженный current_scene, а также любой AutoLoad, настроенный в настройках проекта.

Предупреждение: Не удаляйте этот узел. Это приведет к нестабильному поведению, за которым последует сбой.

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

void call_group(group: StringName, method: StringName, ...) vararg 🔗

Вызывает method для каждого узла внутри этого дерева, добавленного в заданную group. Вы можете передать аргументы в method, указав их в конце вызова этого метода. Узлы, которые не могут вызвать method (либо потому, что метод не существует, либо аргументы не совпадают), игнорируются. См. также set_group() и notify_group().

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

Примечание: В C# method должен быть в snake_case при ссылке на встроенные методы Godot. Предпочитайте использовать имена, представленные в классе MethodName, чтобы избежать выделения нового StringName при каждом вызове.

void call_group_flags(flags: int, group: StringName, method: StringName, ...) vararg 🔗

Вызывает заданный method для каждого узла внутри этого дерева, добавленного в заданную group. Используйте flags для настройки поведения этого метода (см. GroupCallFlags). Дополнительные аргументы для method могут быть переданы в конце этого метода. Узлы, которые не могут вызвать method (либо потому, что метод не существует, либо аргументы не совпадают), игнорируются.

# Вызывает "hide" для всех узлов группы "enemies" в конце кадра и в обратном порядке дерева.
get_tree().call_group_flags(
        SceneTree.GROUP_CALL_DEFERRED | SceneTree.GROUP_CALL_REVERSE,
        "enemies", "hide")

Примечание: В C# method должен быть в snake_case при ссылке на встроенные методы Godot. Предпочитайте использовать имена, представленные в классе MethodName, чтобы избежать выделения нового StringName при каждом вызове.

Error change_scene_to_file(path: String) 🔗

Изменяет запущенную сцену на ту, которая находится по указанному path, после загрузки ее в PackedScene и создания нового экземпляра.

Возвращает @GlobalScope.OK в случае успеха, @GlobalScope.ERR_CANT_OPEN, если path не может быть загружен в PackedScene, или @GlobalScope.ERR_CANT_CREATE, если эта сцена не может быть создана.

Примечание: Подробности о порядке операций см. в change_scene_to_packed().

Error change_scene_to_packed(packed_scene: PackedScene) 🔗

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

Возвращает @GlobalScope.OK в случае успеха, @GlobalScope.ERR_CANT_CREATE, если сцену невозможно создать, или @GlobalScope.ERR_INVALID_PARAMETER, если сцена недопустима.

Примечание: Операции происходят в следующем порядке при вызове change_scene_to_packed():

Текущий узел сцены немедленно удаляется из дерева. С этого момента Node.get_tree(), вызванный на текущей (исходящей) сцене, вернет null. current_scene также будет null, поскольку новая сцена еще недоступна.
В конце кадра ранее текущая сцена, уже удаленная из дерева, будет удалена (освобождена из памяти), а затем новая сцена будет инстанцирована и добавлена в дерево. Node.get_tree() и current_scene вернутся к работе в обычном режиме.

Это гарантирует, что обе сцены не будут запущены одновременно, при этом предыдущая сцена будет безопасно освобождена, аналогично Node.queue_free().

Если вы хотите надежно получить доступ к новой сцене, дождитесь сигнала scene_changed.

SceneTreeTimer create_timer(time_sec: float, process_always: bool = true, process_in_physics: bool = false, ignore_time_scale: bool = false) 🔗

Возвращает новый SceneTreeTimer. По истечении time_sec в секундах таймер выдаст SceneTreeTimer.timeout и будет автоматически освобожден.

Если process_always равен false, таймер будет остановлен при установке paused в true.

Если process_in_physics равен true, таймер обновится в конце кадра физики, а не кадра процесса.

Если ignore_time_scale равен true, таймер проигнорирует Engine.time_scale и обновится с реальным, прошедшим временем.

Этот метод обычно используется для создания одноразового таймера задержки, как в следующем примере:

func some_function():
    print("начало")
    await get_tree().create_timer(1.0).timeout
    print("конец")

public async Task SomeFunction()
{
    GD.Print("начало");
    await ToSignal(GetTree().CreateTimer(1.0f), SceneTreeTimer.SignalName.Timeout);
    GD.Print("конец");
}

Примечание: Таймер всегда обновляется после всех узлов в дереве. Метод Node._process() узла будет вызван до обновления таймера (или Node._physics_process(), если process_in_physics установлен в true).

Tween create_tween() 🔗

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

Примечание: Tween, созданный с помощью этого метода, не привязан ни к одному Node. Он может продолжать работать до тех пор, пока не останется ничего для анимации. Если вы хотите, чтобы Tween автоматически уничтожался при освобождении Node, используйте Node.create_tween() или Tween.bind_node().

Node get_first_node_in_group(group: StringName) 🔗

Возвращает первый Node, найденный внутри дерева, который был добавлен в заданную group в порядке иерархии сцены. Возвращает null, если совпадений не найдено. См. также get_nodes_in_group().

int get_frame() const 🔗

Возвращает количество обработанных шагов физического процесса с момента запуска приложения. Это не измерение прошедшего времени. См. также physics_frame. Количество отрисованных кадров см. в Engine.get_process_frames().

MultiplayerAPI get_multiplayer(for_path: NodePath = NodePath("")) const 🔗

Ищет MultiplayerAPI, настроенный для указанного пути, если он не существует, он ищет родительские пути, пока не найдет его. Если путь пустой или ничего не найдено, возвращается путь по умолчанию. См. set_multiplayer().

int get_node_count() const 🔗

Возвращает количество узлов внутри этого дерева.

int get_node_count_in_group(group: StringName) const 🔗

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

Array[Node] get_nodes_in_group(group: StringName) 🔗

Возвращает Array, содержащий все узлы внутри этого дерева, которые были добавлены в заданную group, в порядке иерархии сцены.

Array[Tween] get_processed_tweens() 🔗

Возвращает Array существующих в данный момент Tween-ов в дереве, включая приостановленные твины.

bool has_group(name: StringName) const 🔗

Возвращает true, если узел, добавленный в заданную группу name, существует в дереве.

bool is_accessibility_enabled() const 🔗

Возвращает true, если функции доступности включены и обновления информации о доступности активно обрабатываются.

bool is_accessibility_supported() const 🔗

Возвращает true, если специальные возможности поддерживаются ОС и включены в настройках проекта.

void notify_group(group: StringName, notification: int) 🔗

Вызывает Object.notification() с заданным notification для всех узлов внутри этого дерева, добавленных в group. См. также уведомления Godot и call_group() и set_group().

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

void notify_group_flags(call_flags: int, group: StringName, notification: int) 🔗

Вызывает Object.notification() с заданным notification для всех узлов внутри этого дерева, добавленных в group. Используйте call_flags для настройки поведения этого метода (см. GroupCallFlags).

void queue_delete(obj: Object) 🔗

Ставит в очередь указанный obj для удаления, вызывая его Object.free() в конце текущего кадра. Этот метод похож на Node.queue_free().

void quit(exit_code: int = 0) 🔗

Завершает работу приложения в конце текущей итерации с заданным exit_code.

По соглашению код выхода 0 указывает на успех, тогда как любой другой код выхода указывает на ошибку. Из соображений переносимости он должен быть между 0 и 125 (включительно).

Примечание: На iOS этот метод не работает. Вместо этого, как рекомендуется в iOS Human Interface Guidelines, пользователь должен закрывать приложения с помощью кнопки «Домой».

Error reload_current_scene() 🔗

Перезагружает текущую активную сцену, заменяя current_scene новым экземпляром ее исходного PackedScene.

Возвращает @GlobalScope.OK в случае успеха, @GlobalScope.ERR_UNCONFIGURED, если current_scene не определен, @GlobalScope.ERR_CANT_OPEN, если current_scene не может быть загружен в PackedScene, или @GlobalScope.ERR_CANT_CREATE, если сцена не может быть создана.

void set_group(group: StringName, property: String, value: Variant) 🔗

Устанавливает заданное property в value для всех узлов внутри этого дерева, добавленных в заданную group. Узлы, не имеющие property, игнорируются. См. также call_group() и notify_group().

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

Примечание: В C# property должно быть в snake_case при ссылке на встроенные свойства Godot. Предпочитайте использовать имена, представленные в классе PropertyName, чтобы избежать выделения нового StringName при каждом вызове.

void set_group_flags(call_flags: int, group: StringName, property: String, value: Variant) 🔗

Устанавливает заданное property в value на всех узлах внутри этого дерева, добавленных в заданную group. Узлы, не имеющие property, игнорируются. Используйте call_flags для настройки поведения этого метода (см. GroupCallFlags).

Примечание: В C# property должно быть в snake_case при ссылке на встроенные свойства Godot. Предпочитайте использовать имена, представленные в классе PropertyName, чтобы избежать выделения нового StringName при каждом вызове.

void set_multiplayer(multiplayer: MultiplayerAPI, root_path: NodePath = NodePath("")) 🔗

Устанавливает пользовательский MultiplayerAPI с заданным root_path (управляя также относительными подпутями) или переопределяет стандартный, если root_path пуст.

Примечание: Не нужно настраивать MultiplayerAPI для подпути, содержащей root_path, вложенные пользовательские многопользовательские режимы не допускаются. То есть, если один настроен для "/root/Foo", установка одного для "/root/Foo/Bar" приведет к ошибке.

Примечание: set_multiplayer() следует вызывать до готовности дочерних узлов в заданном root_path. Если многопользовательские узлы, такие как MultiplayerSpawner или MultiplayerSynchronizer, добавляются в дерево до установки пользовательского многопользовательского API, они не будут работать.

void unload_current_scene() 🔗

Если текущая сцена загружена, вызов этого метода выгрузит ее.