Как Добавить Интерактивные Интерфейсы Анвиля в Ваш Сервер Mi

Создание плагина Minecraft, требующего ввода от игрока, - общая задача. Вы можете попросить через чат, но это заполняет лог чата. Кто угодно может построить настраиваемый интерфейс инвентаря, но для этого нужны текстуры и дополнительный код. Анвильные экраны идеальны для простого текстового ввода, а AnvilGUI - это библиотека, делающая их работоспособными во всех версиях Minecraft без изменения одной строки кода NMS.

Это важно, потому что внутренние механизмы Minecraft постоянно меняются. Анвильные интерфейсы в версии 1.20 обрабатываются совершенно иначе, чем в 1.21. Большинство разработчиков плагинов либо придерживаются своей версии сервера, либо используют хаки отражения для поддержки нескольких версий. AnvilGUI делает эту работу отражения за вас.

Что делает AnvilGUI

AnvilGUI - это обертка вокруг инвентаря анвиля, предназначенная специально для захвата текста от игроков. Вместо погружения в net.minecraft.server (обфускальные внутренности, меняющиеся при каждом патче), вы пишете чистый код с использованием шаблона Builder. Библиотека обнаруживает версию, которую вы используете, и загружает правильную реализацию во время выполнения.

Вот как это выглядит в практике.

Ядро рабочего процесса простое: игрок видит анвильный экран с заголовком и некоторым текстом по умолчанию. Они набирают что-то, нажимают на слот вывода (самый правый), и ваш код выполняется. Вы проверяете ввод, закрываете экран или просите попробовать снова. Все это с помощью обработчиков событий.

Когда использовать это

Ввод текста от игроков встречается повсюду в разработке плагинов. Системы квестов, запрашивающие имена персонажей. Команды настраиваемых никнеймов. Аукционные дома, где продавцы устанавливают цены. Системы магазинов с предложениями игроков. Даже инструменты конвертации координат, такие как наш Nether Portal Calculator, нуждаются в чистых интерфейсах ввода.

И вот в чем дело: анвильные интерфейсы кажутся родными для Minecraft. Интерфейс уже есть, игроки сразу понимают его, и он не нарушает погружение с помощью странных диалогов или всплывающих меню. Если бы вы строили что-то вроде нашего Minecraft MOTD Creator (который позволяет игрокам проектировать сообщения сервера), анвильный ввод идеально подошел бы в этот поток.

Некоторые плагины используют чат для ввода, но это загружает лог чата и выглядит не аккуратно. Другие строят полноценные настраиваемые интерфейсы инвентаря, что требует настраиваемых текстур и гораздо больше кода. Анвели попадают в сладкую точку: они встроенные, чувствуются как vanilla, и AnvilGUI абстрагирует версионный кошмар совместимости.

Установка AnvilGUI

Сначала добавьте репозиторий Maven. С версии 1.10.11 репозиторий переместился на новый URL:

<repository>
 <id>mvn-wesjd-net</id>
 <url>https://mvn.wesjd.net/</url>
</repository>

Затем добавьте зависимость:

<dependency>
 <groupId>net.wesjd</groupId>
 <artifactId>anvilgui</artifactId>
 <version>1.10.12-SNAPSHOT</version>
 <scope>compile</scope>
</dependency>

Область действия compile означает, что AnvilGUI упаковывается в ваш финальный JAR.

Теперь часть, которая запутывает людей: затенение. AnvilGUI - это библиотека, а не отдельный плагин, поэтому вам нужен maven-shade-plugin, чтобы упаковать его в JAR вашего плагина. Это предотвращает конфликты пути классов, если несколько плагинов на одном сервере используют AnvilGUI.

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-shade-plugin</artifactId>
 <version>3.5.0</version>
 <executions>
 <execution>
 <phase>package</phase>
 <goals>
 <goal>shade</goal>
 </goals>
 <configuration>
 <relocations>
 <relocation>
 <pattern>net.wesjd.anvilgui</pattern>
 <shadedPattern>your.plugin.package.anvilgui</shadedPattern>
 </relocation>
 </relocations>
 </configuration>
 </execution>
 </executions>
</plugin>

Замените your.plugin.package на ваш фактический пакетный имя. Это перемещает AnvilGUI в ваше пространство имен, чтобы избежать конфликтов с другими плагинами.

Как работает API

Вот полный пример из проекта:

new AnvilGUI.Builder().onClose(stateSnapshot -> {
 stateSnapshot.getPlayer().sendMessage("Вы закрыли инвентарь.");
 }).onClick((slot, stateSnapshot) -> {
 if(slot != AnvilGUI.Slot.OUTPUT) {
 return Collections.emptyList();
 }

 if(stateSnapshot.getText().equalsIgnoreCase("you")) {
 stateSnapshot.getPlayer().sendMessage("У вас есть магические силы!");
 return Arrays.asList(AnvilGUI.ResponseAction.close());
 } else {
 return Arrays.asList(AnvilGUI.ResponseAction.replaceInputText("Попробуйте снова"));
 }
 }).preventClose().text("Что означает жизнь?").title("Введите ваш ответ").plugin(plugin).open(player);

Шаблон Builder позволяет цепочить вызовы методов. Title - это текст над анвилем. Text - это текст по умолчанию (предварительно заполненный контент). OnClose срабатывает, когда игрок закрывает без подтверждения. OnClick срабатывает, когда они нажимают на слот в анвиле.

Параметр slot сообщает вам, что они нажали. Есть INPUT (левый слот), OUTPUT (правый слот, где отображаются результаты) и RESULT (фактический предмет, который они бы получили, если бы это был реальный рецепт). Вы обычно проверяете OUTPUT, поскольку это кнопка отправки.

StateSnapshot содержит игрока и любой текст, который они набрали. Вы проверяете его и возвращаете ResponseActions. ResponseAction.close() закрывает экран. ResponseAction.replaceInputText() обновляет поле ввода - полезно для сообщений об ошибках, таких как "это имя уже занято" или "попробуйте снова".

PreventClose() удаляет возможность закрытия по клавише Esc, заставляя игроков либо отправить, либо нажать другие слоты. Используйте это для критически важной информации, которую от них绝е нужно.

Plugin(plugin) - это экземпляр вашего плагина. Он необходим для регистрации событий и обнаружения версии под капотом.

Еще одна мощная вещь: вы можете настроить几乎 все. Более длинные заголовки, только для чтения текст, разные поведения слотов на основе ввода. API дает вам контроль.

Общие ошибки и подводные камни

Настройка затенения - это самая большая проблема. Пропустите maven-shade-plugin, и ваш плагин даже не загрузится. Вы получите ClassNotFoundException во время выполнения, и потребуется секунда, чтобы понять, почему.

Другой шаблон, который сбивает с толку: onClick ожидает возврат List<ResponseAction>. Пустой список (Collections.emptyList()) допустим и просто держит экран открытым. Компилятор ловит пропущенные возвраты в любом случае, поэтому это обычно не является проблемой в практике.

Текст ввода в анвиле не цветной и не имеет специальной форматировки. Это просто текст. За пределами заголовка и контента по умолчанию нет много визуальной настройки. Если вам нужны более сложные визуальные элементы (настраиваемые цвета, форматированный текст), вам подойдет другой подход.

О поддержке версий: AnvilGUI работает на recent версиях. На самом деле, она работает и на старых благодаря отражению на основе обнаружения версии. Проверьте страницу релизов, если вы запускаете что-то очень старое, но короткий ответ в том, что если ваш сервер может загрузить библиотеку, она работает.

Библиотека не обрабатывает для вас i18n-трансляцию. Если ваш сервер поддерживает несколько языков, вы переводите заголовок и текст сами перед передачей их в AnvilGUI.

Альтернативы и когда их использовать

Если анвильные экраны не подходят, у вас есть другие варианты.

Интерфейсы подписей позволяют игрокам писать на подписи, а затем вы читаете ее. Проще в некоторых аспектах, но не feels так интегрированно. Игроки видят подпись вместо анвиля.

Интерфейсы книг используют интерфейс записываемой книги Minecraft. Хорошо подходит для более длинного текста, но избыточно для одного поля ввода. Это более тяжелое взаимодействие.

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

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

Мое мнение по этому поводу

AnvilGUI решает конкретную проблему хорошо: захват текста от игроков без борьбы с версионно-зависимым кодом Minecraft. Это Java-библиотека с лицензией MIT, активно поддерживаемая, и у нее есть солидные 542 маркера на GitHub. Если вы строите плагин, который нуждается во вводе игрока и анвиль подходит для вашего случая, потратите десять минут на интеграцию. Это спасет вас от ада отладки совместимости версий в будущем.