MiniMessage: nowoczesne formatowanie tekstu na serwerach Minecraft

Jeśli kiedyś próbowałeś zrobić ładny MOTD dla serwera Minecraft albo kolorową wiadomość na czacie, to pewnie natknąłeś się na konstrukcje typu §6§lWitaj. To działa, ale wygląda jak chaos znaków. Adventure API i jego format MiniMessage rozwiązują ten problem raz na zawsze.

W tym artykule rozbierzemy, jak działa MiniMessage, dlaczego warto przejść na niego z legacy-kodów i jak wykorzystać wszystkie jego możliwości - od prostych kolorów po gradienty i elementy interaktywne.

Czym jest Adventure API i MiniMessage

Adventure to biblioteka do pracy z komponentami tekstowymi w Minecraft. Opracował ją zespół KyoriPowered, a obecnie jest wbudowana prosto w Paper, Velocity, Sponge i inne popularne platformy serwerowe.

MiniMessage to format serializacji tekstu wewnątrz Adventure. Jeśli Component API to programistyczny sposób składania tekstu z obiektów w kodzie Java, to MiniMessage jest sposobem zapisania tego samego jedną linią w configu lub wiadomości.

Zamiast tego:

Component.text("Witaj")
    .color(NamedTextColor.GOLD)
    .decorate(TextDecoration.BOLD)
    .append(Component.text(" świecie").color(NamedTextColor.GREEN))

Piszesz:

<gold><bold>Witaj</bold> <green>świecie</green>

Efekt jest taki sam, ale drugi wariant można spokojnie wrzucić do YAML-configa, a dowolny admin zrozumie, co się dzieje.

Dlaczego kody z § są przestarzałe

Legacy-kody ze znakiem § (albo & w pluginach, które same go zamieniają) pojawiły się jeszcze w becie Minecraft. Mają kilka poważnych problemów:

Tylko 16 kolorów. Jesteś ograniczony paletą 16 predefiniowanych kolorów. Żadnych wartości hex, żadnych odcieni - tylko §a zielony, §c czerwony i tak dalej.

Brak zagnieżdżeń. Formatowanie działa liniowo. Jeśli napisałeś §l§6Tekst§r, to reset §r usuwa absolutnie wszystko - i kolor, i pogrubienie. Trzeba na nowo wpisywać kolor po każdym resecie.

Brak interaktywności. Legacy-kody nie wspierają zdarzeń click, hover-podpowiedzi i innych możliwości chat-komponentów. To po prostu płaski tekst z kolorami.

Ciężko czytać. Linijka §6§l✦ §e§lSerwer §6§l✦ §7- §fWitaj! - spróbuj od pierwszego spojrzenia zrozumieć, co tam się dzieje.

MiniMessage rozwiązuje wszystkie te problemy. Przy tym większość narzędzi wspierających MiniMessage zachowuje wsteczną kompatybilność z legacy-kodami. Możesz przechodzić stopniowo.

Podstawowa składnia MiniMessage

Główna zasada jest prosta: tagi w nawiasach kątowych otwierają formatowanie, tagi z / je zamykają.

Nazwane kolory

<red>Czerwony tekst</red>
<gold>Złoty tekst</gold>
<dark_purple>Ciemnofioletowy</dark_purple>

Dostępne są wszystkie 16 standardowych kolorów Minecraft: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white.

Kolory hex

To dla wielu powód, żeby przejść na MiniMessage. Pełna paleta z 16 milionów kolorów:

<#FF5555>Customowy czerwony</#FF5555>
<color:#00AAFF>Odcień błękitu</color>
<#FFD700>Złoty</#FFD700>

Dwa sposoby zapisu - oba działają tak samo. Kolory hex otwierają ogromne możliwości brandingu serwera.

Formatowanie tekstu

<bold>Pogrubiony</bold> albo skrótowo <b>Pogrubiony</b>
<italic>Kursywa</italic> albo <i>Kursywa</i>
<underlined>Podkreślony</underlined> albo <u>Podkreślony</u>
<strikethrough>Przekreślony</strikethrough> albo <st>Przekreślony</st>
<obfuscated>Zaciemniony</obfuscated> albo <obf>Zaciemniony</obf>

Tagi można łączyć:

<bold><red>Pogrubiony czerwony</red></bold>
<#FF0000><b><u>Czerwony pogrubiony podkreślony</u></b></#FF0000>

Reset formatowania

Tag <reset> zeruje całe formatowanie. Ale zwykle nie jest potrzebny - wystarczy zamknąć tag i formatowanie samo się zakończy.

<red><bold>Pogrubiony czerwony</bold> zwykły czerwony</red> normalny tekst

Gradienty i efekty

To właśnie tu MiniMessage naprawdę pokazuje swoją moc. Spróbuj zrobić gradient legacy-kodami - to dziesiątki znaków z ręcznym doborem kolorów dla każdej litery. W MiniMessage to jedna linijka.

