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

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

Что такое Plugify?

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

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

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

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

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

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

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

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

Чтобы обеспечить бесшовную интеграцию с фреймворком Plugify, поместите плагин в папку внутри каталога envs. Plugify читает манифесты (*.pplugin), лежащие в корне каждой папки в envs. Имя плагина берётся из поля name его манифеста и должно следовать этим правилам:

1. Должно начинаться с буквы или _ (A-Z, a-z, _).
2. Разрешённые символы: буквенно-цифровые (A-Z, a-z, 0-9), а также _. Используйте snake_case.
3. Пробелы и дефисы НЕ допускаются.
4. Называйте папку и файл .pplugin по имени плагина. Plugify этого не требует, но так структуру проще читать.

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

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

• addons/plugify/envs/ – Основной каталог, где хранятся все плагины.
• python_example_plugin/ – Плагин без пакета получает свою папку. Плагины, установленные через mamba, лежат вместе в папке envs/plugins.
• 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",
  "version": "0.1.0",
  "name": "python_example_plugin",
  "description": "Пример плагина на Python. Может использоваться как отправная точка при создании собственного плагина.",
  "author": "untrustedmodders",
  "website": "https://github.com/untrustedmodders/",
  "license": "MIT",
  "entry": "python_example_plugin.ExamplePlugin",
  "platforms": [],
  "language": "python3",
  "dependencies": [],
  "methods": [],
  "classes": []
}

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

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

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

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

Следуя этой структуре манифеста, 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. Для этого выполните следующие шаги:

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

Убедитесь, что ваш плагин правильно структурирован внутри папки envs. Папка плагина должна содержать манифест и файлы плагина, показанные выше.

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

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

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

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

plg plugins

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

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

plg plugin python_example_plugin

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

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

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

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

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

Заключение

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