Настройка Adventure-Platform для форматированного текста на

Если вы разрабатывали плагины или программное обеспечение для серверов Minecraft, вы, вероятно, чувствовали боль форматирования текста. Цвета, стили, события кликов, текст наведения - все это платформо-зависимые. Paper обрабатывает это одним способом, BungeeCord - другим, Sponge - третьим. Adventure-Platform решает эту проблему, предоставляя единственный API для компонентов текста, работающий на всех платформах.

Что делает Adventure-Platform

Adventure-Platform - это набор реализаций, расположенный поверх библиотеки Adventure, библиотеки компонентов текста, созданной Kyori. Представьте Adventure как общий язык, а Adventure-Platform - как переводчик для разных платформ Minecraft.

Само Adventure является платформо-независимым - оно не знает о формате NBT Paper или массивах байт BungeeCord. Оно просто предоставляет чистые Java API. Но ваше серверное программное обеспечение? Оно требует родных компонентов текста. Вот здесь и появляется Adventure-Platform. Оно оборачивает платформо-зависимые реализации в единый чистый интерфейс.

Поддерживает Paper, Spigot и Bukkit на стороне сервера. Обрабатывает прокси BungeeCord. Даже покрывает Sponge, если вы на это готовы. Последний релиз добавил поддержку Minecraft 1.21.6 и 1.21.7.

Почему разработчики серверов используют это

Предположим, вы пишете плагин, который требует настраиваемое сообщение о подключении с цветами, событиями кликов и наведением. Без Adventure-Platform вы бы написали одну версию для Bukkit, другую для Sponge, возможно, третью для Velocity. Не весело.

С Adventure-Platform вы пишете это один раз. Библиотека определяет, на какой платформе вы находитесь, и автоматически переводит компоненты. Цвета, градиенты, обфускация, черта - все обрабатывается. События кликов (открыть URL, выполнить команду, скопировать в буфер, показать текст) работают на всех платформах.

Практический пример: вы строите сервер MOTD (сообщение дня). Используя Adventure, вы создаете компонент текста с цветами и наведением. Adventure-Platform конвертирует это в формат, понятный вашему серверу. Если позже вы перейдете с Paper на BungeeCord, ваш код остается прежним.

Это действительно полезно, если вы поддерживаете плагин или серверное программное обеспечение, ориентированное на несколько платформ.

Включение Adventure-Platform в ваш проект

Сначала вам нужно добавить зависимость. Артефакты Adventure-Platform размещены в Maven Central. Вот, как настроить это в файле сборки Gradle:

repositories {
 mavenCentral()
}

dependencies {
 // Для серверов на основе Bukkit (Paper, Spigot, Craftbukkit)
 implementation "net.kyori:adventure-platform-bukkit:4.4.1"

 // Для BungeeCord
 // implementation "net.kyori:adventure-platform-bungeecord:4.4.1"

 // Для Sponge API 7
 // implementation "net.kyori:adventure-platform-sponge7:4.4.1"
}

Выберите правильный артефакт для вашей платформы. Если вы используете Maven, координаты одинаковы, но в синтаксисе XML Maven.

После добавления зависимости вам нужно получить аудиторию Adventure для вашего сервера:

import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.platform.bukkit.BukkitAudiences;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

public class MyPlugin extends JavaPlugin {
 private BukkitAudiences audiences;

 @Override
 public void onEnable() {
 this.audiences = BukkitAudiences.create(this);
 }

 @Override
 public void onDisable() {
 if (this.audiences!= null) {
 this.audiences.close();
 }
 }

 public void sendMessage(Player player) {
 Audience audience = this.audiences.player(player);
 Component message = Component.text("Привет, ", NamedTextColor.GOLD).append(Component.text(player.getName(), NamedTextColor.YELLOW));
 audience.sendMessage(message);
 }
}

Это базовый шаблон. Создайте объект Audiences один раз в onEnable(), закройте его в onDisable(), затем используйте его для отправки компонентов игрокам.

Что можно сделать с этим

Цвета текста через все 16 классических цветов плюс полная поддержка RGB. Minecraft 1.16+ позволяет использовать любое значение цвета, а Adventure обрабатывает конверсию в старых версиях.

