Первый плагин

Добро пожаловать в Руководство по разработке плагинов для языкового модуля C++ от Plugify. Это руководство проведет вас через процесс создания вашего первого плагина с использованием C++ в рамках фреймворка Plugify. Независимо от того, являетесь ли вы моддером игр, инженером-программистом или разработчиком плагинов, это руководство поможет вам понять основные концепции и шаги, необходимые для создания полнофункционального плагина.

Что такое Plugify?

Plugify — это модульный фреймворк для плагинов, который позволяет разработчикам расширять приложения путем динамической интеграции внешних плагинов. Он предоставляет структурированный подход к разработке плагинов с четкими указаниями по структуре плагинов, управлению зависимостями и предоставлению API.

Зачем использовать C++?

Языковой модуль C++ позволяет разработчикам создавать высокопроизводительные плагины с использованием C++. Используя динамические библиотеки (shared objects), разработчики могут расширять приложения, сохраняя при этом эффективность и гибкость. Plugify гарантирует, что ваш плагин гладко интегрируется с ядром фреймворка, следуя стандартизированной структуре плагинов и API.

Что вы узнаете

В этом руководстве вы:

1. Настроите структуру каталогов для вашего плагина.
2. Определите манифест плагина (файл .pplugin), чтобы зарегистрировать ваш плагин в экосистеме Plugify.
3. Напишете код на C++ для вашего плагина, используя предоставленный API.
4. Будете управлять зависимостями для обеспечения правильной инициализации плагина.
5. Скомпилируете и упакуете ваш плагин с помощью CMake.

К концу этого руководства у вас будет работающий плагин на C++, который можно загрузить во фреймворк Plugify. Давайте начнем!

Структура каталогов

Чтобы обеспечить бесшовную интеграцию с фреймворком Plugify, ваш плагин должен следовать определенной структуре каталогов. Каждый плагин должен быть размещен в своей собственной папке внутри каталога plugins/. Имя папки должно совпадать с именем плагина и следовать этим правилам:

