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

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

Что такое Plugify?

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

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

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

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

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

1. Настроите структуру каталогов для вашего плагина.
2. Определите манифест плагина (файл .pplugin), чтобы зарегистрировать ваш плагин в экосистеме Plugify.
3. Напишете код на Python для вашего плагина, используя предоставленный API.
4. Запустите и протестируете ваш плагин.

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

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

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

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

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

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

• res/plugins/ – Основной каталог, где хранятся все плагины.
• python_example_plugin/ – У каждого плагина есть своя отдельная папка. Имя папки должно совпадать с именем файла .pplugin.
• python_example_plugin.py – Скрипт Python, содержащий код плагина.
• python_example_plugin.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": "PythonExamplePlugin",
  "description": "Пример плагина на Python. Может использоваться как отправная точка при создании собственного плагина.",
  "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": "python_example_plugin.ExamplePlugin",
  "supportedPlatforms": [],
  "languageModule": {
    "name": "python3"
  },
  "dependencies": [],
  "exportedMethods": []
}

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

• entryPoint: Указывает путь к модулю и имя класса плагина. Например, если ваш плагин находится в python_example_plugin.py и класс называется ExamplePlugin, точкой входа будет python_example_plugin.ExamplePlugin.
• languageModule: Должно быть установлено в python3 для плагинов на Python.
• dependencies: Перечисляет другие требуемые плагины, обеспечивая правильный порядок загрузки.
• exportedMethods: Функции, предоставляемые плагином для внешнего взаимодействия.

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

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

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

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

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

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

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

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

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

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

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

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

Каждый плагин должен наследоваться от класса plugify.plugin.Plugin и опционально реализовывать методы жизненного цикла (plugin_start, plugin_update, plugin_end).

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

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

from plugify.plugin import Plugin

class ExamplePlugin(Plugin):
    def plugin_start(self):
        print("Python: OnPluginStart")

    def plugin_update(self, dt):
        print("Python: OnPluginUpdate")

    def plugin_end(self):
        print("Python: OnPluginEnd")

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

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

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

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

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

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

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

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

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

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

plg plugins

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

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

plg plugin python_example_plugin

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

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

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

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

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

Заключение

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