Creating Plugins

В этом разделе вы узнаете, как создавать собственные плагины для Wudgine, начиная с базовой структуры и заканчивая продвинутыми возможностями.

Структура плагина

Каждый плагин Wudgine должен соответствовать определенной структуре:

MyPlugin/
├── include/
│   └── MyPlugin/
│       ├── MyPluginComponent.h
│       └── MyPlugin.h
├── src/
│   ├── MyPluginComponent.cpp
│   └── MyPlugin.cpp
├── resources/
│   └── icons/
├── CMakeLists.txt
└── plugin.json

Файл манифеста плагина

Каждый плагин должен содержать файл plugin.json, который описывает его основные характеристики:

{
  "name": "MyAwesomePlugin",
  "version": "1.0.0",
  "author": "Ваше имя",
  "description": "Описание вашего плагина",
  "category": "Gameplay",
  "dependencies": [
    {
      "name": "OtherPlugin",
      "version": ">=1.0.0"
    }
  ],
  "entryPoint": "MyAwesomePlugin::MyPlugin",
  "editorOnly": false,
  "runtimeOnly": false
}

Создание базового плагина

Для создания базового плагина необходимо:

Создать класс, наследующийся от Wudgine::Plugin::IPlugin
Реализовать необходимые методы жизненного цикла
Зарегистрировать плагин в системе

#pragma once

#include "Wudgine/Plugin/IPlugin.h"

namespace MyAwesomePlugin {

class MyPlugin : public Wudgine::Plugin::IPlugin {
public:
    MyPlugin();
    virtual ~MyPlugin();

    // Методы жизненного цикла
    bool Initialize() override;
    void Shutdown() override;
    
    // Информация о плагине
    const char* GetName() const override { return "MyAwesomePlugin"; }
    const char* GetVersion() const override { return "1.0.0"; }
    const char* GetAuthor() const override { return "Ваше имя"; }
    const char* GetDescription() const override { return "Описание вашего плагина"; }

private:
    // Приватные члены плагина
};

} // namespace MyAwesomePlugin

// Макрос для регистрации плагина
WUDGINE_REGISTER_PLUGIN(MyAwesomePlugin::MyPlugin)

#include "MyPlugin/MyPlugin.h"
#include "Wudgine/Core/Log.h"

namespace MyAwesomePlugin {

MyPlugin::MyPlugin() {
    // Конструктор
}

MyPlugin::~MyPlugin() {
    // Деструктор
}

bool MyPlugin::Initialize() {
    WG_LOG_INFO("MyAwesomePlugin инициализирован");
    
    // Регистрация компонентов, систем и т.д.
    
    return true;
}

void MyPlugin::Shutdown() {
    WG_LOG_INFO("MyAwesomePlugin завершает работу");
    
    // Освобождение ресурсов
}

} // namespace MyAwesomePlugin

Добавление компонентов

Плагины часто добавляют новые компоненты для игровых объектов:

#pragma once

#include "Wudgine/ECS/Component.h"
#include "Wudgine/Core/Serializable.h"

namespace MyAwesomePlugin {

class MyPluginComponent : public Wudgine::ECS::Component, public Wudgine::Core::Serializable {
public:
    MyPluginComponent();
    virtual ~MyPluginComponent();

    // Сериализация
    void Serialize(Wudgine::Core::Archive& archive) override;
    void Deserialize(Wudgine::Core::Archive& archive) override;

    // Свойства компонента
    float GetValue() const { return m_value; }
    void SetValue(float value) { m_value = value; }

private:
    float m_value = 0.0f;
};

} // namespace MyAwesomePlugin

#include "MyPlugin/MyPluginComponent.h"

namespace MyAwesomePlugin {

MyPluginComponent::MyPluginComponent() {
    // Инициализация
}

MyPluginComponent::~MyPluginComponent() {
    // Очистка
}

void MyPluginComponent::Serialize(Wudgine::Core::Archive& archive) {
    archive << m_value;
}

void MyPluginComponent::Deserialize(Wudgine::Core::Archive& archive) {
    archive >> m_value;
}

} // namespace MyAwesomePlugin

// В методе Initialize() вашего плагина
bool MyPlugin::Initialize() {
    // Регистрация компонента в системе ECS
    Wudgine::ECS::ComponentRegistry::GetInstance().RegisterComponent<MyPluginComponent>(
        "MyPluginComponent",
        []() -> Wudgine::ECS::Component* { return new MyPluginComponent(); }
    );
    
    return true;
}

Настройка сборки плагина

Для сборки плагина используется CMake:

cmake_minimum_required(VERSION 3.14)
project(MyAwesomePlugin VERSION 1.0.0)

# Настройка C++
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Поиск Wudgine
find_package(Wudgine REQUIRED)

# Исходные файлы
set(SOURCES
    src/MyPlugin.cpp
    src/MyPluginComponent.cpp
)

# Заголовочные файлы
set(HEADERS
    include/MyPlugin/MyPlugin.h
    include/MyPlugin/MyPluginComponent.h
)

# Создание библиотеки плагина
add_library(${PROJECT_NAME} SHARED ${SOURCES} ${HEADERS})

# Включение директорий
target_include_directories(${PROJECT_NAME} 
    PUBLIC 
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    PRIVATE 
        ${CMAKE_CURRENT_SOURCE_DIR}/src
)

# Связывание с Wudgine
target_link_libraries(${PROJECT_NAME} PRIVATE Wudgine::Core Wudgine::ECS)

# Копирование ресурсов
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
    ${CMAKE_CURRENT_SOURCE_DIR}/resources
    $<TARGET_FILE_DIR:${PROJECT_NAME}>/resources
)

# Копирование манифеста плагина
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy
    ${CMAKE_CURRENT_SOURCE_DIR}/plugin.json
    $<TARGET_FILE_DIR:${PROJECT_NAME}>/plugin.json
)

# Установка
install(TARGETS ${PROJECT_NAME}
    LIBRARY DESTINATION plugins
    RUNTIME DESTINATION plugins
)
install(FILES plugin.json DESTINATION plugins/${PROJECT_NAME})
install(DIRECTORY resources/ DESTINATION plugins/${PROJECT_NAME}/resources)

Советы по разработке плагинов

Следуйте соглашениям — придерживайтесь стиля кодирования Wudgine
Минимизируйте зависимости — делайте плагин максимально автономным
Обрабатывайте ошибки — всегда проверяйте возвращаемые значения и обрабатывайте исключения
Документируйте код — добавляйте комментарии и документацию к публичным API
Пишите тесты — создавайте модульные тесты для проверки функциональности

Отладка плагинов

Для отладки плагинов можно использовать:

Логирование — используйте макросы WG_LOG_* для вывода информации
Отладочные инструменты — добавляйте визуализацию в редакторе
Профилирование — используйте встроенные инструменты профилирования

// Пример использования логирования
WG_LOG_INFO("Плагин инициализирован");
WG_LOG_WARNING("Внимание: {}", "потенциальная проблема");
WG_LOG_ERROR("Ошибка: не удалось загрузить ресурс {}", resourcePath);

// Пример использования профилирования
{
    WG_PROFILE_SCOPE("МояФункция");
    // Код для профилирования
}

Что дальше?

Теперь, когда вы знаете, как создавать плагины, вы можете:

Изучить API плагинов более подробно
Посмотреть примеры готовых плагинов
Узнать, как публиковать свои плагины

Создание плагинов — отличный способ расширить возможности Wudgine и поделиться своими решениями с сообществом!

Overview

Plugin Api

Documentation

Creating Plugins