1. Разрешенные символы: Буквенно-цифровые (A-Z, a-z, 0-9), специальные символы ($, #, @, -).
2. Пробелы НЕ допускаются в имени папки.
3. Файл конфигурации .pplugin должен иметь то же имя, что и папка плагина.

Пример структуры каталогов

Разбор структуры

• res/plugins/ – Основной каталог, где хранятся все плагины.
• plugin_name/ – У каждого плагина есть своя отдельная папка. Имя папки должно совпадать с именем файла .pplugin.
• bin/ – Этот подкаталог содержит скомпилированные бинарные файлы плагина (.dll для Windows, .so для Linux и т.д.).
• plugin_name.pplugin – Файл конфигурации, который определяет метаданные о плагине.

Следуя этой структуре, Plugify может корректно обнаруживать, загружать и управлять плагинами на разных платформах.

Манифест плагина

Каждый плагин во фреймворке Plugify требует файла манифеста с расширением .pplugin. Этот файл представляет собой конфигурацию на основе JSON, которая предоставляет важные метаданные о плагине, обеспечивая его правильную идентификацию, загрузку и управление.

Ключевые обязанности файла манифеста:

• Определяет версию плагина и данные автора.
• Указывает точку входа для выполнения.
• Перечисляет зависимости, требуемые плагином.
• Объявляет экспортируемые методы, доступные для внешнего взаимодействия.

Пример файла манифеста

{
  "$schema": "https://raw.githubusercontent.com/untrustedmodders/plugify/refs/heads/main/schemas/plugin.schema.json",
  "fileVersion": 1,
  "version": "0.1.0",
  "friendlyName": "PluginCPP",
  "description": "Пример плагина. Может использоваться как отправная точка при создании собственного плагина.",
  "createdBy": "untrustedmodders",
  "createdByURL": "https://github.com/untrustedmodders/",
  "docsURL": "https://github.com/orgs/untrustedmodders/README.md",
  "downloadURL": "https://github.com/orgs/untrustedmodders/example-repo.zip",
  "updateURL": "https://github.com/untrustedmodders/plugify/issues",
  "entryPoint": "bin/example_plugin",
  "supportedPlatforms": [],
  "languageModule": {
    "name": "cpp"
  },
  "dependencies": [],
  "exportedMethods": []
}

Объяснение ключевых полей

• entryPoint: Указывает местоположение скомпилированного бинарного файла плагина.
• languageModule: Должно быть установлено в cpp для плагинов на C++.
• dependencies: Перечисляет другие требуемые плагины, обеспечивая правильный порядок загрузки.
• exportedMethods: Функции, предоставляемые плагином для внешнего взаимодействия.

Почему файл манифеста важен?

• Обеспечивает совместимость – Определяет поддерживаемые версии и платформы.
• Обеспечивает модульность – Перечисляет зависимости для структурированной загрузки плагинов.
• Облегчает интеграцию – Позволяет другим плагинам вызывать предоставленные методы.

Следуя этой структуре манифеста, Plugify может эффективно загружать и управлять плагинами, обеспечивая бесшовную функциональность в разных проектах.

Написание кода плагина

Создание плагина для Plugify — это просто. Вы можете либо использовать готовый шаблон плагина на C++, доступный в нашем репозитории, либо написать свой плагин с нуля.

Использование шаблона плагина

Самый простой способ начать — это загрузить шаблон плагина на C++ из нашего репозитория. Он содержит все необходимые файлы, включая:

• Предварительно настроенную систему сборки
• Пример реализации
• Требуемые заголовочные файлы Plugify

Просто клонируйте репозиторий, и ваша среда будет готова к разработке.

Написание плагина с нуля

Если вы предпочитаете создавать свой плагин вручную, следуйте этим шагам:

Настройка вашего плагина

Каждый плагин должен реализовывать интерфейс IPluginEntry и предоставлять необходимые методы для того, чтобы Plugify мог его распознать и выполнить.

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

Вот базовый пример реализации плагина на C++:

#include <iostream>
#include <plugify/cpp_plugin.hpp>
#include <plugin_export.h>

class ExamplePlugin : public plg::IPluginEntry {
public:
    void OnPluginStart() override {
        std::cout << "Example Start!" << std::endl;
    }
    
    void OnPluginUpdate(float dt) override {
        std::cout << "Example Update!" << std::endl;
    }
    
    void OnPluginEnd() override {
        std::cout << "Example End!" << std::endl;
    }
} g_examplePlugin;

EXPOSE_PLUGIN(PLUGIN_API, &g_examplePlugin)

Понимание методов жизненного цикла плагина

Каждый плагин может определять следующие методы жизненного цикла, которые Plugify будет вызывать в определенное время:

Использование макроса Expose

Чтобы зарегистрировать ваш плагин в Plugify, вы должны использовать макрос EXPOSE_PLUGIN. Этот макрос:

• Определяет точку входа плагина.
• Связывает ваш экземпляр класса (g_examplePlugin) с системой Plugify.
• Гарантирует, что Plugify_Init, Plugify_PluginStart, Plugify_PluginUpdate и Plugify_PluginEnd будут правильно предоставлены.

Включение заголовочных файлов Plugify

Чтобы упростить разработку плагинов, Plugify предоставляет набор заголовочных файлов в репозитории языкового модуля C++. Эти файлы можно найти в: includes/plugify/

Они содержат основные определения и утилиты, необходимые для взаимодействия с Plugify.

Заголовочный файл cpp_plugin.hpp предоставляет основную функциональность для написания плагинов. Он включает:

• Управление жизненным циклом плагина (OnPluginStart, OnPluginUpdate и т.д.).
• Доступ к метаданным плагина (GetName(), GetVersion() и т.д.).
• Обработку ресурсов плагина (FindResource() и т.д.).

Итог

• Используйте шаблон плагина на C++ для быстрого старта.
• Реализуйте интерфейс IPluginEntry для определения поведения плагина.
• Предоставьте ваш плагин, используя макрос EXPOSE_PLUGIN.
• Используйте заголовочные файлы Plugify из папки includes/plugify/ для доступа к необходимым утилитам.

Следуя этим шагам, у вас будет полнофункциональный плагин Plugify, готовый к работе!

Управление зависимостями

Управление зависимостями в Plugify гарантирует, что плагины загружаются в правильном порядке на основе их зависимостей. Система использует топологическую сортировку для определения подходящей последовательности, предотвращая проблемы с инициализацией, когда плагины полагаются на другие плагины.

Как работают зависимости

Каждый плагин может объявлять свои зависимости в поле dependencies своего манифеста плагина (файла .pplugin). Ядро Plugify будет:

• Анализировать зависимости, перечисленные в манифесте каждого плагина.
• Сортировать плагины с помощью топологической сортировки, обеспечивая загрузку зависимостей перед зависимыми плагинами.
• Проверять совместимость платформ и запрашиваемые версии.

Представление зависимостей

Зависимости объявляются с использованием следующего формата JSON в поле dependencies манифеста плагина:

"dependencies": [
    {
        "name": "polyhook",
        "optional": false,
        "supportedPlatforms": ["windows", "linux"],
        "requestedVersion": "0.1.0"
    }
]

Объяснение полей

Пример плагина с зависимостями

Вот пример манифеста плагина (.pplugin), который объявляет несколько зависимостей:

{
  "version": "1.0.0",
  "friendlyName": "MyPlugin",
  "entryPoint": "bin/my_plugin",
  "dependencies": [
    {
      "name": "polyhook",
      "optional": false,
      "supportedPlatforms": ["windows", "linux"],
      "requestedVersion": "2.0.0"
    },
    {
      "name": "json-parser",
      "optional": true
    }
  ]
}

В этом примере:

• polyhook является обязательным и должен быть версии 2.0.0.
• json-parser является опциональным, что означает, что плагин все равно загрузится, даже если он отсутствует.

Как Plugify использует зависимости

1. Проверка зависимостей
   • Если обязательная зависимость отсутствует, плагин не загрузится.
   • Если опциональная зависимость отсутствует, плагин продолжит загрузку.
2. Соответствие версий
   • Если установлено requestedVersion, Plugify убедится, что зависимость соответствует или превышает эту версию.
   • Если requestedVersion опущено, Plugify загрузит любую доступную версию зависимости.
3. Совместимость платформ
   • Если установлено supportedPlatforms, Plugify проверит, поддерживается ли текущая ОС.
   • Если платформа не поддерживается, зависимость не будет загружена.

Ключевые выводы

1. Убедитесь, что обязательные зависимости доступны перед загрузкой вашего плагина.
2. Используйте optional: true для зависимостей, которые расширяют функциональность, но не являются критически важными.
3. Указывайте supportedPlatforms, если зависимость не является кроссплатформенной.
4. Определяйте requestedVersion, если ваш плагин требует определенную версию зависимости.

При правильном управлении зависимостями ваш плагин будет загружаться эффективно и избежит неожиданных сбоев из-за отсутствующих или несовместимых зависимостей.

Сборка плагина с помощью CMake

Чтобы собрать ваш плагин, вам нужна система сборки, которая компилирует исходный код в разделяемую библиотеку (.dll на Windows, .so на Linux и т.д.). Мы используем CMake в качестве нашей системы сборки из-за ее гибкости и кроссплатформенной поддержки.

Вы можете использовать любую современную IDE, которая поддерживает CMake, например:

• Visual Studio 2022 (Windows/Linux)
• CLion (кроссплатформенная)
• VS Code с расширением CMake Tools
• Командная строка с CMake и Ninja/Make

Настройка CMake

Создайте файл CMakeLists.txt в каталоге вашего проекта со следующим содержимым:

cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

if(POLICY CMP0092)
    cmake_policy(SET CMP0092 NEW) # Don't add -W3 warning level by default.
endif()

project(example_plugin VERSION 1.0.0.0 
    DESCRIPTION "C++ Example Plugin" 
    HOMEPAGE_URL "https://github.com/untrustedmodders/plugify-module-cpp/test/example_plugin" 
    LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

#
# Plugin Source Files
#
set(PLUGIN_SOURCES "plugin.cpp")

add_library(${PROJECT_NAME} SHARED ${PLUGIN_SOURCES})
target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})

