MiniMessage: современное форматирование текста на Minecraft серверах

Если вы когда-нибудь пытались сделать красивый MOTD для Minecraft сервера или цветное сообщение в чате, то наверняка сталкивались с конструкциями вроде §6§lДобро пожаловать. Это работает, но выглядит как каша из символов. Adventure API и его формат MiniMessage решают эту проблему раз и навсегда.

В этой статье разберём, как работает MiniMessage, почему стоит перейти на него с legacy-кодов и как использовать все его возможности - от простых цветов до градиентов и интерактивных элементов.

Что такое Adventure API и MiniMessage

Adventure - это библиотека для работы с текстовыми компонентами в Minecraft. Её разработала команда KyoriPowered, и сейчас она встроена прямо в Paper, Velocity, Sponge и другие популярные серверные платформы.

MiniMessage - это формат сериализации текста внутри Adventure. Если Component API - это программный способ собирать текст из объектов в Java-коде, то MiniMessage - это способ записать то же самое одной строкой в конфиге или сообщении.

Вместо этого:

Component.text("Привет")
    .color(NamedTextColor.GOLD)
    .decorate(TextDecoration.BOLD)
    .append(Component.text(" мир").color(NamedTextColor.GREEN))

Вы пишете:

<gold><bold>Привет</bold> <green>мир</green>

Результат одинаковый, но второй вариант можно спокойно положить в YAML-конфиг, и любой админ поймёт, что происходит.

Почему §-коды устарели

Legacy-коды с символом § (или & в плагинах, которые сами заменяют его) появились ещё в бете Minecraft. У них есть несколько серьёзных проблем:

Только 16 цветов. Вы ограничены палитрой из 16 предустановленных цветов. Никаких hex-значений, никаких оттенков - только §a зелёный, §c красный и так далее.

Нет вложенности. Форматирование работает линейно. Если вы написали §l§6Текст§r, то сброс §r убирает вообще всё - и цвет, и жирный. Приходится заново прописывать цвет после каждого сброса.

Нет интерактивности. Legacy-коды не поддерживают click-события, hover-подсказки и другие возможности chat-компонентов. Это просто плоский текст с цветами.

Трудно читать. Строка §6§l✦ §e§lСервер §6§l✦ §7- §fДобро пожаловать! - попробуйте с первого взгляда понять, что там происходит.

MiniMessage решает все эти проблемы. При этом большинство инструментов, поддерживающих MiniMessage, сохраняют обратную совместимость с legacy-кодами. Вы можете переходить постепенно.

Базовый синтаксис MiniMessage

Основной принцип простой: теги в угловых скобках открывают форматирование, теги с / закрывают его.

Именованные цвета

<red>Красный текст</red>
<gold>Золотой текст</gold>
<dark_purple>Тёмно-фиолетовый</dark_purple>

Доступны все 16 стандартных цветов Minecraft: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white.

Hex-цвета

Это то, ради чего многие переходят на MiniMessage. Полная палитра из 16 миллионов цветов:

<#FF5555>Кастомный красный</#FF5555>
<color:#00AAFF>Голубой оттенок</color>
<#FFD700>Золотой</#FFD700>

Два способа записи - оба работают одинаково. Hex-цвета открывают огромные возможности для брендирования сервера.

Форматирование текста

<bold>Жирный</bold> или сокращённо <b>Жирный</b>
<italic>Курсив</italic> или <i>Курсив</i>
<underlined>Подчёркнутый</underlined> или <u>Подчёркнутый</u>
<strikethrough>Зачёркнутый</strikethrough> или <st>Зачёркнутый</st>
<obfuscated>Запутанный</obfuscated> или <obf>Запутанный</obf>

Теги можно комбинировать:

<bold><red>Жирный красный</red></bold>
<#FF0000><b><u>Красный жирный подчёркнутый</u></b></#FF0000>

Сброс форматирования

Тег <reset> сбрасывает всё форматирование. Но обычно он не нужен - достаточно закрыть тег, и форматирование прекратится само.

<red><bold>Жирный красный</bold> просто красный</red> обычный текст

Градиенты и эффекты

Вот где MiniMessage по-настоящему показывает свою силу. Попробуйте сделать градиент legacy-кодами - это десятки символов с ручным подбором цветов для каждой буквы. В MiniMessage это одна строка.

Градиент текст

