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

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

Что такое Plugify?

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

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

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

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

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

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

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

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

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

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

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

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

• res/extensions/ – Основной каталог, где хранятся все плагины.
• lua_example_plugin/ – У каждого плагина есть своя выделенная папка. Имя папки должно совпадать с именем файла .pplugin.
• lua_example_plugin.lua – Модуль Lua, содержащий код плагина.
• lua_example_plugin.pplugin – Файл конфигурации, который определяет метаданные о плагине.

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

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

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

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

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

Пример файла .pplugin

{
  "$schema": "https://raw.githubusercontent.com/untrustedmodders/plugify/refs/heads/main/schemas/plugin.schema.json",
  "version": "0.1.0",
  "name": "LuaExamplePlugin",
  "description": "Пример плагина на Lua. Его можно использовать как отправную точку при создании собственного плагина.",
  "author": "untrustedmodders",
  "website": "https://github.com/untrustedmodders/",
  "license": "MIT",
  "entry": "lua_example_plugin.ExamplePlugin",
  "platforms": [],
  "language": "lua",
  "dependencies": [],
  "methods": [],
  "classes": []
}

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

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

Почему важен файл .pplugin?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

local Plugin = require('plugify').Plugin

local ExamplePlugin = {}
ExamplePlugin.__index = ExamplePlugin
setmetatable(ExamplePlugin, {__index = Plugin})

function ExamplePlugin.new()
    local self = setmetatable({}, ExamplePlugin)
    return self
end

function ExamplePlugin:plugin_start()
    print("Lua: OnPluginStart")
end

function ExamplePlugin:plugin_update(dt)
    print("Lua: OnPluginUpdate - Delta time:", dt)
end

function ExamplePlugin:plugin_end()
    print("Lua: OnPluginEnd")
end

return ExamplePlugin

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

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

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

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

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

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

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

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

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

• Вывести список всех загруженных плагинов:

plg plugins

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

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

plg plugin lua_example_plugin

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

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

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

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

Как только ваш плагин загрузится и будет работать правильно, он готов к использованию. Если что-то пошло не так, см. руководство Отладка.

Заключение

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