SceneTree

Успадковує: MainLoop < Object

Управління ігровою петлею через ієрархію вузлів.

Опис

Як один з найважливіших класів, SceneTree керує ієрархією вершин на сцені, а також своїми сценами. Ноди можна додавати, зануритися і видалити. Уся сцена дерево (і таким чином, поточна сцена) може бути використана. Сцени можуть бути завантажені, перевантажені і перезавантажені.

Ви також можете використовувати SceneTree для організації вузлів в групи: Кожна вершина може бути додана в стільки груп, як ви хочете створити, наприклад, групу "неемі". Ви можете потім ітерувати ці групи або навіть викликати методи і встановити властивості на всі вузли, що належать до будь-якої даної групи.

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 Node.update_configuration_warning_warnings(). Тільки вказаний в редакторі редактор.

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

Дзвоните до вершини в групі без особливої поведінки (default).

GroupCallFlags GROUP_CALL_REVERSE = 1

Дзвоните до вершини в групі в зворотному дереві ієрархії порядку (всіх дітей називаються перед їх відповідними материнськими вершинами).

GroupCallFlags GROUP_CALL_DEFERRED = 2

Дзвоните до вершини в групі в кінці поточного кадру (може бути або процесом або фізичним каркасом), схожим на Object.call_deferred().

GroupCallFlags GROUP_CALL_UNIQUE = 4

Дзвоните до вершини в групі тільки один раз, навіть якщо виклик виконується багато разів в одному кадрі. Поєднуватися з GROUP_CALL_DEFERRED для роботи.

Note: Різні аргументи не враховуються. Таким чином, коли той самий виклик виконується з різними аргументами, буде виконуватися тільки перший дзвінок.

Описи властивостей

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() для обробки мережевих пакетів і доставки RPCs. Це дозволяє запустити RPCs в різній петлі (наприклад, фізики, нитки, специфічний крок часу) і для керівництва 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, програма автоматично висувається при навігації спини (наприклад, за допомогою системи "Back" на Андроїд).

Щоб впоратися з кнопкою «Повернутися назад», коли цей параметр вимкнено, скористайтеся 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).

Примітка: A 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 Настанови інтерфейсу користувача користувач очікується закривати програми за допомогою кнопки «Домашній».

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 порожній.

Примітка: Для підшляху, що містить root_path, не потрібно налаштовувати MultiplayerAPI, вкладені користувацькі багатокористувацькі ігри не дозволені. Тобто, якщо один налаштовано для "/root/Foo", встановлення для "/root/Foo/Bar" призведе до помилки.

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

void unload_current_scene() 🔗

Якщо поточна сцена завантажується, викликаючи цей метод буде перевантажувати його.