VillagerGUIApi - API для торговли жителей

VillagerGUIApi - это не мод и не плагин для рядового игрока. Это техническая библиотека для серверных разработчиков, которая решает одну конкретную головную боль: работу с торговым интерфейсом жителей в Minecraft. Если вы пишете плагин под Spigot, Paper или Purpur и вам нужны кастомные магазины, обменники или меню, стилизованные под торговлю с villagers, то этот инструмент, скорее всего, сэкономит вам несколько вечеров отладки.

Зачем это вообще нужно

В ванильном Minecraft торговля с жителем - это отдельное окно, привязанное к конкретной сущности. Серверному разработчику, который хочет сделать свой магазин на базе этого GUI, приходится либо спавнить настоящего жителя и всячески его прятать, либо лезть в NMS и разбираться с внутренними классами. Второй путь работает по-разному на разных версиях, и именно тут начинается боль: то, что компилируется под 1.16, ломается на 1.19, а на 1.20 вообще меняется сигнатура методов.

VillagerGUIApi предлагает другой подход. Библиотека даёт унифицированный интерфейс: вы создаёте VillagerInventory и VillagerTrade, наполняете его предметами, и всё это открывается игроку как обычный торговый GUI. Никаких сущностей в мире, никаких костылей с телепортацией - только чистый инвентарь. По факту это тот самый уровень абстракции, которого не хватает в стандартном Bukkit API.

Что внутри

Автор явно старался сделать вход максимально низким. Подключение занимает буквально несколько строк, а дальше вы работаете с понятными классами и событиями.

Основные возможности:

• Единый API для манипуляции торговыми инвентарями жителей без реального спавна villager
• Система событий, которая позволяет реагировать на действия игрока
• Четыре готовых ивента: VillagerInventoryOpenEvent, VillagerInventoryCloseEvent, VillagerInventoryModifyEvent и VillagerTradeCompleteEvent
• Отдельные реализации под каждую версию Minecraft, которые подгружаются по мере необходимости

События тут - это отдельная ценность. VillagerTradeCompleteEvent даёт вам точку, в которую можно вклиниться после успешной сделки: начислить валюту, выдать награду, записать статистику, проверить права на покупку. Без такого ивента пришлось бы слушать клики и вручную сверять содержимое слотов, что ненадёжно.

Совместимость и производительность

Заявлена поддержка версий от 1.3 до 1.19, а в свежих релизах добавились 1.20.1, 1.20.2 и 1.20.4. Точкой отсчёта стоит считать релиз 1.5.0 от 16 февраля 2024 года - именно там появилась поддержка Minecraft 1.20.4. На странице проекта диапазон версий местами отображается до 1.20.1, но в changelog прямо указана работа с 1.20.4, так что ориентируйтесь на это.

Как это работает под капотом? Через механизм отложенной загрузки классов: библиотека грузит только те классы, которые нужны для текущей версии сервера. Reflection используется по минимуму, а версионные различия спрятаны за отдельными реализациями. На практике это значит, что вам не нужно ставить разные jar-файлы под разные версии Minecraft, но и лишний вес в памяти библиотека не держит.

Важный нюанс: библиотека не заменяет собственные реализации торговли, а лишь оборачивает их. Если вы пишете плагин на чистом Bukkit и хотите кастомные меню, придётся разобраться с VillagerInventory и VillagerTrade - без базового понимания того, как устроены инвентари, будет неочевидно. Зато после освоения API вы получаете один код, который работает на широком диапазоне версий.

Кому это подойдёт, а кому нет

Тут стоит быть честным. Если вы просто администрируете сервер и ищете плагин для готовых магазинов, VillagerGUIApi вам напрямую не нужен - это инструмент для разработчика. Библиотека имеет смысл в двух случаях:

1. Вы пишете свой плагин и хотите сделать торговлю без костылей.
2. Вы разбираетесь в Java и хотите понять, как устроен торговый GUI изнутри, чтобы потом написать что-то своё.

Для большинства админов это промежуточный слой, который просто позволяет ставить плагины-зависимости вроде экономических магазинов и квестовых меню. Желательно проверить, что ваш основной плагин действительно использует эту библиотеку, иначе ставить её на сервер особого смысла нет.

Установка

Процесс стандартный для любого серверного плагина:

1. Скачайте jar-файл библиотеки.
2. Положите его в папку plugins/ вашего сервера.
3. Перезапустите Spigot, Paper или Purpur.

Сам по себе VillagerGUIApi ничего не делает - он просто предоставляет API другим плагинам. Если ваш основной плагин требует эту библиотеку как зависимость, ставьте её вместе с ним. На хостингах вроде BungeeHost такой плагин загружается в папку и активируется в один клик, так что с установкой на готовом сервере проблем не будет.

Техническая сводка

Параметр	Значение
Тип	Библиотека/API для серверных плагинов
Платформы	Spigot, Paper, Purpur, Bukkit
Версии Minecraft	от 1.3 до 1.20.4 (по данным changelog)
Последний релиз	1.5.0 (16 февраля 2024)
Лицензия	MIT
Зависимости	Нет, самостоятельная библиотека
Игроку обязательна?	Нет, работает на стороне сервера

Совет напоследок

Перед тем как тащить библиотеку в продакшен, протестируйте её на той версии сервера, которую используете. Хоть заявлен широкий диапазон, с обновлением Minecraft внутренности торгового GUI действительно меняются, и новые версии могут отставать от актуальных релизов Mojang. Если ваша сборка сидит на 1.21+, проверьте, обновлялся ли проект, потому что без поддержки свежих версий библиотека просто не загрузится.

И ещё: не путайте эту библиотеку с модами для клиентской стороны вроде тех, что добавляют новые интерфейсы торговли. VillagerGUIApi - исключительно серверная история, на клиенте она ничего не рендерит. А вот если ваш плагин поднимает кастомные магазины на сервере, скачать VillagerGUIApi и подключить к проекту - это правильный ход, который сохранит совместимость и избавит от ручной поддержки NMS.