Как написать свой первый плагин - обновлённый гайд за 2023 год [Гайд]

Если вы играли в Minecraft на серверах, то наверняка вам доводилось сталкиваться с различными системами по типу китов, точек дома, префиксов, чатов и т.д. Эти все системы добавляются на сервера при помощи плагинов - неких дополнений к серверным ядрам.
Первое что нам нужно знать - ванильные сервера и одиночная игра не поддерживают плагины! Это связанно с тем, что в одиночной игре мы запускаем так называемый встроенный сервер, в котором нет поддержки API (программного интерфейса приложения), который нужен для запуска плагинов и выполнения их кода. Тоже самое касается и ванильного серверного ядра.
Ядра которые поддерживают плагины были разработаны сообществом, наиболее яркими примерами являются Bukkit, Spigot, Paper, Magma, CatServer, Purpur, Tuinity, kSpigot и т.д. Я могу продолжать этот список очень долго, т.к. по факту помимо оригинальных ядер существуют их форки - версии от других разработчиков с какими либо улучшениями и дополнениями. Некоторые из этих форков предоставляют доп. возможности именно для разработчиков. Например Spigot и Paper имеют доп. API.
Как же это всё работает? Очень просто! Когда вы запускаете серверное ядро с поддержкой плагинов, оно создаст в корне сервера папку plugins, куда мы и будем помещать наши плагины.
Все плагины для Minecraft Java Edition пишутся на языке программирования Java, без знания которого вы не сможете разрабатывать плагины от слова вообще. Так что перед ознакомлением с этим гайдом я советую ознакомиться с базовой логикой Java и хотя бы изучить структуру самого ЯП. Если вы считаете, что готовы, то можете смело переходить ко следующему пункту.

Давайте начнём с подготовки вашего ПК к разработке плагинов. Как я уже сказал ранее, все плагины для Minecraft Java Edition написаны на ЯП Java, а это означает, что нам нужно установить JDK (Java Development Kit) на свой ПК. Так как мы будем разрабатывать плагин для новой версии Minecraft, а именно 1.19.4, то и JDK нам нужна свежая.
Если версия ядра ниже 1.17, то нужна Java 8.
Если версия ядра 1.17 - 1.17.1, то нужна Java 16.
Если версия ядра 1.18 и выше, то нужна Java 17.
Для загрузки той или иной версии Java достаточно вбить в поисковую строку JDK 17, JDK 16 и т.д.
Я рекомендую использовать JDK от Oracle. Допустим, если мы сделаем запрос JDK 17, то первый вебсайт, который нам выдаст это архивная страница для загрузки JDK 17 (Да, JDK 17 уже считается устаревшей)

Заходим на эту страницу и на ней видим вот такой список:

Здесь мы выбираем Java под свою ОС, вероятнее всего у вас Windows x64, поэтому мы загрузим именно Windows x64 Installer.
ВАЖНО Для загрузки некоторых архивных версий Java необходимо зарегистрироваться на сайте Oracle.
Открываем установщик и видим следующее:

Жмём Next >, и видим страницу, где можно указать куда именно будет установлена нужная вам версия JDK. Здесь я рекомендую изменить название папки на то, которое для вас будет самым удобным. После этого нажимаем Next > и ждём пока установка завершится. После установки мы увидим окно с кнопкой Next Steps и Close. Нажимаем Close и довольствуемся, ведь мы только что установили JDK на ваш ПК, подготовив его к разработке плагинов на 33,3%.
Проверить корректно ли установилась JDK можно следующим образом:
Запускаем cmd

Исполняем команду java -version

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

IDE (Среда Разработки) - программа, в которой мы и будем разрабатывать (кодить) наши плагины. Есть различные варианты, например Apache NetBeans, Eclipse и InteliJ Idea. Мы будем использовать именно InteliJ Idea Community Edition, т.к. на данный момент это самая продвинутая, функциональная и приятная IDE. Для того, чтобы её загрузить нам понадобится сделать следующий запрос в Google: InteliJ Idea. Вероятнее всего, вы увидите следующее:

Нажимаем на Download и видим вот такую картину:

