Как обновить плагин до новой версии Minecraft

Шаг за шагом

1. 1.Сначала попробуйте старый .jar

   Поставьте его на тестовый сервер новой версии и прочитайте консоль. Если он загружается и работает, возможно, ничего менять не придётся.

2. 2.Измените зависимость API

   В pom.xml или build.gradle укажите для paper-api или spigot-api новую версию.

3. 3.Обновите api-version и Java

   Укажите api-version в plugin.yml (например, '1.21') и компилируйте под ту Java, которая нужна новой версии: Java 17 до 1.20.5, Java 21 начиная с 1.20.5, Java 25 для 26.x.

4. 4.Исправьте то, что больше не компилируется

   Соберите проект и пройдитесь по ошибкам: переименованные материалы, удалённые методы, изменённые классы событий. Компилятор перечисляет их с файлом и строкой.

5. 5.Обновите зависимости

   Плагинам, которые использует ваш плагин (Vault, PlaceholderAPI, ProtocolLib, WorldGuard), тоже нужны версии с поддержкой новой версии Minecraft, и в файле сборки, и на сервере.

6. 6.Проверьте на новой версии

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

Что обычно ломается

• Названия материалов и enum: обновление 1.13 переименовало большинство предметов и блоков; более поздние версии некоторые добавляют, переименовывают или удаляют. Код со старыми названиями или числовыми ID ломается.
• Удалённые устаревшие методы: методы, помеченные как устаревшие на протяжении нескольких версий, в итоге исчезают.
• Данные предметов: начиная с 1.20.5 NBT предметов заменили компоненты данных. Плагинам, которые напрямую меняют NBT предметов, нужно переписать эту часть; обычный API ItemMeta продолжает работать.
• NMS и рефлексия: код, который использует внутренние классы сервера, ломается почти на каждой версии. Замените его на API, где это возможно, или на библиотеку вроде ProtocolLib.
• Версии библиотек: встроенные библиотеки, собранные под старую Java, могут не работать на новой.

Обновление через много версий

Переход с 1.8 или 1.12 на 1.21 ближе к переписыванию тех частей, что работают с предметами, блоками и частицами, чем к обновлению. Делайте это за один раз под новый API, а не версия за версией, и будьте готовы, что в конфиг-файлах тоже понадобятся новые названия материалов.

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

С Codexe

На тарифе Pro и выше можно импортировать исходный код плагина в виде ZIP и попросить, например: «Это мой плагин для Paper 1.20.4. Обнови его до Paper 1.21.4». Codexe берёт версию Minecraft из файла сборки, собирает проект на нужной этой версии Java и исправляет ошибки компиляции, опираясь на настоящие сигнатуры API, под который идёт сборка. Для плагина, сделанного в Codexe, попросите новую версию в чате проекта.

Компиляция доказывает, что плагин собирается под новый API. Затем попробуйте его на тестовом сервере, потому что изменения поведения между версиями не проявляются как ошибки компиляции.

Вопросы