Разработка Paper-плагинов: развёртывание окружения

Please, star this project for help autor

Гайд по настройке с нуля для Ubuntu и Windows.

Версии (Minecraft 26.2)

Компонент	Версия	Зачем
Minecraft	26.2	целевая версия
JDK	25	с 26.1 игра требует Java 25
Gradle	9.5.1	система сборки
Paper API	26.2.build.+	.+ тянет последнюю сборку
api-version	'26.2'	в plugin.yml

Что во что складывается: JDK компилирует код → Gradle собирает .jar → готовый плагин кладётся в папку plugins сервера Paper.

---

Часть 1. Ubuntu

Шаг 0. Тулчейн: JDK 25 + Gradle + VSCode

Ставим JDK и Gradle через SDKMAN — без root, без apt-репозиториев и GPG-ключей.

sudo apt update
sudo apt install -y curl zip unzip
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 25-tem
sdk install gradle
java -version
gradle -v

java -version → 25, gradle -v → Gradle 9.x на Java 25.

Редактор VSCode + расширения для Java:

sudo snap install code --classic
code --install-extension vscjava.vscode-java-pack
code --install-extension vscjava.vscode-gradle

Шаг 1. Папка проекта

cd exampleplugin

Раскладка (файлы сборки — в корне, код и ресурсы — в src/main/):

exampleplugin/
├── settings.gradle          ← корень
├── build.gradle             ← корень
└── src/main/
    ├── java/me/prankware/exampleplugin/ExamplePlugin.java
    └── resources/plugin.yml

Шаг 1. Сборка

Обёртку генерируешь один раз системным Gradle — дальше работаешь только через ./gradlew:

gradle wrapper
./gradlew build

Готовый .jar — в build/libs/. Проверить, что ресурсы упаковались:

unzip -l build/libs/*.jar | grep -E 'plugin.yml|config'

Обёртка (gradlew, gradle/wrapper/) коммитится в git вместе с кодом — сборка становится воспроизводимой без установки Gradle. В .gitignore добавь build/ и .gradle/, но саму обёртку не игнорируй.

Шаг 2. Локальный Paper-сервер

cd paper-test

Скачай Paper 26.2 с papermc.io (Downloads → Paper → 26.2) в папку paper-test. Файл называется с номером сборки, например paper-26.2-112.jar — запускай по реальному имени (или переименуй в paper.jar).

java -jar paper-26.2-112.jar --nogui

Первый запуск оборвётся на лицензии. Правим два файла:

sed -i 's/eula=false/eula=true/' eula.txt
sed -i 's/online-mode=true/online-mode=false/' server.properties

online-mode=false нужен для входа через TLauncher (offline-аккаунт) — только на локальном сервере, наружу такой не открывай.

Запускаем снова:

java -jar paper-26.2-112.jar --nogui

Дождись Done (...)! For help, type "help". Ставим плагин:

cp exampleplugin/build/libs/*.jar paper-test/plugins/

В консоли сервера stop, снова запускаешь — в логах ищи ExamplePlugin включён!.

Подключение: в TLauncher запусти ванильную 26.2 (Fabric не нужен, плагин серверный), Multiplayer → Add Server → localhost. Версия клиента и сервера обязана совпадать.

---

Часть 2. Windows

Всё в PowerShell. Код, структура и версии — идентичны Ubuntu; отличается только установка инструментов и синтаксис команд.

Шаг 0. Тулчейн: JDK 25 + Gradle + VSCode

JDK ставим через winget, Gradle — через Scoop.

winget install EclipseAdoptium.Temurin.25.JDK

Затем Scoop и Gradle:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install gradle

Scoop ставится под обычного пользователя — не запускай PowerShell от админа.

Закрой и открой PowerShell заново, потом проверь:

java -version
gradle -v

VSCode + расширения:

winget install Microsoft.VisualStudioCode
code --install-extension vscjava.vscode-java-pack
code --install-extension vscjava.vscode-gradle

Шаг 1. Сборка

На Windows обёртка вызывается как .\gradlew (с .\ и обратным слэшем):

gradle wrapper
.\gradlew build

.jar — в build\libs\. Проверить содержимое jar — через утилиту jar из JDK:

jar tf (Get-ChildItem build\libs\*.jar | Select-Object -First 1).FullName | Select-String "plugin.yml"

Шаг 2. Локальный Paper-сервер

Скачай Paper 26.2 с papermc.io в папку paper-test. Запускай по реальному имени файла с номером сборки:

java -jar .\paper-26.2-112.jar --nogui

Первый запуск оборвётся на лицензии. Правим файлы блокнотом:

notepad eula.txt          # eula=false → eula=true
notepad server.properties # online-mode=true → online-mode=false

Запускаем снова, ждём Done (...)! For help. Ставим плагин:

copy exampleplugin\build\libs\*.jar paper-test\plugins\

stop в консоли, запуск заново — ищи ExamplePlugin включён!. Подключение из TLauncher: ванильная 26.2, Multiplayer → Add Server → localhost, версии обязаны совпадать.

---

Частые ошибки

Реальные грабли, собранные в процессе, и как их обойти.

Ubuntu

gpg: no valid OpenPGP data found / Connection refused 127.0.0.1:12334 Apt-путь установки JDK через репозиторий Adoptium ломается на GPG-ключе (armored формат не для --dearmor) и на системном прокси. Решение: не связывайся с apt-репозиторием — ставь JDK через SDKMAN (Шаг 0).

E: Unable to locate package temurin-25-jdk Репозиторий Adoptium отключился из-за неподписанного ключа (следствие ошибки выше). Решение: тот же — SDKMAN.

Windows

winget install Gradle.Gradle → No package found matching input criteria В winget нет официального Gradle (winget search gradle показывает только сторонние gw, M2 Repo Cleaner). Решение: ставь Gradle через Scoop (Шаг 0).

Expand-Archive : .jar is not a supported archive file format Expand-Archive смотрит на расширение и отказывается трогать .jar. Решение: проверяй содержимое через jar tf ... (Шаг 2). Либо скопируй jar в .zip и распакуй.

Общие

Unable to access jarfile paper.jar Файл Paper называется с номером сборки (paper-26.2-112.jar), а не paper.jar. Решение: запускай по реальному имени (dir покажет) или переименуй.

The embedded resource 'config.yml' cannot be found in ...jar config.yml не попал в jar. Решение: он должен лежать строго в src/main/resources/; пересобери начисто ./gradlew clean build; проверь jar tf/unzip -l, что файл внутри.

VSCode красит весь код, хотя сборка проходит Это индексатор Java, а не проект — ./gradlew build собирает корректно. Решение: открой в VSCode именно папку проекта (где build.gradle) и доверься ей; Ctrl+Shift+P → «Java: Clean Java Language Server Workspace» → Reload; дождись окончания импорта в статус-баре. При необходимости пропиши JDK 25 в настройках (java.jdt.ls.java.home): на Ubuntu — ~/.sdkman/candidates/java/current, на Windows — C:\Program Files\Eclipse Adoptium\jdk-25...\.