# Compiler-specific warning flags
if(MSVC)
    target_compile_options(${PROJECT_NAME} PRIVATE /W4 /WX)
else()
    target_compile_options(${PROJECT_NAME} PRIVATE -Wextra -Wshadow -Wconversion -Wpedantic -Werror)
endif()

# Ensure compatibility on Linux
if(UNIX AND NOT APPLE)
    target_link_libraries(${PROJECT_NAME} PRIVATE -static-libstdc++ -static-libgcc)
endif()

target_compile_definitions(${PROJECT_NAME} PRIVATE
    PLUGIFY_IS_DEBUG=$<STREQUAL:${CMAKE_BUILD_TYPE},Debug>)

include(GenerateExportHeader)
generate_export_header(${PROJECT_NAME} EXPORT_MACRO_NAME PLUGIN_API EXPORT_FILE_NAME ${CMAKE_BINARY_DIR}/exports/plugin_export.h)
target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_BINARY_DIR}/exports)

Сборка плагина

mkdir build
cd build
cmake ..
cmake --build . --config Release

Ключевые выводы

1. CMake упрощает кроссплатформенную разработку плагинов
2. Вы можете использовать Visual Studio, CLion или любую IDE, совместимую с CMake
3. Используйте cmake --build . для компиляции вашего плагина из командной строки

