GameHosting.pl

Notatki operatora

PlaceholderAPI (PAPI): ekspansje i placeholdery na serwerze Minecraft

PlaceholderAPI, w skrócie PAPI, to jeden z tych pluginów, który prawie każdy inny wymaga, a który sam z siebie nie pokazuje graczowi niczego. Ten przewodnik tłumaczy, czym tak naprawdę jest PAPI, czym są ekspansje i repozytorium eCloud, jak się go instaluje i jakimi komendami nim zarządzasz. Na koniec pokazuję, jak wpiąć placeholdery w tab czy scoreboard. Z perspektywy kogoś, kto raz za razem odpowiadał na pytanie „zainstalowałem PAPI i nic się nie dzieje”.

Opublikowano · ~8 min czytania

W skrócie: PlaceholderAPI to wspólny mechanizm, który dostarcza placeholdery (na przykład %player_name%) innym pluginom. Sam nic nie wyświetla, robi to dopiero plugin tab, scoreboard albo czat. Po wgraniu pliku .jar do plugins/ dokładasz potrzebne ekspansje z eCloud komendą /papi ecloud download <nazwa>, przeładowujesz /papi reload, a działanie sprawdzasz /papi parse me %placeholder%. Jeśli nie chcesz pilnować ekspansji i zgodności wersji ręcznie, weź hosting z gotową obsługą wtyczek.

Czym jest PlaceholderAPI i czemu tyle pluginów go wymaga

PlaceholderAPI (PAPI) to plugin Bukkit dla serwerów Spigot i Paper, którego jedynym zadaniem jest dostarczanie placeholderów. Placeholder to krótki znacznik w formacie %nazwa%, który podczas wyświetlania zostaje podmieniony na konkretną wartość, na przykład %player_name% zamienia się na nick gracza, a %server_online% na liczbę graczy aktualnie online.

Najważniejsza rzecz, którą trzeba zrozumieć od razu: PlaceholderAPI sam niczego nie wyświetla. To biblioteka, wspólny standard, z którego korzystają inne pluginy. Dzięki niemu autorzy pluginów do tab, scoreboardów, czatu, holographicznych tablic czy menu nie muszą sami pisać kodu pobierającego dane z LuckPerms, ekonomii czy świata. Wystarczy, że wstawią w swoich ustawieniach placeholder %...%, a PlaceholderAPI podmieni go na wartość.

To właśnie dlatego tyle pluginów ma PAPI jako zależność (dependency). On jest spoiwem. Jeden plugin dostarcza dane przez PAPI, drugi je wyświetla przez PAPI, a oba nie muszą o sobie nic wiedzieć. Skutek uboczny jest taki, że nowy operator instaluje PlaceholderAPI, restartuje serwer i ze zdziwieniem stwierdza, że nic się nie zmieniło. To normalne, samo PAPI nie ma żadnego widocznego interfejsu, ożywa dopiero w połączeniu z pluginami, które go używają.

Instalacja PlaceholderAPI

Instalacja jest krótka, bo PAPI to zwykły plugin Bukkit. Kroki:

  1. Sprawdź wersję serwera. PlaceholderAPI wydawane jest pod konkretne wersje Minecrafta. Najpierw ustal, na czym chodzi serwer (na przykład 1.20.x czy 1.21.x), i pobierz pasujące wydanie.
  2. Pobierz plik .jar. PlaceholderAPI bierzesz z jego oficjalnej strony na SpigotMC. To jeden plik .jar.
  3. Wrzuć do folderu plugins. Skopiuj PlaceholderAPI.jar do katalogu plugins/ na serwerze. Nie rozpakowuj, plugin to gotowy plik jar.
  4. Zrestartuj serwer. Po starcie w logu konsoli pojawi się komunikat o załadowaniu PlaceholderAPI, a w plugins/PlaceholderAPI/ powstanie folder konfiguracyjny.
  5. Sprawdź komendą. Wpisz /papi (lub /placeholderapi), zobaczysz listę dostępnych podkomend. To znak, że plugin działa i możesz przejść do ekspansji.

Na tym etapie PAPI działa, ale zna tylko podstawowe placeholdery. Resztę dokładasz przez ekspansje, o których za chwilę.

Ekspansje (expansions) i repozytorium eCloud

Tu jest sedno PlaceholderAPI. Plugin sam w sobie zna garść podstawowych placeholderów (głównie dane gracza i serwera), a wszystko inne dokłada się w postaci ekspansji. Ekspansja to mały dodatek, który wnosi nowy zestaw placeholderów dla konkretnego tematu, na przykład:

Większość ekspansji pobiera się z eCloud, czyli oficjalnego repozytorium ekspansji PlaceholderAPI. Robisz to bez ręcznego ściągania plików, prosto z gry albo konsoli, komendą /papi ecloud download <nazwa>. Po pobraniu przeładowujesz plugin komendą /papi reload i placeholdery z tej ekspansji stają się dostępne dla wszystkich pluginów, które ich używają.

Zasada do zapamiętania: ekspansja dokłada tylko placeholdery, nie zastępuje pluginu źródłowego. Żeby %luckperms_prefix% coś zwracał, na serwerze musi działać sam LuckPerms; żeby placeholdery ekonomii miały wartości, musi działać Vault wraz z pluginem ekonomii. Ekspansja to most między tym pluginem a PAPI, a nie jego zamiennik.

