Подготовка
Пора обустроить нашу мастерскую. К концу этой страницы Shoutbox станет настоящей папкой внутри вашей установки Pano, собранной в jar и перечисленной в Панель → Аддоны — с быстрым циклом «правь-и-обновляй», готовым для остальной части этого руководства.
Полный справочник по этой странице: С чего начать.
Шаг 0 — убедитесь, что Pano запущен (с включённым режимом разработки)
Аддон во время работы живёт внутри запущенного Pano. Поэтому прежде всего убедитесь, что ваш Pano установлен и запущен на вашей машине для разработки. Если нет, сначала выполните Установку и вернитесь сюда.
Для этого руководства мы будем считать, что вы запустили Pano в режиме разработки, который слушает порт 8088:
# in your Pano folder
java -jar Pano-v1.0.0.jar --dev(Без --dev порт по умолчанию — 80.) Держите его запущенным в отдельном терминале.
Теперь включите режим разработки — именно он заставляет ваши файлы UI и локалей перезагружаться вживую с диска, а не браться из кэша:
Панель → Настройки платформы → Режим разработки → Вкл, затем сохраните.
Контрольная точка
Вы можете открыть свой сайт Pano по адресу http://localhost:8088, войти в /panel и увидеть, что режим разработки показан как Вкл.
Шаг 1 — клонируйте шаблон в plugins/
Pano поставляется с готовым шаблоном pano-boilerplate-plugin, в котором бэкенд и UI уже связаны вместе. Клонируйте его в папку plugins/ вашей установки Pano — ту самую папку, где лежат jar-файл Pano и его конфигурация. Это важно: аддон горячо перезагружает свой UI только тогда, когда он находится внутри папки plugins/ запущенной установки.
Последний аргумент (pano-plugin-shoutbox) — это имя папки, и оно должно в точности совпадать с pluginId, который вы зададите на следующем шаге, потому что Pano связывает папку с идентификатором.
cd <your-pano-instance>/plugins
git clone https://github.com/PanoMC/pano-boilerplate-plugin.git pano-plugin-shoutbox
cd pano-plugin-shoutboxШаг 2 — переименуйте шаблон в Shoutbox
Шаблон называет себя pano-boilerplate-plugin в нескольких местах. Измените каждое. Пункты 1–3 все описывают один и тот же класс в трёх местах, поэтому они должны согласовываться друг с другом.
| # | Где | Что изменить |
|---|---|---|
| 1 | gradle.properties | pluginId → pano-plugin-shoutbox; pluginName → Shoutbox; pluginClass → com.panomc.plugins.shoutbox.ShoutboxPlugin; плюс pluginDescription, pluginDeveloper, pluginLicense, pluginSourceUrl, organization → на ваши собственные значения. |
| 2 | Папка Kotlin-пакета | Переименуйте src/main/kotlin/com/panomc/plugins/boilerplate → .../shoutbox, затем задайте строку package внутри .kt-файла как package com.panomc.plugins.shoutbox. |
| 3 | Главный класс Kotlin | Переименуйте класс BoilerplatePlugin → ShoutboxPlugin. Он должен совпадать с окончанием pluginClass из пункта 1. |
| 4 | src/main.js | Константу pluginId 'pano-boilerplate-plugin' → 'pano-plugin-shoutbox'; имя класса PanoExamplePlugin → ShoutboxUiPlugin. |
| 5 | package.json | "name" → pano-plugin-shoutbox. |
| 6 | settings.gradle.kts | Добавьте строку rootProject.name = "pano-plugin-shoutbox". |
Пусть IntelliJ сам переименует класс
pluginClass — это полное имя: пакет (путь папки со слэшами, заменёнными на точки) плюс имя класса. В IntelliJ щёлкните правой кнопкой по имени класса → Refactor → Rename, и IDE переименует файл и обновит каждую ссылку за вас. Полное пошаговое переименование — с точными сообщениями об ошибках, если две правки не согласуются, — в разделе С чего начать.
Ещё две вещи — это содержимое, а не проводка — измените их сейчас или в любой момент позже:
src/main/resources/locales/en-US.json— текст вашего UI (в шаблоне есть один ключ,hello-world).src/main/resources/logo.png— замените на свой логотип.
Шаг 3 — первая сборка
Из папки вашего аддона установите зависимости UI и соберите один раз:
bun install
./gradlew buildПервая сборка медленная — не отменяйте её
Первая сборка скачивает Gradle, внутренний набор инструментов Java и все зависимости. Она может несколько минут выглядеть зависшей. Это нормально.
Она завершается с BUILD SUCCESSFUL и создаёт jar по пути build/libs/pano-plugin-shoutbox-local-build.jar.
Если bun install завис на «Resolving…»
Остановите его с помощью Ctrl + C и выполните вместо этого bun install --backend=copyfile.
Шаг 4 — скопируйте jar на уровень выше и перезапустите
Pano обнаруживает jar-файлы только непосредственно в папке plugins/ установки — не во вложенной build/libs/ внутри вашего клона. Поэтому скопируйте свежесобранный jar на уровень выше:
cp build/libs/pano-plugin-shoutbox-local-build.jar .. # into the instance's plugins/ folderТеперь перезапустите Pano: нажмите Ctrl + C в терминале, где он запущен, затем запустите его снова точно так же, как раньше. Новые jar-файлы подхватываются только при загрузке.
Клон и jar — это две разные вещи
Теперь в plugins/ бок о бок живут две копии вашего аддона:
plugins/
├── pano-plugin-shoutbox/ ← your clone (source: UI + locales)
└── pano-plugin-shoutbox-local-build.jar ← the built jar Pano loadsjar — это бэкенд, который запускает Pano; папка питает живую перезагрузку UI и локалей, пока включён режим разработки. Обе прекрасно сосуществуют.
Шаг 5 — увидьте его в панели
Откройте Панель → Аддоны. В списке должен появиться Shoutbox. Это проверка «загрузился ли он?».
Аддона нет в списке?
Три обычные причины: jar не лежит непосредственно в plugins/ (всё ещё в build/libs/); вы не перезапустили Pano; или pluginClass не совпадает с вашим пакетом + именем класса. Проверьте лог сервера на ошибку загрузки плагина.
Теперь вы должны увидеть Shoutbox в списке аддонов. Половина-бэкенд загрузилась правильно — вы готовы к итерациям.
Шаг 6 — цикл разработки
Во время разработки вы почти никогда не запускаете полную ./gradlew build — она каждый раз пересобирает UI, а это медленно. Вместо этого используйте по одной команде на каждую половину, обе из папки вашего аддона.
Для работы над бэкендом (Kotlin) собирайте быстрый jar только с бэкендом, пропуская UI (-Pnoui означает «пропустить сборку UI»):
./gradlew build -PnouiДля работы над UI (Svelte) запустите наблюдатель и оставьте его работать — он пересобирает UI при каждом сохранении:
bun run devВот что именно нужно для каждого вида изменений:
| Что вы изменили | Как это увидеть |
|---|---|
Svelte UI (src/main.js, src/panel/**, src/theme/**) | Запущенный bun run dev + обновление браузера (F5) |
locales/*.json | При включённом режиме разработки — обновление браузера (F5) |
| Kotlin-код | ./gradlew build -Pnoui, скопировать jar в plugins/, затем перезапустить Pano |
gradle.properties, config.conf | Полная ./gradlew build, скопировать jar в plugins/, затем перезапустить |
Изменения в Kotlin требуют пересборки и перезапуска
Kotlin не горячий. Отключение и повторное включение аддона в панели не подхватывает новый код — сервер держит старый код в памяти, пока полный перезапуск не загрузит новый jar. UI и локали горячие в режиме разработки; Kotlin — никогда. Держите это разделение в голове, и остальная часть этого руководства будет ощущаться быстрой.
Shoutbox жив и загружен, и вы знаете, какие изменения горячие, а какие нет. Теперь давайте дадим ему память и API.
Далее: Бэкенд →