PlaceholderAPI na serwerze Minecraft: konfiguracja, expansions, przyklady

PlaceholderAPI (zwykle skracane do PAPI) to plugin-most, przez który inne pluginy wymieniają się dynamicznymi danymi. Bez niego połowa nowoczesnych funkcji w TAB, scoreboardzie i czacie po prostu nie działa. Przejdziemy przez instalację, najważniejsze expansions i miejsca, w których PAPI naprawdę się przydaje.

Czym jest PlaceholderAPI i po co go używać

Sam PAPI nie robi nic. To plugin-API, który daje innym pluginom jeden wspólny format do podstawiania danych w stringi. Każdy plugin, który chce pokazać nazwę gracza, jego saldo, grupę LuckPerms albo aktualne TPS, wpisuje w configu %player_name% lub %vault_eco_balance%, a PAPI w locie zamienia to na prawdziwą wartość.

Największa zaleta to jeden format na wszystko. Wcześniej plugin TAB miał swoje placeholdery, plugin scoreboarda inne, czat trzecie. Z PAPI mamy uniwersalną składnię, a każdy plugin, który ją obsługuje, czyta dane z dowolnego źródła.

W praktyce PAPI działa na około 90% serwerów, od małych SMP po duże sieci minigame. Jeśli stawiasz serwer z TAB, scoreboardem, custom-czatem albo hologramami, niemal na pewno go potrzebujesz.

Instalacja PlaceholderAPI

Stabilną wersję pobierzesz ze Spigot. Wrzucasz .jar do plugins/, restartujesz serwer. Tyle.

Po pierwszym uruchomieniu PAPI tworzy folder plugins/PlaceholderAPI/ z podfolderem expansions/. Tam trafiają dodatki dostarczające konkretne placeholdery. Sam PAPI bez nich jest praktycznie bezużyteczny, więc kolejny krok jest ważniejszy niż sama instalacja.

Kompatybilność wersji: Paper i Spigot 1.16.5 do 1.21.x. Dla Folii istnieje osobny fork PAPI 2.11+. Zwykła wersja na Folii nie wystartuje przez różnice w schedulerze.

Zasada działania: provider i consumer

PAPI ma prosty model. Provider (expansion) to plugin lub moduł, który dostarcza dane. Consumer to plugin, który te dane wstawia we własne wiadomości.

Przykład. W configu pluginu TAB piszesz:

header: '&aOnline: %server_online%/%server_max_players%'

Plugin TAB widzi %server_online%, pyta PAPI, PAPI znajduje odpowiednią expansion (tutaj Server) i zwraca aktualną liczbę graczy. Plugin TAB nie musi wiedzieć, jak serwer liczy tę wartość, i o to chodzi.

Przydatne komendy

PAPI dostarcza kilka komend do debugowania i zarządzania:

/papi list
/papi info <expansion>
/papi parse <player> <text>
/papi parse me %player_name% has $%vault_eco_balance%
/papi reload
/papi ecloud download <expansion>

/papi parse me <text> to najważniejsze narzędzie do debugowania. Jeśli placeholder w TAB albo na czacie wyświetla się dosłownie (%player_name% zamiast nazwy), uruchom tę komendę. Jeżeli PAPI poprawnie go rozwiązuje, problem leży po stronie consumer-pluginu. Jeśli zwraca surowy tekst, expansion nie jest zainstalowana albo masz literówkę.

Instalacja expansions przez ecloud

Kiedyś expansions pobierało się ręcznie ze strony. Teraz jest wbudowany ecloud:

/papi ecloud download Player
/papi ecloud download Vault
/papi ecloud download Statistic
/papi ecloud download Server
/papi ecloud download Math
/papi reload

Po każdym pobraniu robisz /papi reload albo restart serwera. Bez tego expansion leży w folderze, ale jest nieaktywna.

Solidny zestaw startowy dla większości serwerów: Player, Server, Vault (jeśli masz ekonomię), LuckPerms (jeśli na nim ustawiasz uprawnienia), Statistic (do statystyk gry).

Najważniejsze expansions

Player - podstawowa, instalowana niemal zawsze. Daje %player_name%, %player_displayname%, %player_uuid%, %player_health%, %player_food_level%, %player_world%, %player_ping%, koordynaty, gamemode i dziesiątki innych pól.

Server - dane o serwerze. %server_online%, %server_max_players%, %server_unique_joins%, %server_tps_1%, %server_uptime%, %server_ram_used%. Placeholdery TPS są szczególnie cenne dla adminowych scoreboardów.

