Как написать первый плагин Minecraft на Java: команда /hello

Первый Paper-плагин состоит из трёх обязательных частей: Java-класса, plugin.yml и JAR, собранного под совместимую версию сервера. Мы добавим команду /hello, увидим сообщение в игре и разберём, почему плагин может собратьcя успешно, но не загрузиться из-за main class, api-version или Java toolchain.

Плагин выполняется внутри Minecraft-сервера и расширяет его через Paper API. Он не является модом клиента и не меняет саму игру на компьютере игрока. Сервер при запуске сканирует папку plugins, читает plugin.yml из JAR, загружает указанный main class и вызывает onEnable. Внутри него мы регистрируем обработчик команды hello.

Как Paper находит и запускает плагин

Проект использует Gradle Kotlin DSL. build.gradle.kts добавляет официальный Paper repository, compileOnly зависимость и Java toolchain, соответствующий текущей документации. Исходник лежит по пути src/main/java/dev/kodik/hello/HelloPlugin.java и начинается package dev.kodik.hello.

У проекта есть один главный маршрут: получить входные данные, проверить их, выполнить действие и показать результат. Если каждый этап можно проверить отдельно, ошибка перестаёт быть загадкой.

От входных данных до видимого результата. Descriptor связывает файл сервера с Java-классом

Создаём Gradle-проект и команду /hello

Создайте в IntelliJ проект Gradle с Kotlin DSL. Структура каталогов и файлы есть в исходниках статьи. На момент проверки актуальная документация Paper показывает ветку 26.2 и Java toolchain 25, но эти числа нестабильны. Сверьте их перед сборкой. После добавления файлов выполните ./gradlew build или gradlew.bat build на Windows.

package dev.kodik.hello;

import java.util.Objects;
import org.bukkit.plugin.java.JavaPlugin;

public final class HelloPlugin extends JavaPlugin {
    @Override
    public void onEnable() {
        Objects.requireNonNull(getCommand("hello"), "hello is missing in plugin.yml")
            .setExecutor((sender, command, label, args) -> {
                sender.sendMessage("Привет, " + sender.getName() + "! Плагин работает.");
                return true;
            });

        getLogger().info("HelloPlugin включён");
    }
}

Objects.requireNonNull превращает забытый раздел commands в точную ошибку во время запуска. Без него getCommand может вернуть null, а причина потеряется в другом месте.

Что отличает устойчивый проект от случайного успеха. Лог загрузки дополняет успешную компиляцию

Почему package, main и пути должны совпасть

compileOnly означает, что Paper API нужно для компиляции, но не упаковывается в JAR: реализация уже существует на сервере. plugin.yml попадает в корень JAR как ресурс. Поле main содержит полное имя класса вместе с package. Paper использует class loader, создаёт экземпляр и вызывает lifecycle-методы. getCommand ищет декларацию hello в YAML.

Не перезагружайте плагины командой /reload во время разработки: многие плагины и ресурсы не рассчитаны на такой lifecycle. Останавливайте тестовый сервер, заменяйте JAR и запускайте снова. Не разрабатывайте на прод-сервере с игроками.

Собираем JAR и читаем серверный лог

Соберите JAR и до копирования откройте его как ZIP: plugin.yml должен лежать в корне, а HelloPlugin.class по пути dev/kodik/hello. Запустите локальный тестовый сервер и примите лицензионное соглашение Minecraft только если согласны с его условиями. Выполните /hello из игры и консоли.

Первый плагин готов не после компиляции, а после полного цикла: JAR собран, descriptor прочитан, onEnable выполнен, команда проверена и ошибка конфигурации понятна.

Четыре проверки перед следующим шагом. Версии являются частью воспроизводимого проекта

Куда развивать первый игровой плагин

Следующим шагом добавьте permission для /hello и проверьте игрока с правом и без него. Затем вынесите формат сообщения в config.yml и используйте saveDefaultConfig. Для игровой механики подпишитесь на одно событие, например PlayerJoinEvent, и не смешивайте его с командой в гигантском классе.

Как изучить тему в Кодике

В Кодике начните с классов, методов и package Java. Затем соберите обычный JAR без Minecraft. После этого подключите Paper API и разберите lifecycle. Игровая мотивация полезна, но базовые конструкции должны оставаться узнаваемыми.

Не пытайтесь запомнить весь API. В тренажёре Кодика сначала воспроизведите чистую логику без библиотеки, затем восстановите подключение и обработку ошибок. Финальный тест: объяснить проект по памяти и добавить одну свою функцию.

Что получится в итоге

Gradle собирает JAR, Paper читает plugin.yml, вызывает onEnable и новая команда /hello отвечает игроку прямо в серверном чате.