Создайте свой первый аддон
Добро пожаловать в руководство по аддонам Pano. Это кулинарная книга: вместо того чтобы объяснять каждую возможность в отрыве от практики, мы вместе создаём один настоящий аддон — от готового шаблона до опубликованного аддона на Marketplace.
К концу вы проделаете каждый шаг сами хотя бы раз — и будете точно знать, куда смотреть, когда захотите копнуть глубже.
Справочник против руководства
Раздел Разработка аддонов — это справочник, он объясняет каждую тему в полном объёме. Это руководство — пошаговая сборка. Когда вам понадобится больше глубины по какому-то шагу, мы даём прямую ссылку на соответствующую страницу справочника. Ничто здесь ему не противоречит; мы просто проходим единственный, конкретный путь сквозь него.
Аддон и плагин — это одно и то же
Аддоны — это плагины Pano; на уровне кода во всех названиях используется слово plugin (PanoPlugin, pluginId и так далее). В тексте этого руководства мы говорим аддон, но в коде вы по-прежнему будете видеть plugin. Так и должно быть; ничего не переименовано.
Аддон, который мы создаём: Shoutbox
Знакомьтесь с нашим примером. Shoutbox — это крошечный аддон, который позволяет вашему сообществу оставлять короткие сообщения — «выкрики» (shouts) — на сайте вашего сервера. Что он делает:
- Посетители видят последние выкрики в небольшом виджете вверху главной страницы.
- Администраторы публикуют и удаляют выкрики из панели, что защищено правом доступа.
- Он несёт собственный текст, переведённый на каждый язык, на котором говорит ваш сервер.
Аддон — это единственный JAR-файл с двумя половинами, которые работают вместе:
- бэкенд на Kotlin, который выполняется внутри сервера Pano — ему принадлежат таблица базы данных, JSON-API и право доступа.
- UI на Svelte, который выполняется в браузере — виджет на главной странице и страница управления в панели.
Его идентичность, которую мы будем использовать на протяжении всего пути:
| Поле | Значение |
|---|---|
pluginId | pano-plugin-shoutbox |
pluginName | Shoutbox |
| Главный класс | com.panomc.plugins.shoutbox.ShoutboxPlugin |
pluginId — навсегда
Мы намеренно выбрали pano-plugin-shoutbox в качестве pluginId и никогда не изменим его после публикации — Pano зашивает его во множество мест за кулисами, и он же служит идентификатором вашего ресурса на Marketplace. Подробнее о том, где он используется, в разделе Настройка манифеста.
Что вам нужно
Здесь всё исходит из того, что Pano запущен на той же машине, где вы пишете код — ваш аддон во время работы живёт внутри этой установки.
| Что нужно | Что это такое |
|---|---|
| JDK версии 11 или новее | Запускает сборку Gradle. Подойдёт любая Java 11+ — сборка сама скачивает нужную ей внутреннюю Java. Проверьте командой java -version. |
| Bun | Устанавливает и собирает UI, а также запускает наблюдатель разработки. Скачайте с bun.sh. Проверьте командой bun --version. |
| Git | Скачивает шаблон. Проверьте командой git --version. |
| Запущенный Pano | Ваш аддон во время работы общается с живым Pano. Если у вас его ещё нет, сначала выполните Установку — и включите режим разработки (мы сделаем это на следующей странице). |
| Редактор кода | Подойдёт любой, но для Kotlin полноценная IDE избавит от боли — IntelliJ IDEA Community бесплатна и уже содержит файлы проекта из шаблона. |
Быть экспертом не нужно. Немного Kotlin и немного Svelte помогут, но каждый шаг здесь можно просто копировать и вставлять. Если хотите мягкое введение — руководство по Svelte превосходно и бесплатно.
План пути
Вот всё путешествие целиком. Каждый шаг — одна страница, и каждая страница заканчивается ссылкой на следующую.
- Подготовка — установите инструменты, клонируйте и переименуйте шаблон, соберите его и увидите Shoutbox в списке Панель → Аддоны.
- Бэкенд — дайте Shoutbox память и API: таблицу базы данных, JSON-эндпоинт и право доступа.
- Фронтенд — покажите выкрики на главной странице, затем добавьте страницу в панели для управления ими.
- Переводы — перенесите текст Shoutbox в файлы локалей и заговорите более чем на одном языке.
- Выпуск — соберите релизный jar, автоматизируйте версионирование и выпуски и опубликуйте на GitHub и Marketplace (с необязательным премиум-путём).
Готовы? Давайте обустроим нашу мастерскую.
Далее: Подготовка →