Створення додатків

Про плагіни

Плагін — це чудовий спосіб розширити редактор корисними інструментами. Його можна створити повністю за допомогою GDScript і стандартних сцен, навіть не перезавантажуючи редактор. На відміну від модулів, вам не потрібно ні створювати код C++, ні перекомпілювати механізм. Хоча це робить плагіни менш потужними, з ними можна робити багато речей. Зауважте, що плагін подібний до будь-якої сцени, яку ви вже можете створити, за винятком того, що він створюється за допомогою сценарію для додавання функцій редактора.

Цей підручник допоможе вам створити два плагіни, щоб ви могли зрозуміти, як вони працюють, і розробити свій власний. Перший — це настроюваний вузол, який можна додати до будь-якої сцени в проекті, а інший — настроювана док-станція, додана до редактора.

Створення плагіна

Перш ніж почати, створіть новий порожній проект, де завгодно. Це буде основою для розробки та тестування плагінів.

Перше, що вам потрібно для того, щоб редактор визначив новий плагін, це створити два файли: plugin.cfg для конфігурації та скрипт інструменту з функціональністю. Плагіни мають стандартний шлях, наприклад addons/plugin_name у папці проекту. Godot надає діалогове вікно для створення цих файлів і розміщення їх там, де вони мають бути.

На головній панелі інструментів натисніть випадаючий список Проект. Потім натисніть Налаштування проекту.... Перейдіть на вкладку Плагіни і натисніть кнопку Create New Plugin у верхньому правому куті.

Ви побачите діалогове вікно, ось так:

../../../_images/making_plugins-create_plugin_dialog.webp

Текст покажчика місця заповнення в кожному полі описує, як він впливає на створення плагіном файлів і значень конфігураційного файлу.

Щоб продовжити приклад, використовуйте такі значення:

Plugin Name: My Custom Node
Subfolder: my_custom_node
Description: A custom node made to extend the Godot Engine.
Author: Your Name Here
Version: 1.0.0
Language: GDScript
Script Name: custom_node.gd
Activate now: No

Plugin Name: My Custom Node
Subfolder: MyCustomNode
Description: A custom node made to extend the Godot Engine.
Author: Your Name Here
Version: 1.0.0
Language: C#
Script Name: CustomNode.cs
Activate now: No

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

Зніміть прапорець Активувати зараз? у C# завжди потрібно, оскільки, як і будь-який інший скрипт C#, скрипт EditorPlugin потрібно скомпілювати, що вимагає створення проекту. Після створення проекту плагін можна ввімкнути на вкладці Плагіни Налаштування проекту.

Ви маєте отримати таку структуру каталогу:

../../../_images/making_plugins-my_custom_mode_folder.webp

plugin.cfg — це INI-файл із метаданими про ваш плагін. Назва та опис допомагають людям зрозуміти, що він робить. Ваше ім’я допомагає вам належним чином оцінити вашу роботу. Номер версії допомагає іншим знати, чи є у них застаріла версія; якщо ви не впевнені, як знайти номер версії, перегляньте Семантичне керування версіями. Основний файл сценарію вкаже Godot, що ваш плагін робить у редакторі, коли він активний.

Файл сценарію

Після створення плагіна діалогове вікно автоматично відкриє для вас скрипт EditorPlugin. Скрипт має дві вимоги, які ви не можете змінити: він має бути скриптою @tool, інакше він не завантажуватиметься належним чином у редакторі, і він має успадкувати від EditorPlugin.

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

Окрім сценарію EditorPlugin, будь-який інший GDScript, який використовує ваш плагін, має також бути інструментом. Будь-який GDScript без @tool, який використовується редактором, діятиме як порожній файл!

Важливо мати справу з ініціалізацією та очищенням ресурсів. Хорошою практикою є використання віртуальної функції _enter_tree() для ініціалізації вашого плагіна та _exit_tree() для його очищення. На щастя, діалог генерує ці зворотні виклики для вас. Ваш скрипт має виглядати приблизно так:

@tool
extends EditorPlugin


func _enter_tree():
    # Initialization of the plugin goes here.
    pass


func _exit_tree():
    # Clean-up of the plugin goes here.
    pass

#if TOOLS
using Godot;

[Tool]
public partial class CustomNode : EditorPlugin
{
    public override void _EnterTree()
    {
        // Initialization of the plugin goes here.
    }

    public override void _ExitTree()
    {
        // Clean-up of the plugin goes here.
    }
}
#endif

Це хороший шаблон для створення нових плагінів.

Спеціальний вузол

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

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

Вузли, додані через EditorPlugin, є вузлами "CustomType". Хоча вони працюють з будь-якою мовою сценаріїв, вони мають менше функцій, ніж the Script Class system. Якщо ви пишете GDScript або NativeScript, ми рекомендуємо замість них використовувати Script Classes.