Vault - ekonomia i grupy przez Vault API. %vault_eco_balance%, %vault_eco_balance_formatted% (z separatorami tysięcy), %vault_prefix%, %vault_suffix%, %vault_group%. Działa z każdą ekonomią, która hookuje się w Vault: EssentialsX, CMI, TheNewEconomy.

LuckPerms - wybór, jeśli używasz LuckPerms (a większość używa). %luckperms_primary_group_name%, %luckperms_prefix%, %luckperms_suffix%, %luckperms_meta_<key>%. Lepszy od Vault dla prefix/suffix, bo nie gubi kolorów.

Statistic - statystyki gry z Bukkit API. %statistic_play_one_minute% (łączny czas gry), %statistic_mob_kills%, %statistic_deaths%, %statistic_blocks_broken%. Uwaga: niektóre pola to ciężkie zapytania, nie pakuj 20 takich do TAB na każdego gracza.

Math - matematyka w samym placeholderze. %math_0_{%player_health%}/2% zwróci połowę życia. Wygodne do obliczeń w scoreboardzie bez pisania skryptów.

Custom-placeholdery przez JavaScript

Do nietypowych przypadków jest JavaScript expansion. Pozwala napisać własny placeholder w JS bez kompilowania osobnego pluginu.

Przykład: chcesz %js_kdr% liczący stosunek k/d gracza. Tworzysz plugins/PlaceholderAPI/javascript_placeholders.yml:

kdr:
  description: 'Kill / death ratio'
  script_file: 'kdr.js'

I sam skrypt plugins/PlaceholderAPI/javascripts/kdr.js:

function kdr(player, args) {
    var kills = parseInt(PlaceholderAPI.setPlaceholders(player, "%statistic_player_kills%"));
    var deaths = parseInt(PlaceholderAPI.setPlaceholders(player, "%statistic_deaths%"));
    if (deaths === 0) return kills.toFixed(2);
    return (kills / deaths).toFixed(2);
}

Po /papi reload placeholder %javascript_kdr% działa wszędzie. Silnik Nashorn JS został usunięty w Java 11+, więc na nowoczesnych wersjach instalujesz GraalVM JS albo używasz forka PlaceholderAPI Javascript Expansion.

Gdzie używać PAPI na serwerze

TAB / Tablist (TAB plugin) - klasyk. Header, footer, nazwy graczy w liście, scoreboard z tego samego pluginu, wszystko przez PAPI.

Pluginy scoreboarda - FeatherBoard, AnimatedScoreboard, sam TAB. Dynamiczne tablice z saldem, rangą i czasem gry budują się w całości na PAPI.

Pluginy czatu - DeluxeChat, EssentialsXChat, VentureChat. Format wiadomości i hover/click events pisze się z placeholderami.

Hologramy - HolographicDisplays, DecentHolograms. Leaderboardy top-graczy, saldo nad bankomatem, aktualny licznik online.

ItemsAdder, Oraxen, MMOItems - format wyświetlanej nazwy i lore przedmiotów często używa PAPI do dynamicznych pól.

Skrypty Skript - wbudowane wsparcie przez parsed placeholder.

Praktyczny przykład: format TAB i czatu

Config pluginu TAB z placeholderami:

header:
  - '&8&m-----&r &aMineGuard &8&m-----'
  - '&7Online: &a%server_online%&7/&a%server_max_players%'
  - '&7TPS: &a%server_tps_1%'
footer:
  - '&7Balance: &6$%vault_eco_balance_formatted%'
  - '&7Group: &b%luckperms_primary_group_name%'
  - '&7Ping: &e%player_ping%ms'

Config DeluxeChat dla czatu:

formats:
  default:
    priority: 100
    format: '%luckperms_prefix%%player_name%%luckperms_suffix% &8» &f{message}'
  vip:
    priority: 50
    permission: 'group.vip'
    format: '&6[VIP] %player_name% &8» &e{message}'

W EssentialsXChat placeholdery włącza się w essentials/config.yml:

chat:
  format: '{DISPLAYNAME} &8» &f{MESSAGE}'
  group-formats:
    vip: '&6[VIP] {DISPLAYNAME} &8» &e{MESSAGE}'

EssentialsXChat wspiera PAPI od EssentialsX 2.19+. Wcześniej trzeba było mieć osobny plugin EssentialsXChat-PlaceholderAPI Hook.

Wydajność i cache

Sam PAPI jest szybki. Problemy zaczynają się przy ciężkich expansions, które na każde wywołanie placeholdera lecą do bazy. Przykład: %statistic_play_one_minute% dla wszystkich 100 graczy w TAB co 2 sekundy to 50 zapytań SQL na sekundę, a jeśli statystyki siedzą w bazie, to już zauważalne obciążenie.

Co robić:

• Nie pakuj więcej niż 5-10 placeholderów na gracza w jedną linię TAB. Statystyki per-gracz mnożą się przez online.
• Zwiększ interwał odświeżania w pluginie TAB. Domyślnie zwykle 1 sekunda, 5-10 sekund spokojnie wystarczy dla większości placeholderów.
• Relational placeholders tylko, gdy faktycznie trzeba. Są droższe, bo liczą się dla pary graczy, nie jednego.
• Profiluj przez timings. /timings paste pokaże wtyczki zjadające czas i konkretna expansion może tam wyjść.

Gdy placeholder nie działa

Typowe sytuacje, w których %player_name% wyświetla się dosłownie:

1. PAPI nie jest zainstalowane lub się nie załadowało - sprawdź /plugins, wpis powinien być zielony.
2. Expansion nie pobrana - /papi list pokazuje aktywne. Brakuje twojej, więc /papi ecloud download <name>.
3. Plugin nie używa PAPI - nie każdy plugin czyta placeholdery. Czyste Bukkit MOTD z server.properties ich nie parsuje, potrzebny osobny plugin MOTD z obsługą PAPI.
4. Literówka w nazwie - %player_health% działa, %player_hp% nie. /papi list pokaże dokładne nazwy.
5. Hook PAPI w consumer-pluginie jest opcjonalny - niektóre configi mają flagę placeholderapi: true, domyślnie wyłączoną.

/papi parse me <text> to twoje główne narzędzie. Jeśli rozwiązuje placeholder, a consumer-plugin nie, znaczy że consumer nie aktywował swojego hooka PAPI.

FAQ

Co jest lepsze, PlaceholderAPI czy MVdWPlaceholderAPI

PAPI to dziś standard branżowy. MVdWPlaceholderAPI był popularny na 1.8 i 1.12, ale autor od lat go nie wspiera. Większość nowoczesnych pluginów obsługuje oba przez plugin-mostek MVdWPlaceholderAPI Hook, ale jeśli stawiasz serwer od zera, bierzesz PAPI i nie oglądasz się za siebie.

Jak napisać własną expansion

Tworzysz plugin Java albo standalone .jar w folderze expansions/. Klasa dziedziczy po PlaceholderExpansion, nadpisujesz onPlaceholderRequest(Player p, String identifier) i zwracasz wartość. W getIdentifier() ustawiasz prefix (np. myplugin dla %myplugin_xxx%). Działające przykłady są na GitHub PAPI.

Czy można używać PAPI w nazwie przedmiotu

Tylko jeśli plugin renderujący przedmiot wspiera placeholdery. Czyste Bukkit ItemStack ich nie parsuje. ItemsAdder, Oraxen, MMOItems i DeluxeMenus to potrafią. Do własnych GUI zwykle używa się DeluxeMenus jako frontendu.

Czemu %vault_eco_balance% zwraca 0

Trzy powody. Pierwszy: Vault nie zainstalowany albo nie znalazł providera ekonomii (potrzebujesz EssentialsX, CMI lub innego pluginu z Vault hookiem). Drugi: gracz nie ma jeszcze konta w ekonomii (Essentials zakłada przy pierwszym wejściu po instalacji). Trzeci: używasz %vault_eco_balance_formatted% i wartość jest po prostu na tyle mała, że zaokrągla się do 0.

Czy dużo placeholderów w TAB mocno obciąża serwer

Zależy które. Player i Server są tanie, czytają z pamięci. Statistic, LuckPerms-meta i custom-placeholdery oparte o SQL są droższe. W praktyce 5-10 placeholderów na gracza w TAB z interwałem 5 sekund nie daje zauważalnego obciążenia nawet przy 200 online. Problemy zaczynają się od 50+ placeholderów odświeżanych co sekundę.

Co to są relational placeholders

Placeholdery o formie %rel_<expansion>_<id>%, liczone dla pary graczy (viewer i target). Używane głównie w TAB do kolorowania nazw zależnie od relacji (przeciwnik czerwony, sojusznik zielony). Droższe niż zwykłe, bo liczą się N×M razy zamiast N.

Co dalej

Zainstaluj zestaw bazowy - Player, Server, Vault, LuckPerms - i odpal /papi list, żeby zobaczyć, co masz dostępne. Potem dorzuć plugin TAB i zbuduj scoreboard. Gdy zechcesz czegoś niestandardowego, JavaScript expansion zamyka większość przypadków bez pisania osobnego pluginu.

Jeśli używasz PAPI intensywnie na dużym serwerze, raz w tygodniu odpalaj /timings paste i sprawdzaj, czy jakaś expansion nie wlazła na szczyt listy obciążenia. Najczęściej to Statistic albo własna expansion z ciężkimi zapytaniami.