Tekst z gradientem

<gradient:red:gold>Płynne przejście z czerwieni w złoto</gradient>
<gradient:#FF0000:#00FF00:#0000FF>Trzykolorowy gradient</gradient>
<gradient:green:blue:purple>Zielony przez niebieski w fioletowy</gradient>

Gradient automatycznie rozkłada się na wszystkie znaki tekstu. Można podać dwa, trzy i więcej kolorów - przejścia będą równomierne.

Rainbow (tęcza)

<rainbow>Tekst wszystkimi kolorami tęczy</rainbow>
<rainbow:2>Tęcza z inną fazą</rainbow>

Parametr fazy (liczba po dwukropku) przesuwa kolor startowy tęczy. Przydatne, jeśli masz kilka tęczowych elementów i chcesz, żeby nie zaczynały się od tego samego koloru.

Transition

<transition:red:gold:0.5>Kolor w 50% między czerwonym a złotym</transition>

W odróżnieniu od gradient, transition stosuje jeden kolor do całego tekstu - obliczony jako wartość pośrednia między podanymi kolorami.

Elementy interaktywne

MiniMessage wspiera wszystkie możliwości chat-komponentów Minecraft. Działa to na czacie, w księgach, tabie i innych miejscach, gdzie klient renderuje tekst JSON.

Zdarzenia click

<click:open_url:'https://example.com'>Otwórz stronę</click>
<click:run_command:'/spawn'>Kliknij, żeby teleportować</click>
<click:suggest_command:'/msg '>Napisz wiadomość</click>
<click:copy_to_clipboard:'Skopiowany tekst'>Skopiuj</click>

Typy zdarzeń click:

• open_url - otwiera link w przeglądarce
• run_command - wykonuje komendę w imieniu gracza
• suggest_command - wstawia tekst w linię czatu
• copy_to_clipboard - kopiuje tekst do schowka

Hover-podpowiedzi

<hover:show_text:'To podpowiedź'>Najedź na mnie</hover>
<hover:show_text:'<red>Czerwona podpowiedź'>Najedź</hover>

Wewnątrz tekstu hover też działa formatowanie MiniMessage. Można robić kolorowe, wieloliniowe podpowiedzi:

<hover:show_text:'<gold>Zaczarowany miecz
<gray>Obrażenia: <red>+15
<gray>Wytrzymałość: <green>1500/1500'>⚔ Miecz smoka</hover>

Łączenie

Prawdziwa moc pojawia się w kombinacji:

<click:open_url:'https://example.com'><hover:show_text:'<aqua>Przejdź na stronę'><gradient:gold:yellow><bold>Nasza strona</bold></gradient></hover></click>

Tworzy to tekst z gradientem, który po najechaniu pokazuje podpowiedź, a po kliknięciu otwiera link.

Specjalne tagi

Tekst tłumaczony (Translatable)

<translatable:block.minecraft.diamond_block>

Wyświetla nazwę bloku w języku klienta gracza. Przydatne dla serwerów wielojęzycznych.

Keybind

Naciśnij <keybind:key.sneak>, żeby kucnąć

Pokazuje klawisz przypisany do akcji u konkretnego gracza.

Selector

<selector:@p> - najbliższy gracz

Wstawka (Insertion)

<insertion:'Tekst do wstawienia'>Naciśnij Shift+Click</insertion>

Przy Shift+Click wstawia podany tekst w linię czatu.

Przykłady do realnych zadań

MOTD serwera

<gradient:#FF6B35:#FFD700><bold>MYSERVER</bold></gradient> <dark_gray>- <gray>Survival 1.21
<aqua>▸ <white>Nowy sezon! <green>Online: <yellow>42

Wiadomość powitalna

<gradient:gold:yellow>✦ Witaj, </gradient><green><bold>%player%</bold></green><gradient:yellow:gold> ✦</gradient>
<gray>Miłej gry na serwerze!
<dark_gray>▸ <click:run_command:'/rules'><hover:show_text:'<yellow>Kliknij, żeby przeczytać'><aqua>Regulamin</aqua></hover></click> <dark_gray>▸ <click:open_url:'https://discord.gg/example'><hover:show_text:'<#7289DA>Nasz Discord'><#7289DA>Discord</#7289DA></hover></click>

Wiadomość kicka

<red><bold>Odłączony od serwera</bold></red>

<gray>Powód: <white>%reason%
<dark_gray>Odezwij się na <click:open_url:'https://discord.gg/example'><aqua>Discord</aqua></click>

Gdzie używa się MiniMessage

Paper i jego forki

Paper (i forki - Purpur, Pufferfish, Folia) ma Adventure API wbudowane. Każdy plugin może używać MiniMessage bezpośrednio:

MiniMessage mm = MiniMessage.miniMessage();
Component message = mm.deserialize("<gold>Witaj, <green>" + playerName);
player.sendMessage(message);

