Аддоны/плагины

⚠️ Управление аддонами в Pano требует права доступа «Управление аддонами» (Addon Management).
Если вы не вошли в систему как администратор, у вас должно быть право доступа на управление аддонами, чтобы открыть страницу аддонов и выполнять связанные с ними действия.

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

В экосистеме Pano:

• Бэкенд называет их плагинами (модули на базе PF4J).
• Фронтенд / пользовательский интерфейс называет их аддонами (устанавливаемые расширения).

Независимо от названия, они представляют собой одну и ту же модульную систему, которая делает Pano мощной, гибкой и управляемой сообществом платформой.

🧩 Создание собственного аддона

Если вы разработчик и хотите создать свой собственный аддон, Pano предоставляет мощный и удобный API и систему жизненного цикла на базе PF4J.

Аддоны могут:

• Расширять бэкенд Pano новыми функциями или API.
• Добавлять пользовательские UI-компоненты в темы и панель на веб-сайте.
• Интегрироваться с данными сервера Minecraft, информацией об игроках или игровыми событиями.

Каждый аддон упаковывается в виде JAR-файла с дескриптором, который определяет его метаданные и зависимости.
Вы можете распространять свои аддоны публично через Pano Store или приватным образом на своих собственных серверах.

📘 Узнайте, как проектировать, собирать и публиковать аддоны здесь:
👉 Руководство по разработке аддонов →

💡 Почему аддоны важны

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

Аддоны важны, потому что они:

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

С аддонами ваша установка Pano развивается вместе с потребностями вашего сервера — от простых расширений веб-сайта до глубоких игровых интеграций.

⚙️ Как работают аддоны (под капотом)

Система аддонов Pano работает на базе PF4J — известного Java-фреймворка для плагинов.
Каждый аддон представляет собой автономный JAR-файл, который включает собственные метаданные, зависимости и обработчики жизненного цикла.

При запуске Pano:

1. Сканирует директорию плагинов (или путь, определенный с помощью -Dpf4j.pluginsDir).
2. Загружает и проверяет каждый обнаруженный JAR-файл аддона.
3. Зависимости между аддонами разрешаются автоматически (на основе объявленных plugin-id и dependencies).
4. Аддоны включаются или выключаются на основе конфигурации PF4J и внутреннего менеджера аддонов Pano.

По умолчанию, если вы не укажете пользовательский путь:

java -jar Pano-<version>.jar

Pano автоматически создаст и будет использовать директорию plugins/ в той же папке, что и ваш JAR-файл.

Вы можете переопределить эту директорию с помощью:

java -Dpf4j.pluginsDir=/path/to/custom/plugins -jar Pano-<version>.jar

📦 Установка аддонов

Существует два способа установки аддонов:

1. С вашего локального компьютера

1. Откройте страницу Панель администратора → Аддоны.
2. Нажмите Install Addon — появится модальное окно.
3. Либо перетащите ваш JAR-файл аддона, либо нажмите Select File, чтобы загрузить его вручную.
4. Дождитесь завершения установки — ваш новый аддон появится в списке.

2. Из Pano Store

1. В том же окне Install Addon нажмите Browse Store.
2. Найдите аддон, который хотите использовать — бесплатный или платный.
3. Нажмите Install.
4. После завершения установки он автоматически станет доступен в вашем списке аддонов.

Вы можете изучать новые аддоны, покупать премиум-версии или обновлять существующие — всё это напрямую в Pano Store.

🧩 Для использования Маркетплейса требуется привязанный аккаунт Pano.

⚠️ Любой аддон, не проверенный Pano, может быть небезопасен, используйте его на свой страх и риск!

🧰 Включение и выключение аддонов

Существует два метода включения или выключения аддонов:

1. С помощью PF4J (через файлы)

Внутри папки plugins/ PF4J хранит файлы метаданных, определяющие статус аддона.
Вы можете вручную отключить аддон, отредактировав или создав файл disabled.txt внутри его папки — но этот метод предназначен только для продвинутых пользователей.

2. Через панель администратора (рекомендуется)

Перейдите в раздел Панель → Аддоны и просто переключите тумблер аддона в положение Enable или Disable.
При выключении:

• Аддон остановится и больше не будет загружаться или работать.
• Любые зависимые аддоны также будут автоматически отключены.

При повторном включении:

• Все совместимые зависимые аддоны по возможности активируются снова.

💡 Если при включении аддона произошла ошибка, будут предоставлены логи ошибок. Ознакомьтесь с логами ошибок в консоли Pano для получения подробностей и сообщите об этом соответствующему разработчику.

⚠️ Откат версии аддонов (Downgrade)

Хотя технически это возможно, откат версии аддона (установка старой версии поверх новой) не рекомендуется.

Откат может привести к следующим последствиям:

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

Если вам всё же необходимо откатить версию, убедитесь, что у вас есть:

1. Полная резервная копия вашей базы данных и конфигурации.
2. Подтверждение совместимости со старой версией в документации.

💀 Действуйте только если вы абсолютно уверены — в противном случае может потребоваться переустановка Pano.

💡 Мы просим наших разработчиков аддонов учитывать возможность отката, но имейте в виду, что это не всегда может работать корректно!

🧩 Удаление аддонов

При удалении аддона:

• Любые аддоны, зависящие от него, также будут удалены автоматически.
• Это гарантирует стабильность системы и отсутствие «осиротевших» зависимостей.

Чтобы удалить:

1. Перейдите в раздел Панель → Аддоны.
2. Нажмите на аддон, чтобы перейти на его страницу подробностей, и нажмите кнопку Delete.
3. Подтвердите действие — зависимые аддоны будут перечислены перед удалением.

💡 Ожидается, что аддон сам очистит свои данные перед удалением. Однако имейте в виду, что возможны остаточные файлы!

🔍 Обзор директории аддонов

Пример файловой структуры для Pano и аддонов:

/pano/
├── Pano-1.0.0.jar
├── config.conf
├── plugins/
│    ├── disabled.txt (необязательно)
│    ├── pano-announcements-plugin/
│    │     └── plugin.conf
│    ├── pano-auth-integrations-plugin/
│    │     └── plugin.conf
│    ├── pano-announcements-plugin.jar
│    ├── pano-auth-integrations-plugin.jar
│    └── pano-feedback-plugin.jar
├── themes/
└── file-uploads/

🧠 Резюме

Действие	Расположение	Рекомендуемый метод
Установка (локально)	Панель → Аддоны → Установить аддон	Перетаскивание или выбор файла
Установка (магазин)	Панель → Аддоны → Установить аддон → Browse Store	Нажать install
Включить / Выключить	Панель → Аддоны	Переключатель
Удалить аддон	Панель → Аддоны	Удаление с подтверждением
Сменить папку плагинов	Опция JVM	-Dpf4j.pluginsDir=/путь/к/папке

🧩 Продвинутые примечания

• Аддоны могут предоставлять как логику бэкенда, так и компоненты фронтенда через API платформы.
• Некоторые аддоны регистрируют пользовательские маршруты, API-эндпоинты или UI-виджеты.
• Если вы столкнулись с конфликтами или отсутствующими зависимостями, проверьте папку logs на наличие сообщений об ошибках PF4J.

🪄 Аддоны — это то, что делает Pano живым — они превращают вашу установку в настраиваемую, постоянно расширяемую платформу, которая растет вместе с вашим сообществом.