Важное примечание для плагинов на Linux

Для некоторых игр мы рекомендуем статически линковать стандартную библиотеку C++ (STL) на Linux. Это помогает избежать потенциальных проблем с аллокаторами памяти, которые могут возникнуть, когда плагин динамически линкуется с другой версией рантайма C++, чем сам игровой движок.

Статическая линковка в CMake

Чтобы обеспечить статическую линковку STL, измените ваш CMakeLists.txt следующим образом:

if(UNIX AND NOT APPLE)
    target_link_libraries(${PROJECT_NAME} PRIVATE -static-libstdc++ -static-libgcc)
endif()

Зачем статическая линковка?

• Предотвращает конфликты между различными версиями STL, которые могут использовать игра и ваш плагин.
• Избегает несоответствия аллокаторов памяти, что может привести к сбоям или неожиданному поведению.
• Обеспечивает совместимость с различными дистрибутивами Linux, даже если у них разные рантаймы C++.

Это особенно важно для игровых движков, которые активно используют оптимизации выделения памяти.

Запуск и тестирование плагина

После того как вы собрали свой плагин, следующий шаг — запустить и протестировать его в системе Plugify. Для этого выполните следующие шаги:

Размещение плагина в правильном каталоге

Убедитесь, что ваш плагин правильно структурирован внутри папки plugins/. Ваш каталог плагина должен содержать:

Как только папка плагина и файл манифеста будут правильно размещены, Plugify автоматически обнаружит и попытается загрузить плагин.

Проверка статуса загрузки плагина

Вы можете проверить, успешно ли загрузился ваш плагин, используя команды терминала, предоставляемые Plugify. Эти команды позволяют вам запрашивать статус плагинов и устранять потенциальные проблемы.

• Перечислить все загруженные плагины:

plg plugins

Это отобразит все загруженные в данный момент плагины. Если ваш плагин есть в списке, это означает, что Plugify успешно его распознал и инициализировал.

• Запросить информацию о конкретном плагине:

plg plugin example_plugin

Эта команда получает подробную информацию о конкретном плагине, включая его версию, зависимости и поддерживаемые платформы.

Обработка сбоев при загрузке плагина

Если ваш менеджер плагинов не может загрузиться, Plugify предоставит сообщения об ошибках в консоли. Вы также можете явно запросить статус плагинов, используя:

plg list

Эта команда покажет, не удалось ли инициализировать плагин и, если да, предоставит причину (например, отсутствующие зависимости, неверная точка входа или ошибки времени выполнения).

Устранение неполадок

Если ваш плагин не работает как ожидалось:

• Проверьте логи консоли на наличие подробных сообщений об ошибках.
• Убедитесь, что все зависимости правильно установлены и совместимы с игрой/платформой.
• Проверьте точку входа в манифесте .pplugin, чтобы она соответствовала фактическому местоположению бинарного файла плагина.
• Включите отладочное логирование, если необходимо, чтобы получить больше деталей о проблеме.

Как только ваш плагин загрузится и будет функционировать правильно, он готов к использованию! Хотите дополнительную информацию о методах отладки?

Заключение

Это руководство охватило основные шаги по созданию плагина на C++ для языкового модуля C++, включая настройку проекта, написание кода плагина, настройку манифеста и сборку плагина с помощью CMake. Соблюдение этих рекомендаций обеспечивает гладкую интеграцию в экосистему Plugify.