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

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

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

Дивись також

Перегляньте підручник Створення екземплярів, щоб дізнатися про підхід 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")

private Sprite2D _sprite2D;
private Camera2D _camera2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = GetNode<Sprite2D>("Sprite2D");
    _camera2D = GetNode<Camera2D>("Camera2D");
}

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

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

Шляхи вузлів

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

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

../../_images/nodes_and_scene_instances_ui_scene_example.webp

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

var animation_player

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

private AnimationPlayer _animationPlayer;

public override void _Ready()
{
    base._Ready();

    _animationPlayer = GetNode<AnimationPlayer>("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.

private Sprite2D _sprite2D;

public override void _Ready()
{
    base._Ready();

    _sprite2D = new Sprite2D(); // Create a new Sprite2D.
    AddChild(_sprite2D); // Add it as a child of this node.
}

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

sprite2d.queue_free()

_sprite2D.QueueFree();

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

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

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

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

Інстансування сцени

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

Завантажуємо сцену з локального диска.
Створення екземпляра завантаженого ресурсу PackedScene.

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

var scene = GD.Load<PackedScene>("res://MyScene.tscn");

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

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

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

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

var instance = scene.Instantiate();
AddChild(instance);

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