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.

Вузли та екземпляри сцени

У цьому посібнику пояснюється, як отримувати вузли, створювати вузли, додавати їх як дочірні елементи та створювати екземпляри сцен із коду.

Дивись також

Ознайомтеся з посібником Створення екземплярів, щоб дізнатися про підхід Godot до інстанціювання сцен.

Отримання вузлів

Ви можете отримати посилання на вузол, викликавши метод Node.get_node(). Щоб це працювало, дочірній вузол має бути присутнім у дереві сцени. Отримання його у функції _ready() батьківського вузла гарантує це.

Якщо, наприклад, у вас є таке дерево сцен і ви хочете отримати посилання на вузли Sprite2D та Camera2D, щоб отримати до них доступ у своєму скрипті.

../../_images/nodes_and_scene_instances_player_scene_example.webp

Для цього ви можете скористатися наступним кодом.

var sprite2d
var camera2d

func _ready():
    sprite2d = get_node("Sprite2D")
    camera2d = get_node("Camera2D")

Зверніть увагу, що ви отримуєте вузли, використовуючи їх ім’я, а не тип. Вище «Sprite2D» і «Camera2D» є іменами вузлів у сцені.

../../_images/nodes_and_scene_instances_sprite_node.webp

Якщо ви перейменуєте вузол Sprite2D на Skin у доку Scene, вам доведеться змінити рядок, який отримує вузол, на get_node("Skin") у сценарії.

../../_images/nodes_and_scene_instances_sprite_node_renamed.webp

Шляхи вузлів

Отримавши посилання на вузол, ви не обмежені отриманням безпосереднього дочірнього елемента. Функція get_node() підтримує шляхи, схоже на роботу з файловим браузером. Додайте косу риску для розділення вузлів.

Візьмемо наступний приклад сцени зі сценарієм, приєднаним до вузла UserInterface.

../../_images/nodes_and_scene_instances_ui_scene_example.webp

Щоб отримати вузол AnimationPlayer, слід скористатися наступним кодом.

var animation_player

func _ready():
    animation_player = get_node("ShieldBar/AnimationPlayer")

Примітка

Як і у випадку шляхів до файлів, ви можете використовувати «..», щоб отримати батьківський вузол. Найкраще уникати цього, хоча й не порушувати інкапсуляцію. Ви також можете починати шлях із косої риски, щоб зробити його абсолютним. У цьому випадку ваш верхній вузол буде «/root», попередньо визначене кореневе вікно перегляду програми.

Синтаксичний цукор

Щоб скоротити свій код у GDScript, можна використовувати два скорочення. По-перше, розміщення анотації @onready перед змінною-членом ініціалізує її безпосередньо перед зворотним викликом _ready().

@onready var sprite2d = get_node("Sprite2D")

Існує також коротке позначення для get_node(): знак долара, "$". Ви розміщуєте його перед назвою або шляхом до вузла, який хочете отримати.

@onready var sprite2d = $Sprite2D
@onready var animation_player = $ShieldBar/AnimationPlayer

Створення вузлів

Щоб створити вузол з коду, викличте його метод new(), як і для будь-якого іншого типу даних, заснованого на класі.

Ви можете зберегти посилання на щойно створений вузол у змінній і викликати add_child(), щоб додати його як дочірнього вузла, до якого ви прикріпили скрипт.

var sprite2d

func _ready():
    sprite2d = Sprite2D.new() # Create a new Sprite2D.
    add_child(sprite2d) # Add it as a child of this node.

Щоб видалити вузол і звільнити його з пам’яті, ви можете викликати його метод queue_free(). Це поставить вузол у чергу на видалення в кінці поточного кадру після завершення його обробки. У цей момент механізм видаляє вузол зі сцени та звільняє об’єкт у пам’яті.

sprite2d.queue_free()

Перед викликом sprite2d.queue_free() дерево віддаленої сцени виглядає так.

../../_images/nodes_and_scene_instances_remote_tree_with_sprite.webp

Після того як механізм звільнив вузол, дерево віддаленої сцени більше не відображає спрайт.

../../_images/nodes_and_scene_instances_remote_tree_no_sprite.webp

Як альтернативу, ви можете викликати функцію free(), щоб негайно знищити вузол. Робіть це з обережністю, оскільки будь-яке посилання на нього миттєво стане недійсним. Ми рекомендуємо використовувати функцію queue_free(), якщо ви не впевнені, що робите.

Коли ви звільняєте вузол, він також звільняє всіх своїх дітей. Завдяки цьому, щоб видалити цілу гілку дерева сцени, вам потрібно звільнити лише самий верхній батьківський вузол.

Створення екземплярів сцен

Сцени — це шаблони, на основі яких можна створювати скільки завгодно копій. Ця операція називається інстанціюванням, і її виконання за допомогою коду відбувається у два етапи:

  1. Завантажуємо сцену з локального диска.

  2. Створення екземпляра завантаженого ресурсу PackedScene.

var scene = load("res://my_scene.tscn")

Попереднє завантаження сцени може покращити роботу користувача, оскільки операція завантаження відбувається, коли компілятор читає скрипт, а не під час виконання. Ця функція доступна лише з GDScript.

var scene = preload("res://my_scene.tscn")

У цей момент scene є ресурсом упакованої сцени, а не вузлом. Щоб створити власне вузол, вам потрібно викликати PackedScene.instantiate(). Він повертає дерево вузлів, яке ви можете використовувати як дочірнє до поточного вузла.

var instance = scene.instantiate()
add_child(instance)

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