Как сделать плагин в Майнкрафте — первая команда на Paper

Чтобы сделать плагин в Майнкрафте, создайте Java-проект под серверное ядро, напишите обработчик команды и соберите файл .jar, который сервер загрузит из папки plugins. Пример для Java Edition 26.3 добавляет на Paper команду /hello: она отвечает отправителю приветствием.

Понадобится именно сервер Paper: обычный сервер Mojang этот плагин не загрузит. Разницу между серверными дополнениями и их установку разбирает гайд по плагинам. С помощью других плагинов можно создать НПС или сесть на стул и лечь на землю.

Что установить перед созданием плагина

Подготовьте JDK — комплект Java с компилятором, IntelliJ IDEA и отдельную папку для тестового сервера. Требования к проекту и создание шаблона описаны в документации Paper.

Откройте терминал и выполните java -version, затем javac -version. Обе команды должны находить установленную Java. Если java работает, а javac не найден, проверьте установку JDK и переменную PATH.

Как подготовить проект

1. В IntelliJ IDEA откройте File → Settings → Plugins → Marketplace. Найдите Minecraft Development, установите расширение и перезапустите IDE.
2. Выберите File → New → Project → Minecraft. Укажите параметры из таблицы ниже.
3. Создайте проект и дождитесь синхронизации Gradle. При первом открытии ему нужен интернет для загрузки зависимостей.
4. В настройках проекта выберите установленный JDK. В Settings → Build, Execution, Deployment → Build Tools → Gradle проверьте, что Gradle JVM использует тот же JDK.

Для запуска Gradle на Java 25 нужен Gradle начиная с 9.1.0 — это указано в таблице совместимости Gradle. Если шаблон создал более старый Wrapper, откройте gradle/wrapper/gradle-wrapper.properties и в значении distributionUrl замените только имя архива на gradle-9.1.0-bin.zip, сохранив остальную строку. Затем повторите синхронизацию.

Откройте созданный build.gradle или build.gradle.kts. В блоке dependencies должна быть зависимость Paper API:

compileOnly("io.papermc.paper:paper-api:26.3.build.+")

Если мастер указал другую версию API, замените соответствующую строку. Репозитории и остальные настройки шаблона сохраните; целевая версия Java в настройках сборки должна соответствовать выбранному JDK. Область compileOnly означает, что API нужен для компиляции, а при запуске его предоставляет Paper: включать серверное API внутрь вашего JAR не нужно.

Как добавить команду /hello

Создайте два Java-файла в пакете me.student.hello. Если мастер уже создал HelloPlugin.java, замените его содержимое целиком. Сохраняйте исходники в UTF-8.

1. Откройте src/main/java/me/student/hello/HelloPlugin.java и вставьте код главного класса.
2. В той же папке создайте Java-класс HelloCommand и вставьте обработчик команды из следующего примера.

Файл HelloPlugin.java:

package me.student.hello;

import org.bukkit.plugin.java.JavaPlugin;

public final class HelloPlugin extends JavaPlugin {
@Override
public void onEnable() {
registerCommand("hello", new HelloCommand());
getLogger().info("HelloPlugin включён");
}
}

Файл HelloCommand.java:

package me.student.hello;

import io.papermc.paper.command.brigadier.BasicCommand;
import io.papermc.paper.command.brigadier.CommandSourceStack;

public final class HelloCommand implements BasicCommand {
@Override
public void execute(CommandSourceStack source, String[] args) {
source.getSender().sendPlainMessage(
"Привет, " + source.getSender().getName() + ". Плагин работает."
);
}
}

onEnable() вызывается при включении плагина. Внутри него registerCommand() связывает имя hello с обработчиком; слеш в имени не нужен. Когда игрок или консоль выполняет команду, метод execute() отправляет ответ её отправителю.

Здесь используется рекомендованный Paper интерфейс BasicCommand. Дописывать команду в раздел commands файла plugin.yml для этого способа регистрации не требуется. Проверку прав мы не задавали, поэтому команда доступна всем игрокам.

