MessageHandler

Opis

Autorska biblioteka do kompleksowej obsługi wiadomości i plików językowych dla pluginów oparta na rozwiązaniach net.kyori:adventure.

Warianty

• MessageHandler-Paper – wersja dla serwerów Paper/Folia i kompatybilnych forków.
• MessageHandler-Spigot – odpowiednik dla serwerów Bukkit/Spigot.
• MessageHandler-BungeeCord – wersja przygotowana pod proxy BungeeCord.
• MessageHandler-Velocity – wersja przygotowana pod proxy Velocity.

Jak dodać?

Dodaj do build.gradle.kts odpowiednią wersję:

Paper/Spigot

• Snapshot:

repositories {
    mavenCentral()
    maven("https://nexus.syntaxdevteam.pl/repository/maven-snapshots/") //SyntaxDevTeam
    maven("https://nexus.syntaxdevteam.pl/repository/maven-releases/") //SyntaxDevTeam
}

dependencies {
    // Paper/Purpur/Folia
    implementation("pl.syntaxdevteam:messageHandler-paper:1.2.0-R0.2-SNAPSHOT")
    // lub Spigot/Bukkit
    // implementation("pl.syntaxdevteam:messageHandler-spigot:1.2.0-R0.2-SNAPSHOT")
    // lub BungeeCord
    // implementation("pl.syntaxdevteam:messageHandler-bungeecord:1.2.0-R0.2-SNAPSHOT")
    // lub Velocity
    // implementation("pl.syntaxdevteam:messageHandler-velocity:1.2.0-R0.2-SNAPSHOT")
}

W klasie głównej dodaj:

import pl.syntaxdevteam.message.SyntaxMessages

class TwojPLuginX : JavaPlugin() {
    lateinit var messageHandler: MessageHandler

  override fun onEnable() {
        SyntaxMessages.initialize(this)
        messageHandler = SyntaxMessages.messages
  }
}

Opisy podstawowych metod do obsługi wiadomości

• reloadMessages() – ponownie wczytuje konfigurację językową i czyści wszystkie cache wiadomości, by kolejne odczyty korzystały z aktualnych danych. Dodaje się najczęściej do komendy reload.

• getPrefix() – zwraca aktualny prefiks dodawany do wiadomości użytkownika.

• stringMessageToComponent(category, key, placeholders) – podstawowa metoda która buduje komponent MiniMessage z prefiksem na podstawie wpisu YAML i podstawionych placeholderów.

  Przykład użycia:

  val wiadomosc = messageHandler.stringMessageToComponent("errors", "no-permission", map.of("player", playerName))

• stringMessageToString(category, key, placeholders) – zwraca sformatowany tekst MiniMessage jako String z prefiksem, zachowując kolory i placeholdery stosowana tam gdzie wymagany jest czysty String zamiast komponentu.

• stringMessageToStringNoPrefix(category, key, placeholders) – tak jak powyższa metoda ale ta zwraca treść wiadomości jako „czysty” String bez prefiksu, ale po przetworzeniu MiniMessage.

• stringMessageToComponentForLocale(locale, category, key, placeholders) – wariant API przygotowany pod dobór pliku językowego zależnie od locale klienta (np. en_us), bez zmiany globalnego language z configu.

• stringMessageToStringForLocale(locale, category, key, placeholders) – jak wyżej, ale zwraca String.

• getSmartMessageForLocale(locale, category, key, placeholders) – locale-aware odpowiednik getSmartMessage, działający dla wpisu pojedynczego i listy.

  Aktualnie zaimplementowane w modułach: MessageHandler-Paper, MessageHandler-Spigot, MessageHandler-BungeeCord i MessageHandler-Velocity.

  Kolejność fallback dla API locale-aware:

  1. messages_<locale>.yml (np. messages_en_us.yml)
  2. messages_<language>.yml (np. messages_en.yml)
  3. plik bazowy wynikający z language w configu (tryb zgodny wstecznie)

  Uwaga dla proxy (BungeeCord/Velocity):

  • locale gracza może być chwilowo niedostępne na bardzo wczesnym etapie połączenia,
  • API ...ForLocale(...) przyjmuje także null locale i wtedy zawsze używa globalnego fallbacku (punkt 3).

Automatyczny język gracza

