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

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

Про плагіни

Плагін — це чудовий спосіб розширити редактор корисними інструментами. Його можна створити повністю за допомогою 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

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

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

У 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

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

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

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

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

# Optional, add to execute in the editor.
@tool

# Icons are optional.
# Alternatively, you may use the UID of the icon or the absolute path.
@icon("icon.svg")

# Automatically register the node in the Create New Node dialog
# and make it available for use with other scripts.
class_name MyButton
extends Button


func _enter_tree():
    pressed.connect(clicked)


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

using Godot;

// Optional, add to execute in the editor.
[Tool]

// Icons are optional.
// Alternatively, you may use the UID of the icon or the absolute path.
[Icon("icon.svg")]

// Automatically register the node in the Create New Node dialog
// and make it available for use with other scripts.
[GlobalClass]
public partial class MyButton : Button
{
    public override void _EnterTree()
    {
        Pressed += Clicked;
    }

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

That's it for our basic button. You can save this as my_button.gd inside the plugin folder. You may have a 16×16 icon to show in the scene tree. If you don't have one, you can grab the default one from the engine and save it in your addons/my_custom_node folder as icon.svg, or use the default Godot logo (@icon("res://icon.svg")).

Порада

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

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

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

../../../_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_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.
    var dock_scene = preload("res://addons/my_custom_dock/my_dock.tscn").instantiate()

    # Create the dock and add the loaded scene to it.
    dock = EditorDock.new()
    dock.add_child(dock_scene)

    dock.title = "My Dock"

    # Note that LEFT_UL means the left of the editor, upper-left dock.
    dock.default_slot = DOCK_SLOT_LEFT_UL

    # Allow the dock to be on the left or right of the editor, and to be made floating.
    dock.available_layouts = EditorDock.DOCK_LAYOUT_VERTICAL | EditorDock.DOCK_LAYOUT_FLOATING

    add_dock(dock)


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

#if TOOLS
using Godot;

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

    public override void _EnterTree()
    {
        var _dock_scene = GD.Load<PackedScene>("res://addons/MyCustomDock/MyDock.tscn").Instantiate<Control>();

        // Create the dock and add the loaded scene to it.
        _dock = new EditorDock();
        _dock.AddChild(dock_scene);

        _dock.Title = "My Dock";

        // Note that LeftUl means the left of the editor, upper-left dock.
        _dock.DefaultSlot = DockSlot.LeftUl;

        // Allow the dock to be on the left or right of the editor, and to be made floating.
        _dock.AvailableLayouts = DockLayout.Horizontal | DockLayout.Floating;

        AddDock(_dock);
    }

    public override void _ExitTree()
    {
        // Clean-up of the plugin goes here.
        // Remove the dock.
        RemoveDock(_dock);
        // Erase the control from the memory.
        _dock.QueueFree();
    }
}
#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++.

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