Нам нужно загрузить именно InteliJ Idea Community Edition, т.к. Ultimate Edition является платной версией этой IDE и по факту нам не сильно нужен для Minecraft разработки. Нажимаем Download и ожидаем пока загрузится .exe установщик IDE.
В установщике просто нажимаем Next > и соглашаемся со стандартными настройками. По окончанию установки у нас должна появится InteliJ Idea на ПК. Если она установилась корректно, то переходите ко следующему пункту.

Для разработки плагинов нам также необходимо загрузить на свой пк серверное ядро той версии, для которой будем писать плагин. Делаем простой запрос в гугл: Название вашего ядра + версия. Допустим мне нужно ядро Paper 1.19.4, соответственно выглядеть это будет так:

Нажимаем на этот сайт и попадаем на страницу загрузок:

Здесь мы нажимаем на Paper и видим, что сайт предлагает загрузить ядро Paper для версии 1.20.2, но нам нужна именно версия 1.19.4, поэтому переходим в Build Explorer:


Здесь мы выбираем нужную версию и качаем последний билд ядра на нашу версию:

После загрузки мы должны переместить .jar файл в отдельную папку, допустим server:

Для удобства я переименовал ядро в core.jar, т.к. сейчас нам нужно будет создать загрузочный скрипт. Для этого мы создаём .txt файл и переименовываем его в start.bat:

Открываем файл при помощи текстового редактора по типу Notepad++ или же обычного блокнота и вписываем туда следующее:

@echo off
title Test server
java -jar core.jar -nogui
pause

Сохраняем скрипт и запускаем его:

Если всё верно, то сервер загрузит библиотеки и выдаст ошибку, т.к. вам необходимо принять EULA (Политику конфиденциальности). Для этого заходим в eula.txt и изменяем eula=false на eula=true.
ВАЖНО Если у вас не лицензионный аккаунт Minecraft, вам так же следует октлючить online-mode в server.properties. Для этого открываем этот файл текстовым редактором и заменяем online-mode=true на online-mode=false.
Во время второго запуска сервер должен сгенерировать до конца все файлы и успешно запустится:

Если вы увидели надпись Done (xxx s)! For help, type "help", то сервер успешно запущен и готов к работе. Мы можем переходить к финальному подготовительному этапу.

Итак, теперь нам нужно подготовить нашу IDE к разработке Minecraft плагинов. Для этого мы запускаем саму InteliJ Idea:

Переходим во вкладку Plugins и видим экран установки плагинов для IDE:

Пишем в поисковой строке Minecraft Development и нажимаем Install:

После этого IDE попросит вас перезагрузить её чтобы плагин начал работать и фактически на этом этапе мы готовы к разработке плагинов на все 100%! Теперь вы можете смело переходить к финальному и самому основному пункту данного гайда - разработка самого плагина.

Если вы дошли сюда, значит у вас уже всё готово для начала разработки. Давайте приступим к этому интересному процессу. Для начала мы переходим на главную страницу InteliJ Idea и нажимаем New Project:

После нажатия на эту кнопку откроется вот такое меню:

Нажимаем на Minecraft и с этого момента мы действительно начинаем работу над плагином:

Итак, сейчас я подробно объясню вам что делает каждое из этих полей. Мой личный совет - заполняйте все поля, кроме Depend, Soft Depend и Load Before. Эти 3 поля заполняйте только по необходимости.
Начнём с первого поля, и это Name, где мы указываем название проекта, не плагина:

Далее идёт поле Location, где мы указываем в какой директории будут находится файлы нашего проекта:

Теперь мы видим переключалку под названием Platform Type, где есть два значения: Mod и Plugin. Выбираем Plugin, т.к. мы будем разрабатывать именно плагин.

После этого мы видим поле Platform, где выбираем для какого типа ядра будем писать плагин, в нашем случае это Bukkit, поэтому выбираем его:

Также мы видим переключалку Bukkit Platform, в которой можно выбрать какого типа наше ядро: Spigot или Paper. Т.К. Я загрузил ядро Paper, то я выбрал здесь Paper.
ВАЖНО Давайте немного углубимся в тему форков. Spigot - это форк Bukkit, поэтому Spigot включает в себя всё что есть в бакките + некоторые свои функции. Paper - это форк Spigot, поэтому он включает в себя всё что есть в бакките, спигете и некоторые свои функции. Это важно понимать при выборе значения в этой переключалке.

