PlaceholderAPI — przewodnik po placeholderach Minecraft

Czym jest PlaceholderAPI?

PAPI to centralny rejestr zmiennych tekstowych dla serwera Minecraft. Każdy plugin może się zarejestrować i powiedzieć: „kiedy zobaczysz %mojplugin_punkty%, zapytaj mnie o aktualną wartość".

• placeholdery mają format %identifier_name%,
• działają w czasie rzeczywistym (wartość pobierana przy rozwijaniu),
• działają w kontekście gracza (znają, kto otrzymuje wiadomość),
• są ograniczone do tekstu (string in → string out).

Bez PAPI każdy plugin musiałby implementować własną integrację z każdym innym pluginem. Z PAPI istnieje jeden wspólny język i wszyscy go używają.

Instalacja

Pobierz JAR z extendedclip.com/papi albo Modrinth. Wrzuć do plugins/, zrestartuj. Sprawdź wersję: /papi info.

Sam PAPI to pusty silnik — nie ma żadnych placeholderów out of the box. Wartości dostarczają ekspansje (expansions).

eCloud — biblioteka oficjalnych ekspansji

PlaceholderAPI ma własny system zarządzania ekspansjami przez chmurę:

/papi ecloud list                    # lista wszystkich
/papi ecloud list popular            # najpopularniejsze
/papi ecloud info NazwaEkspansji
/papi ecloud download NazwaEkspansji
/papi reload                          # przeładuj po instalacji
/papi list                            # lokalnie zainstalowane

Ekspansje są pobierane do plugins/PlaceholderAPI/expansions/. Po instalacji od razu działają w każdym pluginie, który czyta placeholdery.

Najważniejsze placeholdery — Player i Server

Dwie najpopularniejsze ekspansje są zazwyczaj wbudowane (lub instalujesz w pierwszej kolejności):

%player_name%
%player_displayname%
%player_uuid%
%player_world%
%player_x%, %player_y%, %player_z%
%player_health%, %player_food_level%
%player_ping%
%player_gamemode%
%player_first_played%
%player_last_played%

%server_online%, %server_max_players%
%server_motd%
%server_name%
%server_uptime%
%server_total_chunks%
%server_total_entities%
%server_ram_used%
%server_ram_max%
%server_tps%
%server_tps_1%, %server_tps_5%, %server_tps_15%

To zestaw wystarcza, by zrobić sensowny tablist (TAB plugin) lub scoreboard (FeatherBoard).

LuckPerms expansion — prefiksy i grupy

Po /papi ecloud download LuckPerms dostajesz:

%luckperms_prefix%
%luckperms_suffix%
%luckperms_primary_group_name%
%luckperms_groups%                    # lista, separator domyślny
%luckperms_inherits_group_admin%      # true/false
%luckperms_meta_meta_key%             # custom meta
%luckperms_weight%                    # waga grupy

To one stoją za kolorowymi prefiksami w czacie i tablistcie. Format czatu w EssentialsXChat:

format: '%luckperms_prefix%&7{DISPLAYNAME}&8: &f{MESSAGE}'

Vault expansion — ekonomia

%vault_eco_balance%
%vault_eco_balance_formatted%        # 1,000 zamiast 1000
%vault_eco_balance_fixed%            # 1000.00
%vault_prefix%
%vault_suffix%
%vault_group%

Wraz z LuckPerms tworzą podstawę: prefiks z grupy, balance z ekonomii, wszystko w jednej linijce czatu.

Najpopularniejsze ekspansje (warto mieć)

• Player, Server — fundament,
• LuckPerms — prefiksy i grupy,
• Vault — ekonomia,
• Statistic — statystyki vanilla (bloki kopane, czas grania, mile chodzone),
• Math — proste obliczenia matematyczne,
• JavaScript — embed JS dla zaawansowanej logiki,
• Checkitem — sprawdzanie itemu w ekwipunku,
• SkinsRestorer — info o skin'ie,
• Citizens — info o NPC.

Większość pluginów ekonomicznych (ShopGUI+, MagicChest, AuctionGUI) ma własne placeholdery — wystarczy je zainstalować, a PAPI je rozpozna.

Testowanie placeholderów

/papi parse me %player_name%
/papi parse Marcin %luckperms_prefix%
/papi parse me %server_tps_5%

Komenda /papi parse rozwija placeholdery w kontekście wybranego gracza. Idealne do debugu — gdy %vault_eco_balance% pokazuje 0 zamiast salda, sprawdzasz w /papi parse Nick, czy w ogóle Vault dostarcza dane.

Tworzenie własnych placeholderów

PAPI ma natywne wsparcie dla custom placeholderów przez plik config.yml:

custom:
  serwer_nazwa: SerwerMinecraft.pl
  godzina_otwarcia: '%javascript_pl_local_hour%:00'
  rang_kolor:
    matcher: '%luckperms_primary_group_name%'
    cases:
      admin: '&c'
      vip: '&6'
      default: '&7'

Po /papi reload dostępne są jako %customplaceholder_serwer_nazwa% i tak dalej.

Pluginy, które bez PAPI nie mają sensu

• TAB (NEZNAMY) — tablist + sidebar + nametagi, w 100% PAPI-driven,
• FeatherBoard — animowany scoreboard,
• DeluxeMenus — GUI menusy z placeholderami,
• DecentHolograms / HolographicDisplays — hologramy z dynamicznymi danymi,
• ScoreboardX, Animated Scoreboard,
• BetonQuest, Quests — questy z dynamicznymi celami.

Wydajność — częsty problem na dużych serwerach

Placeholdery są szybkie, ale nie darmowe. Najczęstsze błędy:

• Scoreboard z 15 placeholderami odświeżany co tick — to 300 wywołań/s per gracz,
• Hologramy nad każdą skrzynią — jeśli każdy %shop_price% robi DB query, lagujesz,
• %javascript_*% — wykonanie skryptu JS przy każdym wywołaniu, należy używać oszczędnie,
• Custom placeholdery z matcher — dla każdej zmiennej dwa wywołania pod spodem.

Reguła: refresh rate scoreboardu/tablistu max 1× na sekundę dla danych zmiennych, 5× na minutę dla statystyk i konfiguracji.

Podsumowanie

PlaceholderAPI to klej, który spina wszystkie pluginy serwera w jeden spójny ekosystem. Sam w sobie nic nie wyświetla, ale bez niego TAB i scoreboard są puste, czat nie ma prefiksów, hologramy są statyczne. Zainstaluj PAPI, pobierz pięć podstawowych ekspansji (Player, Server, LuckPerms, Vault, Statistic) i masz fundament pod dowolne wizualne dostosowania serwera.

Custom placeholdery w config.yml wystarczają na 90% własnych przypadków — od kolorów per ranga po dynamiczne wiadomości. Dla skomplikowanej logiki sięga się po ekspansję JavaScript, ale w praktyce większość serwerów nigdy jej nie potrzebuje. PAPI to plugin, który stawiasz raz, konfigurujesz raz i potem nie wracasz do niego przez lata.