Стили текста работают так, как ожидается: жирный, курсив, подчеркивание, черта, обфускация. Комбинируйте их в любом порядке. Постройте градиентный текст, где цвета меняются на протяжении сообщения.

События кликов делают ваши сообщения интерактивными. Игроки могут кликнуть, чтобы открыть URL, выполнить команду, скопировать в буфер или показать сообщение. События наведения отображают текст при наведении игрока на компонент - идеально для тултипов или объяснений. Если вы создаете что-то вроде настраиваемого MOTD, вы можете добавить функциональность «клик, чтобы присоединиться» или декоративный текст наведения.

Транслации встроены. Adventure имеет тип транслируемых компонентов, который обрабатывает встроенные ключи перевода Minecraft, а также пользовательские. Сервер автоматически обрабатывает согласование языка.

Сериализация JSON работает, если вам нужно хранить компоненты или отправлять их по сети. Библиотека может конвертировать компоненты в JSON и обратно, следуя родившему формату Minecraft.

Питфолы и что может поймать вас не на ходу

Самая большая ошибка: не закрывать объект Audiences. Он держит ресурсы. Если вы создаете BukkitAudiences или аналогичный и не закрываете его при отключении плагина, вы утечка памяти. Всегда закрывайте в onDisable().

Сериализация компонентов варьируется между версиями. На самом деле, это не совсем точно - сама сериализация стабильна, но внутренний формат NBT, используемый Minecraft, изменился в 1.21.6. Последний релиз Adventure-Platform обрабатывает это, но если вы на старой версии и переходите на 1.21.6, вы можете увидеть странное поведение с существующими сохраненными компонентами. Это важно, если вы кэшируете компоненты или храните их в базах данных.

Не предполагайте, что все платформы поддерживают все функции одинаково. Например, некоторые старые реализации Sponge могут иметь ограниченную поддержку новых функций текста. Проверьте платформо-зависимую документацию на сайте документации Adventure перед тем, как полагаться на форматирование краевых случаев.

Цвета RGB требуют 1.16+. Если вы целеваете старые серверы, придерживайтесь именованных цветов или используйте выборочную конверсию цветов (которую может сделать Adventure, но вам нужно обрабатывать это аккуратно).

Что еще есть

MiniMessage - это язык компонентов на основе строк, работающий вместе с Adventure. Вместо построения компонентов в коде вы можете писать их в читаемом формате: «Привет!» Это легче в весе, если вы строите текст из файлов конфигурации или пользовательского ввода. MiniMessage и Adventure работают гладко вместе.

Если вы не готовы к полноценной библиотеке, как Adventure, существуют более простые альтернативы, такие как LegacyChat. Они обрабатывают основы (цвета, форматирование) без сложности. Взамен вы не получаете события кликов, наведения, перевода или абстракцию платформы. Хорошо для небольших проектов. Не хорошо, если вам нужны функции за пределами простых цветов.

Некоторые платформы поставляют свои собственные API текста. Sponge имеет свою собственную реализацию текста, близкую к Adventure, но не идентичную. Waterfall (преемник прокси Velocity) поощряет использование Adventure. Если вы строите для конкретной платформы и не планируете поддерживать несколько серверов, вы можете пропустить Adventure и использовать родное API. Но если есть малейший шанс, что вам придется повторно использовать код или поддерживать несколько платформ позже, Adventure-Platform стоит первоначального вложения.

Стоит ли настраивать это?

Да, если вы пишете плагин или серверное программное обеспечение, которое может оказаться на нескольких типах платформ или если вы хотите, чтобы ваш код был повторно используем. Настройка проста, API чист, и вы избегаете кучи проблем в будущем.

Если вы разрабатываете небольшой плагин для одной конкретной версии сервера и платформы, вам это, возможно, не нужно. Но в тот момент, когда вы подумаете «а что, если я захочу использовать это на другом типе сервера?» или «что, если кто-то попросит запустить это на их сервере Sponge?» Adventure-Platform спасает вас от переписывания.

Библиотека существует уже несколько лет и активно поддерживается (по состоянию на написание, недавние обновления добавили поддержку 1.21.6/1.21.7). Ее используют крупные серверные программное обеспечение и плагины. Не рискованный выбор.