Что написать в plugin.yml

Откройте src/main/resources/plugin.yml и полностью замените содержимое следующим:

name: HelloPlugin
version: '1.0.0'
main: me.student.hello.HelloPlugin
api-version: '26.3'

Поле main должно точно совпадать с пакетом и именем главного класса, включая регистр букв. version обозначает версию вашего плагина, а api-version — версию API сервера. Сервер старее указанного API откажется загружать плагин; подробности есть в описании plugin.yml.

Проверьте название файла: нужен именно plugin.yml, без скрытого окончания .txt. Gradle положит его в корень готового JAR вместе со скомпилированными классами.

Как собрать плагин в JAR

1. Откройте терминал IntelliJ IDEA в корневой папке проекта — там находятся файлы gradlew и gradlew.bat.
2. В Windows PowerShell выполните .\gradlew.bat clean build. В Linux и macOS выполните ./gradlew clean build; если нет права запуска, используйте bash gradlew clean build.
3. Дождитесь сообщения BUILD SUCCESSFUL. Если сборка завершилась ошибкой, сначала исправьте её: старый JAR не содержит последних изменений.
4. Откройте папку build/libs. Нужен основной файл .jar, без окончания -sources.jar или -javadoc.jar. Точное имя зависит от настроек проекта.

Можно собрать проект через окно Gradle в IDE, запустив задачу build. Копировать на сервер папку проекта, исходники .java или отдельные файлы .class не нужно.

Как проверить плагин на тестовом сервере

Создайте отдельную папку test-server и используйте новый мир. Если сервер ещё не подготовлен, поможет инструкция по созданию сервера.

1. Скачайте Paper для Java Edition 26.3 через официальный раздел загрузок проекта. Поместите серверный JAR в test-server и переименуйте в paper.jar.
2. Откройте терминал в этой папке и выполните java -Xmx2G -jar paper.jar --nogui. Параметр -Xmx2G ограничивает максимальную память Java-процесса; для работы компьютеру также нужна свободная память сверх этого значения.
3. После первого запуска откройте созданный eula.txt. Прочитайте условия и, если согласны, измените eula=false на eula=true. Повторите запуск.
4. Когда сервер закончит запуск, введите в его консоли stop и дождитесь завершения процесса.
5. Скопируйте собранный плагин в test-server/plugins. Если папки нет, создайте её. Запустите сервер снова той же командой.
6. Проверьте, что в консоли появилось HelloPlugin включён. Выполните plugins: имя HelloPlugin должно быть в списке включённых плагинов.
7. Запустите Java Edition 26.3, откройте «Сетевая игра» и подключитесь к localhost. В чате выполните /hello: появится приветствие с вашим ником.
8. Проверьте консоль сервера: введите hello без слеша. Ответ должен появиться в консоли.

Копирование JAR, перезапуск и проверка через plugins соответствуют инструкции Paper по установке плагинов. В консоли серверные команды вводят без начального слеша; другие полезные действия собраны в гайде по серверным командам.

После изменения кода снова выполните сборку, остановите сервер командой stop, замените старый JAR и запустите сервер. Оставляйте в папке только одну копию своего плагина. Для проверки обновлений используйте полный перезапуск вместо /reload.

Почему плагин не работает

Начните с консоли сервера и файла logs/latest.log. Найдите первое сообщение об ошибке вашего плагина и строки Caused by: они помогают понять причину.

Подойдёт ли пример для старых версий и Bedrock

Этот пример использует API Paper и рассчитан на Java Edition 26.3. Для Spigot и старых выпусков нужен отдельный вариант проекта: изменение одного поля api-version не заменяет перенос кода и выбор подходящей версии Java.

В Bedrock Edition этот Java-плагин не запускается. Для стандартной Bedrock используют дополнения и Script API с JavaScript или TypeScript; это другой формат проекта.