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

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

Что такое Plugify?

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

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

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

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

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

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

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

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

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

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

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

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

• res/plugins/ – Основной каталог, где хранятся все плагины.
• plugin_name/ – У каждого плагина есть своя выделенная папка. Имя папки должно совпадать с именем файла .pplugin.
• bin/ – Эта подпапка содержит скомпилированные бинарные файлы плагина (.dll для всех платформ).
• 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": "PluginCSharp",
  "description": "Пример плагина на C#. Его можно использовать как отправную точку при создании собственного плагина.",
  "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/plugin_name.dll",
  "supportedPlatforms": [],
  "languageModule": {
    "name": "csharp"
  },
  "dependencies": [],
  "exportedMethods": []
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Каждый плагин должен наследоваться от класса Plugify.Plugin и опционально реализовывать методы жизненного цикла (OnPluginStart, OnPluginUpdate, OnPluginEnd).

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

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

using System;
using Plugify;

namespace ExamplePlugin
{
    public class SamplePlugin : Plugin
    {
        void OnPluginStart()
        {
            Console.WriteLine(".NET: OnStart");
        }

        void OnPluginUpdate(float dt)
        {
            Console.WriteLine(".NET: OnUpdate");
        }

        void OnPluginEnd()
        {
            Console.WriteLine(".NET: OnEnd");
        }
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы собрать ваш плагин, вам необходимо скомпилировать его в сборку .NET (.dll). Для этой цели вы можете использовать Visual Studio, Rider или VSCode.

Использование Visual Studio или Rider

1. Откройте ваш проект в Visual Studio или Rider.
2. Щелкните правой кнопкой мыши по проекту и выберите Собрать.
3. Скомпилированный файл .dll будет находиться в папке bin/Debug/net9.0 или bin/Release/net9.0.

Использование VSCode

1. Откройте терминал в каталоге вашего проекта.
2. Выполните следующую команду:
   dotnet build
   

3. Скомпилированный файл .dll будет находиться в папке bin/Debug/net9.0 или bin/Release/net9.0.

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

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

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

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

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

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

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

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

plg plugins

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

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

plg plugin example_plugin

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

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

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

plg list

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

Отладка проблем

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

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

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

Заключение

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