Щоб створити новий тип вузла, ви можете використати функцію add_custom_type() з класу EditorPlugin. Ця функція може додавати нові типи до редактора (вузли або ресурси). Однак перш ніж ви зможете створити тип, вам потрібен скрипт, який діятиме як логіка для цього типу. Хоча цей скрипт не обов’язково має використовувати анотацію @tool, її можна додати, щоб скрипт запускався в редакторі.

Для цього підручника ми створимо кнопку, яка друкує повідомлення, якщо натиснути. Для цього нам знадобиться скрипт, який походить від Button. Він також може розширити BaseButton, якщо ви бажаєте:

@tool
extends Button


func _enter_tree():
    pressed.connect(clicked)


func clicked():
    print("You clicked me!")

using Godot;

[Tool]
public partial class MyButton : Button
{
    public override void _EnterTree()
    {
        Pressed += Clicked;
    }

    public void Clicked()
    {
        GD.Print("You clicked me!");
    }
}

Ось і все для нашої основної кнопки. Ви можете зберегти це як my_button.gd у папці плагіна. Вам також знадобиться піктограма 16×16 для відображення в дереві сцени. Якщо у вас його немає, ви можете отримати типовий логотип із механізму та зберегти його у папці addons/my_custom_node як icon.png або використати типовий логотип Godot (preload("res://) icon.svg")).

Порада

Зображення SVG, які використовуються як користувацькі піктограми вузлів, повинні мати Редактор > Масштабувати за допомогою масштабу редактора та Редактор > Перетворити кольори за допомогою теми редактора import options. Це дозволяє піктограмам відповідати параметрам масштабу та тематики редактора, якщо піктограми розроблено з тією ж палітрою кольорів, що й власні піктограми Godot.

Тепер нам потрібно додати його як спеціальний тип, щоб він відображався в діалоговому вікні Створити новий вузол. Для цього змініть скрипт custom_node.gd на такий:

@tool
extends EditorPlugin


func _enter_tree():
    # Initialization of the plugin goes here.
    # Add the new type with a name, a parent type, a script and an icon.
    add_custom_type("MyButton", "Button", preload("my_button.gd"), preload("icon.png"))


func _exit_tree():
    # Clean-up of the plugin goes here.
    # Always remember to remove it from the engine when deactivated.
    remove_custom_type("MyButton")

#if TOOLS
using Godot;

[Tool]
public partial class CustomNode : EditorPlugin
{
    public override void _EnterTree()
    {
        // Initialization of the plugin goes here.
        // Add the new type with a name, a parent type, a script and an icon.
        var script = GD.Load<Script>("res://addons/MyCustomNode/MyButton.cs");
        var texture = GD.Load<Texture2D>("res://addons/MyCustomNode/Icon.png");
        AddCustomType("MyButton", "Button", script, texture);
    }

    public override void _ExitTree()
    {
        // Clean-up of the plugin goes here.
        // Always remember to remove it from the engine when deactivated.
        RemoveCustomType("MyButton");
    }
}
#endif

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

Потім спробуйте, додавши свій новий вузол:

../../../_images/making_plugins-custom_node_create.webp

Коли ви додаєте вузол, ви бачите, що до нього вже приєднано створений вами скрипт. Встановіть текст на кнопку, збережіть і запустіть сцену. Коли ви натискаєте кнопку, ви можете побачити певний текст у консолі:

../../../_images/making_plugins-custom_node_console.webp

Спеціальний док

Іноді вам потрібно розширити редактор і додати інструменти, які завжди доступні. Простий спосіб зробити це – додати нову док-станцію з плагіном. Доки — це просто сцени на основі Control, тому вони створюються подібно до звичайних сцен GUI.

Створення настроюваного дока виконується так само, як настроюваний вузол. Створіть новий файл plugin.cfg у папці addons/my_custom_dock, а потім додайте до нього такий вміст:

[plugin]

name="My Custom Dock"
description="A custom dock made so I can learn how to make plugins."
author="Your Name Here"
version="1.0"
script="custom_dock.gd"

[plugin]

name="My Custom Dock"
description="A custom dock made so I can learn how to make plugins."
author="Your Name Here"
version="1.0"
script="CustomDock.cs"

Потім створіть скрипт custom_dock.gd у тій же папці. Заповніть його template we've seen before, щоб добре почати.

Оскільки ми намагаємося додати нову спеціальну док-станцію, нам потрібно створити вміст док-станції. Це не що інше, як стандартна сцена Godot: просто створіть нову сцену в редакторі, а потім відредагуйте її.