Wiele nowoczesnych pluginów już wspiera MiniMessage w configach: EssentialsX, LuckPerms (w niektórych kontekstach), TAB, DeluxeChat i inne.

Velocity

Velocity też jest zbudowany na Adventure API. MiniMessage działa w configach i pluginach dla Velocity. MOTD, wiadomości kicka, wiadomości przy przełączaniu serwerów - wszystko wspiera ten format.

MineGuard

Usługa ochrony DDoS MineGuard wspiera MiniMessage we wszystkich customowych wiadomościach. MOTD proxy, wiadomości kicka przy blokadzie, wiadomości w czasie weryfikacji captchy - wszędzie można używać zarówno tagów MiniMessage, jak i legacy-kodów §/&. Pozwala to dopasować wygląd ochrony do stylu twojego serwera, w tym gradienty i kolory hex.

BungeeCord / Waterfall

BungeeCord nie używa Adventure natywnie, ale istnieją biblioteki-mosty (adventure-platform-bungeecord), które pozwalają pluginom pracować z MiniMessage.

Narzędzia do pracy z MiniMessage

MiniMessage Web Viewer

Główne narzędzie to webui.advntr.dev. To edytor online, gdzie można:

• Pisać znaczniki MiniMessage i widzieć efekt w czasie rzeczywistym
• Sprawdzać poprawność składni
• Testować gradienty i kombinacje kolorów
• Eksperymentować ze zdarzeniami hover i click

Bardzo polecam trzymać tę kartę otwartą przy konfiguracji serwera.

MiniMessage API w kodzie

Dla deweloperów pluginów:

// Podstawowe użycie
MiniMessage mm = MiniMessage.miniMessage();
Component parsed = mm.deserialize("<red>Wiadomość");

// Z placeholderami (bezpieczne przed injection)
Component parsed = mm.deserialize(
    "Witaj, <name>!",
    Placeholder.unparsed("name", playerName)
);

// Z placeholderami komponentowymi
Component parsed = mm.deserialize(
    "Witaj, <name>!",
    Placeholder.component("name", playerNameComponent)
);

Zwróć uwagę na Placeholder.unparsed() - to ważne dla bezpieczeństwa. Jeśli wstawiasz user input bezpośrednio w stringa, gracz może wstawić tagi MiniMessage. unparsed je escapuje.

Konwersja z legacy

Jeśli masz już kupę wiadomości w formacie legacy, można skonwertować programowo:

LegacyComponentSerializer legacy = LegacyComponentSerializer.legacySection();
Component component = legacy.deserialize("§6§lTekst");
String miniMessage = MiniMessage.miniMessage().serialize(component);

Częste błędy

Niezamknięte tagi. MiniMessage jest restrykcyjny co do parzystości tagów. <bold>Tekst bez </bold> może prowadzić do nieoczekiwanego zachowania. Zawsze zamykaj tagi.

Zły porządek zamykania. Tagi zamyka się w odwrotnej kolejności, jak w HTML:

Poprawnie: <bold><red>Tekst</red></bold>
Niepoprawnie: <bold><red>Tekst</bold></red>

Cudzysłowy w click/hover. Jeśli w tekście podpowiedzi są cudzysłowy, używaj różnych typów:

<hover:show_text:"Tekst z 'pojedynczymi' cudzysłowami">Najedź</hover>

Spacje w tagach. Nie stawiaj spacji wewnątrz tagów: <bold> jest poprawne, < bold > nie zadziała.

Rady stylistyczne

Kilka rekomendacji, które przychodzą z doświadczeniem:

1. Nie przeginaj z kolorami. Tęczowy tekst wszędzie to nie styl. Wybierz 2-3 główne kolory dla serwera i trzymaj się ich.

2. Gradienty do nagłówków. Używaj gradientu do nazwy serwera, nagłówków sekcji. Do zwykłego tekstu lepiej pasują proste kolory.

3. Hover dla przydatnych informacji. Nie rób hover dla hover. Podpowiedzi mają dawać dodatkową informację.

4. Testuj na różnych klientach. Klienty Bedrock przez Geyser mogą renderować tekst inaczej. Sprawdzaj, jeśli masz serwer cross-platform.

5. Używaj zmiennych. Zamiast hardkodować kolory, zrób szablony. Jeśli zdecydujesz się zmienić główny kolor serwera, wystarczy zmienić go w jednym miejscu.

Podsumowanie

MiniMessage to kierunek, w który zmierza ekosystem serwerów Minecraft. Paper już w pełni przeszedł na Adventure API, Velocity od początku był na nim, a coraz więcej pluginów i usług (w tym MineGuard) dodaje wsparcie tego formatu.

Jeśli nadal używasz kodów z §, to najlepszy moment, żeby spróbować MiniMessage. Zacznij od webui.advntr.dev, poeksperymentuj z gradientami i hover-podpowiedziami. Gdy przyzwyczaisz się do składni, z powrotem już nie zechcesz.