Autorska biblioteka do kompleksowej obsługi wiadomości i plików językowych dla pluginów oparta na rozwiązaniach net.kyori:adventure.
- 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.
Dodaj do build.gradle.kts odpowiednią wersję:
- 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
}
}-
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 globalnegolanguagez configu. -
stringMessageToStringForLocale(locale, category, key, placeholders)– jak wyżej, ale zwraca String. -
getSmartMessageForLocale(locale, category, key, placeholders)– locale-aware odpowiednikgetSmartMessage, 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:
messages_<locale>.yml(np.messages_en_us.yml)messages_<language>.yml(np.messages_en.yml)- plik bazowy wynikający z
languagew 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żenulllocale i wtedy zawsze używa globalnego fallbacku (punkt 3).
Ustaw tryb automatyczny oraz język zapasowy w konfiguracji pluginu korzystającego z biblioteki:
language: auto
fallback-language: ENNastę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
autokorzystają zfallback-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>"
formatLegacyText(message)– konwertuje tekst w formacie &-color na komponent MiniMessage. Czyli formatowanie wszystkich formatów Minecraft typu&a,&l,&nitp.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.
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.