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

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

Что такое Plugify?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "$schema": "https://raw.githubusercontent.com/untrustedmodders/plugify/refs/heads/main/schemas/plugin.schema.json",
  "fileVersion": 1,
  "version": "0.1.0",
  "friendlyName": "JavaScriptExamplePlugin",
  "description": "Пример плагина на JavaScript. Его можно использовать как отправную точку при создании собственного плагина.",
  "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": "js_example_plugin.ExamplePlugin",
  "supportedPlatforms": [],
  "languageModule": {
    "name": "javascript"
  },
  "dependencies": [],
  "exportedMethods": []
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { Plugin } from 'plugify';

export class ExamplePlugin extends Plugin {
    pluginStart() {
        console.log("JavaScript: OnPluginStart");
    }
    
    pluginUpdate(dt) {
        console.log("JavaScript: OnPluginUpdate");
    }
    
    pluginEnd() {
        console.log("JavaScript: OnPluginEnd");
    }
}

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

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

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

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

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

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

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

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

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

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

  
  Это отобразит все загруженные в данный момент плагины. Если ваш плагин есть в списке, это означает, что Plugify успешно его распознал и инициализировал.
• Запросить информацию о конкретном плагине:
  plg plugin js_example_plugin
  

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

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

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

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

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

Заключение

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