Ustaw tryb automatyczny oraz język zapasowy w konfiguracji pluginu korzystającego z biblioteki:

language: auto
fallback-language: EN

Następnie przekaż gracza do przeciążonej metody:

player.sendMessage(
    messageHandler.stringMessageToComponent(player, "messages", "welcome")
)

Dostępne są także stringMessageToString(player, ...) i getSmartMessage(player, ...). Biblioteka odczyta locale wysłane przez klienta Minecraft i spróbuje kolejno pliku dla pełnego locale oraz języka, np. dla pl_PL: messages_pl_pl.yml, potem messages_pl.yml. Jeśli żaden z nich nie istnieje albo locale nie jest jeszcze dostępne, użyje messages_en.yml wskazanego przez fallback-language. Pliki dostępne do automatycznego wyboru należy umieścić w katalogu lang pluginu. Przy ustawieniu language: PL, EN, DE itp. nowe przeciążenia zachowują dotychczasowy, globalny wybór języka.

Metody bez parametru gracza nie mogą rozpoznać odbiorcy i w trybie auto korzystają z fallback-language. Dla konsoli jest to oczekiwane zachowanie.

• stringMessageToComponentNoPrefix(category, key, placeholders) – generuje komponent przeznaczony nie tylko do logów ale napisany z myślą o nich, konwertując zapis legacy/section na MiniMessage i pomijając prefiks.

  Przykłąd użycia:

  val logWiadomosc = messageHandler.stringMessageToComponentNoPrefix("logs", "user-joined", map.of("user", userName))
  logger.info(logWiadomosc)

• getSmartMessage(category, key, placeholders) – inteligentnie obsługuje zarówno pojedynczy wpis tekstowy, jak i listę, zwracając listę komponentów gotowych do wyświetlenia. Przykład zastosowania w pliku YAML:

  Wersja 1 – pojedynczy wpis tekstowy:

    broadcast: "<dark_gray>Gracz <gray><player></gray> został wyrzucony z powodu <gray><reason></gray></dark_gray>"

  

  Wersja 2 – lista wpisów tekstowych:

   broadcast:
     - "<dark_gray>*************** Twoja Nazwa Serwera *************** </dark_gray>"
     - ""
     - "<red>   Gracz <white><player></white> został wyrzucony</red>"
     - "   Powód: <white><reason></white>"
     - ""
     - "<dark_gray>*************************************************** </dark_gray>"

  

Metody do formatowania tekstu

• formatLegacyText(message) – konwertuje tekst w formacie &-color na komponent MiniMessage. Czyli formatowanie wszystkich formatów Minecraft typu &a, &l, &n itp.
• formatHexAndLegacyText(message) – obsługuje zarówno kody &#rrggbb, jak i § podczas konwersji do komponentu.
• miniMessageFormat(message) – parsuje surowy ciąg MiniMessage do komponentu Adventure.
• getANSIText(component) – serializuje komponent do kolorowego ANSI (np. na konsolę).
• getPlainText(component) – sprowadza komponent do czystego tekstu pozbawionego formatowania.
• formatMixedTextToMiniMessage(message, resolver) – przyjmuje tekst mieszany (MiniMessage + legacy + § + sekwencje \uXXXX) i zwraca poprawnie zdeserializowany komponent, opcjonalnie z resolverem placeholderów. Najczęściej używane do przetwarzania tekstu wprowadzonych przez użytkowników, bo kompleksowo żąda wszystkie możliwe formaty.
• formatMixedTextToLegacy(message, resolver)` – przyjmuje tekst mieszany (MiniMessage + legacy + § + sekwencje \uXXXX) i zwraca poprawnie zdeserializowany komponent, opcjonalnie z resolverem placeholderów. Najczęściej używane do przetwarzania tekstu wprowadzonych przez użytkowników, bo kompleksowo żąda wszystkie możliwe formaty.

---

Component adapters (Paper and Spigot, R0.3)

formatRichTextToComponent(text, resolver) parses configured fragments containing both MiniMessage and legacy formatting. stringMessageToComponentNoPrefixLiteral(category, key, values) renders dynamic text literally while applying formatting from the language template. componentToString(component, format) serializes built components with the handler's codecs; getMessageFormat(category, key, includePrefix) preserves the source template's format when adapting components. Existing message parsing APIs retain their behavior.