<gradient:red:gold>Плавный переход от красного к золотому</gradient>
<gradient:#FF0000:#00FF00:#0000FF>Трёхцветный градиент</gradient>
<gradient:green:blue:purple>Зелёный через синий в фиолетовый</gradient>

Градиент автоматически распределяется по всем символам текста. Можно указать два, три и больше цветов - переходы будут равномерными.

Rainbow (радуга)

<rainbow>Текст всеми цветами радуги</rainbow>
<rainbow:2>Радуга с другой фазой</rainbow>

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

Transition

<transition:red:gold:0.5>Цвет на 50% между красным и золотым</transition>

В отличие от gradient, transition применяет один цвет ко всему тексту - вычисленный как промежуточное значение между указанными цветами.

Интерактивные элементы

MiniMessage поддерживает все возможности chat-компонентов Minecraft. Это работает в чате, книгах, табе и других местах, где клиент рендерит JSON-текст.

Click-события

<click:open_url:'https://example.com'>Открыть сайт</click>
<click:run_command:'/spawn'>Нажми для телепорта</click>
<click:suggest_command:'/msg '>Написать сообщение</click>
<click:copy_to_clipboard:'Скопированный текст'>Скопировать</click>

Типы click-событий:

• open_url - открывает ссылку в браузере
• run_command - выполняет команду от имени игрока
• suggest_command - вставляет текст в строку чата
• copy_to_clipboard - копирует текст в буфер обмена

Hover-подсказки

<hover:show_text:'Это подсказка'>Наведи на меня</hover>
<hover:show_text:'<red>Красная подсказка'>Наведи</hover>

Внутри hover-текста тоже работает форматирование MiniMessage. Можно делать цветные, многострочные подсказки:

<hover:show_text:'<gold>Зачарованный меч
<gray>Урон: <red>+15
<gray>Прочность: <green>1500/1500'>⚔ Меч дракона</hover>

Комбинирование

Настоящая мощь проявляется в комбинации:

<click:open_url:'https://example.com'><hover:show_text:'<aqua>Перейти на сайт'><gradient:gold:yellow><bold>Наш сайт</bold></gradient></hover></click>

Это создаёт текст с градиентом, который при наведении показывает подсказку, а при клике открывает ссылку.

Специальные теги

Переводимый текст (Translatable)

<translatable:block.minecraft.diamond_block>

Отображает название блока на языке клиента игрока. Полезно для мультиязычных серверов.

Keybind

Нажмите <keybind:key.sneak>, чтобы присесть

Показывает клавишу, привязанную к действию у конкретного игрока.

Selector

<selector:@p> - ближайший игрок

Вставка (Insertion)

<insertion:'Текст для вставки'>Нажми Shift+Click</insertion>

При Shift+Click вставляет указанный текст в строку чата.

Примеры для реальных задач

MOTD сервера

<gradient:#FF6B35:#FFD700><bold>MYSERVER</bold></gradient> <dark_gray>- <gray>Выживание 1.21
<aqua>▸ <white>Новый сезон! <green>Онлайн: <yellow>42

Приветственное сообщение

<gradient:gold:yellow>✦ Добро пожаловать, </gradient><green><bold>%player%</bold></green><gradient:yellow:gold> ✦</gradient>
<gray>Приятной игры на сервере!
<dark_gray>▸ <click:run_command:'/rules'><hover:show_text:'<yellow>Нажми, чтобы прочитать'><aqua>Правила</aqua></hover></click> <dark_gray>▸ <click:open_url:'https://discord.gg/example'><hover:show_text:'<#7289DA>Наш Discord'><#7289DA>Discord</#7289DA></hover></click>

Кик-сообщение

<red><bold>Отключён от сервера</bold></red>

<gray>Причина: <white>%reason%
<dark_gray>Обратитесь в <click:open_url:'https://discord.gg/example'><aqua>Discord</aqua></click>

Где используется MiniMessage

Paper и его форки

Paper (и форки - Purpur, Pufferfish, Folia) имеют Adventure API встроенным. Любой плагин может использовать MiniMessage напрямую:

MiniMessage mm = MiniMessage.miniMessage();
Component message = mm.deserialize("<gold>Привет, <green>" + playerName);
player.sendMessage(message);

Многие современные плагины уже поддерживают MiniMessage в конфигах: EssentialsX, LuckPerms (в некоторых контекстах), TAB, DeluxeChat и другие.

