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

Можна вирішити це деякими обхідними шляхами, але вони мають свої обмеження:

Ви можете використовувати "майстер-сцену", яка завантажує та вивантажує інші сцени в вигляді своїх нащадків. Однак це означає, що ви більше не можете запускати ці сцени окремо і очікувати від них правильної роботи.
Інформація може бути збережена на диску в user://, а потім завантажена сценами, які цього потребують, але часте збереження та завантаження даних є громіздкими і може бути повільним.

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

Використовуючи цю концепцію, ви можете створювати об'єкти, які:

Завжди завантажуються, незалежно від того, яка сцена працює в даний момент.
Можуть зберігати глобальні змінні, наприклад інформацію про гравця.
Можуть працювати з переключенням сцен і переходами між сценами.
Діють як синглтон, оскільки архітектура GDScript не дозволяє підтримувати глобальні змінні.

Автозавантаження вузлів та скриптів може дати нам ці характеристики.

Примітка

Godot не зробить Autoload «справжнім» синглетоном відповідно до шаблону дизайну singleton. За бажання користувач все ще може створювати екземпляри кілька разів.

Порада

Якщо ви створюєте автозавантаження як частину плагіна редактора, спробуйте registering it automatically in the Project Settings, коли плагін увімкнено.

Автозавантаження

Ви можете створити автозавантаження для завантаження сцени або сценарію, який успадковує class_Node.

Примітка

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

Щоб автоматично завантажити сцену або скрипт, почніть із меню та перейдіть до Проект > Параметри проекту > Глобальні > Автозавантаження.

Тут ви можете додати будь-яку кількість сцен або сценаріїв. Кожному запису в списку потрібне ім’я, яке призначається як властивість name вузла. Порядком записів, які додаються до глобального дерева сцен, можна керувати за допомогою клавіш зі стрілками вгору/вниз. Як і звичайні сцени, механізм читатиме ці вузли в порядку зверху вниз.

Якщо стовпець Увімкнути позначено (це за замовчуванням), то до синглтона можна отримати доступ безпосередньо в GDScript:

PlayerVariables.health -= 10

Стовпець Enable не впливає на код C#. Однак, якщо синглтон є сценарієм C#, подібного ефекту можна досягти, включивши статичну властивість під назвою Instance і призначивши її в _Ready():

public partial class PlayerVariables : Node
{
    public static PlayerVariables Instance { get; private set; }

    public int Health { get; set; }

    public override void _Ready()
    {
        Instance = this;
    }
}

Це дозволяє отримати доступ до синглтона з коду C# без GetNode() і без приведення типу:

PlayerVariables.Instance.Health -= 10;

Зауважте, що до об'єктів автозавантаження (скриптів та/або сцени) доступ такий же, як і до будь-яких інших вузлів у дереві сцен. Насправді, якщо ви подивитесь на дерево запущеної сцени, ви побачите, що автоматично з'являються і завантажені вузли:

Попередження

Автозавантаження не можна видаляти за допомогою free() або queue_free() під час виконання, інакше система призведе до збою.

Користувацький перемикач сцени

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

Для початку завантажте шаблон звідси: singleton_autoload_starter.zip і відкрийте це в Godot.

Може з’явитися вікно зі сповіщенням про те, що проект востаннє відкривався в старішій версії Godot, але це не проблема. Натисніть Ok, щоб відкрити проект.

Проект містить дві сцени: scene_1.tscn і scene_2.tscn. Кожна сцена містить мітку з назвою сцени та кнопку з підключеним сигналом pressed(). Коли ви запускаєте проект, він запускається в scene_1.tscn. Однак натискання кнопки нічого не дає.

Створення сценарію

Відкрийте вікно Скрипт і створіть новий скрипт під назвою global.gd. Переконайтеся, що він успадковує від Node:

Наступний крок – додати цей скрипт до списку автозавантаження. Починаючи з меню, відкрийте Проект > Налаштування проєкту > Глобальні зміни > Автозавантаження та виберіть скрипт, натиснувши кнопку огляду або ввівши його шлях: res://global.gd. Натисніть Додати, щоб додати його до списку автозавантаження, та назвіть його "Глобальний", що потрібно для того, щоб скрипти мали до нього доступ під назвою "Глобальний":