Komendy PlaceholderAPI

Z PAPI zarządzasz kilkoma komendami pod /papi (równoważne pełnemu /placeholderapi). Oto te, których używa się na co dzień:

KomendaCo robi
/papi ecloud download <ekspansja>Pobiera ekspansję z repozytorium eCloud (na przykład /papi ecloud download Player).
/papi reloadPrzeładowuje PlaceholderAPI i wczytuje świeżo pobrane lub zaktualizowane ekspansje.
/papi listWypisuje ekspansje, które są obecnie zarejestrowane i aktywne na serwerze.
/papi parse me %player_name%Pokazuje, na co podmieni się dany placeholder dla Ciebie. Najszybszy test, czy placeholder działa.
/papi info <ekspansja>Wyświetla informacje o ekspansji: wersję, autora i placeholdery, które wnosi.
/papi ecloud list allPokazuje ekspansje dostępne do pobrania z eCloud.

Typowy cykl pracy wygląda więc tak: /papi ecloud download <ekspansja>, potem /papi reload, na końcu /papi parse me %placeholder% dla pewności, że wartość się zwraca. Komenda /papi parse przyjmuje też nick zamiast me, jeśli chcesz sprawdzić placeholder w kontekście konkretnego gracza.

Przykłady popularnych placeholderów

Składnia zawsze jest ta sama: %ekspansja_nazwa%. Kilka placeholderów, które spotkasz najczęściej:

Zanim wpiszesz taki placeholder do ustawień innego pluginu, przepuść go przez /papi parse me. Jeśli w odpowiedzi dostaniesz z powrotem dosłowny %luckperms_prefix% zamiast wartości, to znak, że brakuje ekspansji albo samego pluginu źródłowego. Lepiej wyłapać to od razu niż szukać potem winy w pluginie, który placeholder miał wyświetlić.

Jak użyć placeholderów w innym pluginie (tab, scoreboard)

Tu PlaceholderAPI pokazuje, po co istnieje. Pluginy, które wspierają PAPI (na przykład popularne pluginy do listy graczy tab czy do scoreboardów), pozwalają wstawiać placeholdery wprost w swoich plikach konfiguracyjnych. Schemat jest zawsze taki sam:

  1. Upewnij się, że PAPI i potrzebna ekspansja są na miejscu. Jeśli w scoreboardzie chcesz pokazać prefiks z LuckPerms, najpierw musi działać LuckPerms, ekspansja LuckPerms musi być pobrana z eCloud, a /papi parse me %luckperms_prefix% musi zwracać sensowną wartość.
  2. Wstaw placeholder do konfiguracji pluginu wyświetlającego. W pliku ustawień pluginu tab czy scoreboard po prostu wpisujesz %player_name% albo %server_online% tam, gdzie ma się pojawić wartość. Plugin sam, w momencie wyświetlania, poprosi PlaceholderAPI o podmianę.
  3. Przeładuj plugin wyświetlający. Po edycji jego konfiguracji użyj jego własnej komendy przeładowania (zwykle coś w stylu /<plugin> reload). Po stronie PAPI nic nie musisz robić, chyba że dokładałeś nową ekspansję, wtedy najpierw /papi reload.

Przykładowo, linia w scoreboardzie typu [%luckperms_prefix%] %player_name% wyświetli graczowi jego rangę i nick. Plugin scoreboardu nie wie nic o LuckPerms, całą robotę odwala PlaceholderAPI, dlatego dokładnie te same placeholdery zadziałają tak samo w tab, czacie czy hologramach. Ucz się raz składni placeholderów, a używasz jej wszędzie.

Typowe problemy

Najczęstsze pytania

Dlaczego po instalacji PlaceholderAPI nic się nie zmieniło?

Bo PAPI sam nie wyświetla niczego, to biblioteka dostarczająca placeholdery innym pluginom. Wartości pokazuje dopiero plugin tab, scoreboard albo czat, który tych placeholderów używa. Bez takiego pluginu sama instalacja PAPI jest niewidoczna dla graczy.

Czym jest ekspansja (expansion)?

To dodatek wnoszący nowy zestaw placeholderów dla konkretnego tematu (Player, Server, Vault, LuckPerms). Większość ekspansji pobierasz z eCloud komendą /papi ecloud download <nazwa>, a po /papi reload ich placeholdery są dostępne.

Jak sprawdzić, czy placeholder działa?

Komendą /papi parse me %placeholder%, na przykład /papi parse me %player_name%. Jeśli dostajesz z powrotem dosłowny tekst zamiast wartości, brakuje ekspansji albo placeholder jest źle wpisany.

Czym różni się %player_name% od placeholderów Vault albo LuckPerms?

%player_name% z ekspansji Player działa od razu. Placeholdery ekonomii (Vault) czy prefiksu (%luckperms_prefix%) wymagają, by na serwerze działał odpowiedni plugin źródłowy i by pobrać dla niego ekspansję z eCloud.

Czy po pobraniu ekspansji trzeba restartować serwer?

Zwykle nie, wystarczy /papi reload. Restart całego serwera bywa potrzebny, gdy dokładasz lub aktualizujesz sam plugin źródłowy (na przykład wgrywasz LuckPerms do folderu plugins).

Powiązane