В поле Minecraft Version выбираем версию нашего ядра, в моём случае это 1.19.4:

В поле Plugin Name мы вводим название самого плагина:

В поле Main Class мы вводим путь к главному классу плагина:

Далее мы видим раздел Optional Settings, я рекомендую вам развернуть его и заполнить:

В поле Description вводим описание плагина, что он делает:

В поле Authors вбиваем свой никнейм:

В поле Website вводим ссылку на свой сайт, если он у вас есть:

В поле Log Prefix мы вводим префикс плагина который будет отображаться в консоли и логах:

Переключалка Load At предназначена для более продвинутых пользователей, которые понимают в какой именно момент им нужно чтобы плагин инициализировался, поэтому поставим значение Startup (До загрузки мира):

Поля Load Before, Soft Depend и Depend мы заполнять не будем, т.к. наш плагин не имеет никаких зависимостей или же несовместимостей.
После секции Optional Settings идёт поле Build System. Я очень настоятельно рекомендую оставить значение Maven, т.к. Gradle является менее распространённым в мире написания плагинов и вы врядли сможете найти нужные дополнения/зависимости/гайды и т.д. для Gradle:

В секции Build System Properties мы видим 3 поля:
Group ID - Ваш идентификатор разработчика, если нет веб-сайта то пишите me.nickname, если есть, то пишите domainzone.domain.
Artifact ID - Идентификатор самого плагина, обычно идентичен названию плагина.
Version - Версия плагина, можете оставить 1.0-SNAPSHOT, но я заменю на 0.1.

Ну и последнее поле - JDK. В нём вы указываете какую версию JDK вы будете использовать для проекта, в моём случае это JDK 17.

После этого нажимаем Create и видим, что проект был успешно создан:

Давайте разберёмся со структурой проекта:
.idea - системная папка InteliJ Idea, не трогаем её.
src - папка с исходниками нашего плагина, тобишь та папка, где мы будем писать весь код.
resources - папка с ассетами (ресурсами) плагина, например конфигурация, инфо об плагине и т.д.
pom.xml - схема для Maven, если вы не разбираетесь в этом, то вам это трогать уж точно не нужно.
Открываем папку src, в ней доходим до главного класса и открываем его:

Здесь за нас уже написали самую основу плагина, давайте разберёмся:
Вопервых, за нас уже правильно объявили главный класс который наследует все методы из класса JavaPlugin.

public final class Main extends JavaPlugin

Также за нас уже написали два метода: onEnable() (при включении) и onDisable() (при выключении). Фактически, большинство действий мы будем выполнять именно при включении сервера.

@Override
public void onEnable() {
     // Plugin startup logic

}

@Override
public void onDisable() {
     // Plugin shutdown logic
}

В этом уроке мы разберём написание самого простейшего плагина для вывода надписи при включении и выключении сервера.
Первым делом нам нужно создать объект под названием Logger. Этот объект отвечает за вывод в консоль всевозможных ошибок, предупреждений, информации и т.д.:

Мы приравниваем Logger к Logger'у из Bukkit, т.к. нам нужен именно майнкрафтовский логгер.
Теперь в методы onEnable() и onDisable() мы впишем простую команду: log.info("Информация"):

Отлично, мы написали простенький плагин, давайте же проверим работает ли он. Для начала нам нужно скомпилировать его. Вверху мы видим меню компилятора:

Нажимаем на зелёную стрелочку и наблюдаем за происходящим на экране, если всё правильно, то внизу у вас должна появится консоль с логом и также должна появится папка target, где и находится наш .jar файл плагина:

Копируем этот .jar файл в папку plugins своего сервера и запускаем сам сервер:

Как мы видим, плагин написан правильно и делает то что и должен. Мы можем выключить сервер дабы удостоверится в этом ещё раз:

Поздравляю вас, вы написали свой первый плагин для Minecraft!