Velocity

Velocity тоже построен на Adventure API. MiniMessage работает в конфигах и плагинах для Velocity. MOTD, кик-сообщения, сообщения при переключении серверов - всё поддерживает этот формат.

MineGuard

Сервис DDoS-защиты MineGuard поддерживает MiniMessage во всех кастомных сообщениях. MOTD прокси, кик-сообщения при блокировке, сообщения на время капчи-проверки - везде можно использовать как MiniMessage-теги, так и legacy §/& коды. Это позволяет настроить внешний вид защиты под стиль вашего сервера, включая градиенты и hex-цвета.

BungeeCord / Waterfall

BungeeCord не использует Adventure нативно, но существуют библиотеки-мосты (adventure-platform-bungeecord), которые позволяют плагинам работать с MiniMessage.

Инструменты для работы с MiniMessage

MiniMessage Web Viewer

Главный инструмент - webui.advntr.dev. Это онлайн-редактор, где можно:

• Писать MiniMessage-разметку и видеть результат в реальном времени
• Проверять корректность синтаксиса
• Тестировать градиенты и цветовые комбинации
• Экспериментировать с hover и click событиями

Очень рекомендую держать эту вкладку открытой при настройке сервера.

MiniMessage API в коде

Для разработчиков плагинов:

// Базовое использование
MiniMessage mm = MiniMessage.miniMessage();
Component parsed = mm.deserialize("<red>Сообщение");

// С плейсхолдерами (безопасно от инъекций)
Component parsed = mm.deserialize(
    "Привет, <name>!",
    Placeholder.unparsed("name", playerName)
);

// С компонентными плейсхолдерами
Component parsed = mm.deserialize(
    "Привет, <name>!",
    Placeholder.component("name", playerNameComponent)
);

Обратите внимание на Placeholder.unparsed() - это важно для безопасности. Если подставлять пользовательский ввод напрямую в строку, игрок может вставить MiniMessage-теги. unparsed экранирует их.

Конвертация из legacy

Если у вас уже есть куча сообщений в legacy-формате, можно конвертировать программно:

LegacyComponentSerializer legacy = LegacyComponentSerializer.legacySection();
Component component = legacy.deserialize("§6§lТекст");
String miniMessage = MiniMessage.miniMessage().serialize(component);

Частые ошибки

Незакрытые теги. MiniMessage строгий к парности тегов. <bold>Текст без </bold> может привести к неожиданному поведению. Всегда закрывайте теги.

Неправильный порядок закрытия. Теги закрываются в обратном порядке, как в HTML:

Правильно: <bold><red>Текст</red></bold>
Неправильно: <bold><red>Текст</bold></red>

Кавычки в click/hover. Если в тексте подсказки есть кавычки, используйте разные типы:

<hover:show_text:"Текст с 'одинарными' кавычками">Наведи</hover>

Пробелы в тегах. Не ставьте пробелы внутри тегов: <bold> - правильно, < bold > - не сработает.

Советы по стилю

Несколько рекомендаций, которые приходят с опытом:

1. Не перебарщивайте с цветами. Радужный текст везде - это не стильно. Выберите 2-3 основных цвета для сервера и придерживайтесь их.

2. Градиенты - для заголовков. Используйте градиент для названия сервера, заголовков разделов. Для обычного текста лучше подходят простые цвета.

3. Hover для полезной информации. Не делайте hover ради hover. Подсказки должны давать дополнительную информацию.

4. Тестируйте на разных клиентах. Bedrock-клиенты через Geyser могут отображать текст иначе. Проверяйте, если у вас кроссплатформенный сервер.

5. Используйте переменные. Вместо хардкода цветов заведите шаблоны. Если решите сменить основной цвет сервера, будет достаточно поменять его в одном месте.

Подведём итог

MiniMessage - это то, к чему двигается экосистема Minecraft серверов. Paper уже полностью перешёл на Adventure API, Velocity с самого начала был на нём, и всё больше плагинов и сервисов (включая MineGuard) добавляют поддержку этого формата.

Если вы до сих пор используете §-коды, самое время попробовать MiniMessage. Начните с webui.advntr.dev, поэкспериментируйте с градиентами и hover-подсказками. Когда привыкнете к синтаксису, обратно уже не захочется.