Для док-станції редактора кореневий вузол має бути Control або одним із його дочірніх класів. Для цього підручника ви можете створити одну кнопку. Ім’я кореневого вузла також буде ім’ям, яке з’явиться на вкладці док-станції, тому обов’язково вкажіть йому коротке й описове ім’я. Крім того, не забудьте додати текст до вашої кнопки.

../../../_images/making_plugins-my_custom_dock_scene.webp

Збережіть цю сцену як my_dock.tscn. Тепер нам потрібно захопити створену сцену, а потім додати її як док-станцію в редакторі. Для цього ви можете покластися на функцію add_control_to_dock() з класу EditorPlugin.

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

@tool
extends EditorPlugin


# A class member to hold the dock during the plugin life cycle.
var dock


func _enter_tree():
    # Initialization of the plugin goes here.
    # Load the dock scene and instantiate it.
    dock = preload("res://addons/my_custom_dock/my_dock.tscn").instantiate()

    # Add the loaded scene to the docks.
    add_control_to_dock(DOCK_SLOT_LEFT_UL, dock)
    # Note that LEFT_UL means the left of the editor, upper-left dock.


func _exit_tree():
    # Clean-up of the plugin goes here.
    # Remove the dock.
    remove_control_from_docks(dock)
    # Erase the control from the memory.
    dock.free()

#if TOOLS
using Godot;

[Tool]
public partial class CustomDock : EditorPlugin
{
    private Control _dock;

    public override void _EnterTree()
    {
        _dock = GD.Load<PackedScene>("res://addons/MyCustomDock/MyDock.tscn").Instantiate<Control>();
        AddControlToDock(DockSlot.LeftUl, _dock);
    }

    public override void _ExitTree()
    {
        // Clean-up of the plugin goes here.
        // Remove the dock.
        RemoveControlFromDocks(_dock);
        // Erase the control from the memory.
        _dock.Free();
    }
}
#endif

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

Перевірка результатів

Настав час перевірити результати вашої роботи. Відкрийте Налаштування проекту та натисніть вкладку Плагіни. Ваш плагін має бути єдиним у списку.

../../../_images/making_plugins-project_settings.webp

Ви бачите, що плагін не ввімкнено. Щоб активувати плагін, установіть прапорець Увімкнути. Док-станція має стати видимою ще до того, як ви закриєте вікно налаштувань. Тепер у вас має бути спеціальна док-станція:

../../../_images/making_plugins-custom_dock.webp

Реєстрація автозавантажень/синглтонів у плагінах

Плагіни редактора можуть автоматично реєструвати autoloads, коли плагін увімкнено. Це також включає скасування реєстрації автозавантаження, коли плагін вимкнено.

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

Використовуйте наступний код, щоб зареєструвати синглтон із плагіна редактора:

@tool
extends EditorPlugin

# Replace this value with a PascalCase autoload name, as per the GDScript style guide.
const AUTOLOAD_NAME = "SomeAutoload"


func _enable_plugin():
    # The autoload can be a scene or script file.
    add_autoload_singleton(AUTOLOAD_NAME, "res://addons/my_addon/some_autoload.tscn")


func _disable_plugin():
    remove_autoload_singleton(AUTOLOAD_NAME)

#if TOOLS
using Godot;

[Tool]
public partial class MyEditorPlugin : EditorPlugin
{
    // Replace this value with a PascalCase autoload name.
    private const string AutoloadName = "SomeAutoload";

    public override void _EnablePlugin()
    {
        // The autoload can be a scene or script file.
        AddAutoloadSingleton(AutoloadName, "res://addons/MyAddon/SomeAutoload.tscn");
    }

    public override void _DisablePlugin()
    {
        RemoveAutoloadSingleton(AutoloadName);
    }
}
#endif

Використання підплагінів

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

Спочатку створіть усі плагіни та підплагіни як звичайні плагіни:

../../../_images/sub_plugin_creation.webp

Потім перемістіть підплагіни в основну папку плагінів:

Godot приховає підплагіни зі списку плагінів, щоб користувач не міг увімкнути або вимкнути їх. Натомість основний скрипт плагіна має вмикати та вимикати такі додаткові плагіни:

@tool
extends EditorPlugin

# The main plugin is located at res://addons/my_plugin/
const PLUGIN_NAME = "my_plugin"

func _enable_plugin():
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/node", true)
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/panel", true)

func _disable_plugin():
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/node", false)
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/panel", false)

Виходячи за рамки

Тепер, коли ви навчилися створювати базові плагіни, ви можете розширити редактор кількома способами. Багато функцій можна додати до редактора за допомогою GDScript; це потужний спосіб створення спеціалізованих редакторів без необхідності заглиблюватися в модулі C++.

Ви можете створити власні плагіни, щоб допомогти собі, і поділитися ними в Бібліотеці ресурсів, щоб люди могли отримати користь від вашої роботи.