Тепер, при запуску будь-якої сцени проєкту, цей скрипт завжди буде завантажений.

Повертаючись до сценарію, йому потрібно отримати поточну сцену у функції _ready(). І поточна сцена (та, що має кнопку), і global.gd є нащадками root, але автоматично завантажені вузли завжди перші. Це означає, що остання дочірня частина root завжди є завантаженою сценою.

extends Node

var current_scene = null

func _ready():
    var root = get_tree().root
    # Using a negative index counts from the end, so this gets the last child node of `root`.
    current_scene = root.get_child(-1)

using Godot;

public partial class Global : Node
{
    public Node CurrentScene { get; set; }

    public override void _Ready()
    {
        Viewport root = GetTree().Root;
        // Using a negative index counts from the end, so this gets the last child node of `root`.
        CurrentScene = root.GetChild(-1);
    }
}

Тепер нам потрібна функція для зміни сцени. Ця функція повинна звільнити поточну сцену та замінити її на запитувану.

func goto_scene(path):
    # This function will usually be called from a signal callback,
    # or some other function in the current scene.
    # Deleting the current scene at this point is
    # a bad idea, because it may still be executing code.
    # This will result in a crash or unexpected behavior.

    # The solution is to defer the load to a later time, when
    # we can be sure that no code from the current scene is running:

    _deferred_goto_scene.call_deferred(path)


func _deferred_goto_scene(path):
    # It is now safe to remove the current scene.
    current_scene.free()

    # Load the new scene.
    var s = ResourceLoader.load(path)

    # Instance the new scene.
    current_scene = s.instantiate()

    # Add it to the active scene, as child of root.
    get_tree().root.add_child(current_scene)

    # Optionally, to make it compatible with the SceneTree.change_scene_to_file() API.
    get_tree().current_scene = current_scene

public void GotoScene(string path)
{
    // This function will usually be called from a signal callback,
    // or some other function from the current scene.
    // Deleting the current scene at this point is
    // a bad idea, because it may still be executing code.
    // This will result in a crash or unexpected behavior.

    // The solution is to defer the load to a later time, when
    // we can be sure that no code from the current scene is running:

    CallDeferred(MethodName.DeferredGotoScene, path);
}

public void DeferredGotoScene(string path)
{
    // It is now safe to remove the current scene.
    CurrentScene.Free();

    // Load a new scene.
    var nextScene = GD.Load<PackedScene>(path);

    // Instance the new scene.
    CurrentScene = nextScene.Instantiate();

    // Add it to the active scene, as child of root.
    GetTree().Root.AddChild(CurrentScene);

    // Optionally, to make it compatible with the SceneTree.change_scene_to_file() API.
    GetTree().CurrentScene = CurrentScene;
}

Використовуючи Object.call_deferred (), друга функція запуститься лише після завершення всього коду з поточної сцени. Таким чином, поточна сцена не буде видалена під час її використання (тобто її код все ще працює).

Нарешті, нам потрібно заповнити порожні функції зворотного виклику в обох сценах:

# Add to 'scene_1.gd'.

func _on_button_pressed():
    Global.goto_scene("res://scene_2.tscn")

// Add to 'Scene1.cs'.

private void OnButtonPressed()
{
    var global = GetNode<Global>("/root/Global");
    global.GotoScene("res://Scene2.tscn");
}

і

# Add to 'scene_2.gd'.

func _on_button_pressed():
    Global.goto_scene("res://scene_1.tscn")

// Add to 'Scene2.cs'.

private void OnButtonPressed()
{
    var global = GetNode<Global>("/root/Global");
    global.GotoScene("res://Scene1.tscn");
}

Запустіть проєкт і перевірте, чи можете ви перемикатися між сценами при натисканні кнопки.

Примітка

Примітка: Коли сцен мало, перехід відбувається миттєво. Однак якщо ваші сцени складніші, для їх появи може знадобитися значна кількість часу. Щоб дізнатися, як впоратися з цим, дивіться наступний урок: Тло завантаження.

Як варіант, якщо час завантаження відносно короткий (менше 3 секунд, або близько того), ви можете відобразити "талицю завантаження", показавши якийсь 2D-елемент безпосередньо перед зміною сцени. Потім ви можете приховати її відразу після зміни сцени. Це може бути використано, щоб вказати гравцеві, що сцена завантажується.