PlaceholderAPI - placeholdery na serwerze Minecraft

Co to jest PlaceholderAPI

PlaceholderAPI (w skrócie PAPI) to darmowy, open-source plugin dla serwerów Minecraft opartych na Spigot i Paper. Jego jedynym zadaniem jest bycie pośrednikiem — udostępnia innym pluginom ujednolicony interfejs do wymiany danych przez tzw. placeholdery, czyli specjalne znaczniki otoczone znakami procenta (%placeholder%).

Bez PAPI każdy plugin musiałby implementować własny, niekompatybilny system zmiennych. Dzięki PlaceholderAPI plugin do scoreboardu nie musi wiedzieć nic o Vault, LuckPerms czy statystykach — po prostu pyta PAPI: "jaka jest wartość %vault_eco_balance% dla tego gracza?" i dostaje odpowiedź. To radykalnie upraszcza konfigurację serwera i eliminuje dziesiątki inkompatybilności.

Plugin powstał w 2015 roku i szybko stał się de facto standardem w ekosystemie pluginów serwerowych. Dziś jest jednym z najczęściej pobieranych pluginów na SpigotMC — pobrany ponad 700 000 razy. Obsługuje wersje Minecraft od 1.7 do 1.21.x.

Kod źródłowy dostępny jest na GitHub, a plugin do pobrania na SpigotMC oraz Hangar.

Jak działają placeholdery

Placeholder to ciąg znaków w formacie %identyfikator_zmienna%. Pierwsza część (przed podkreślnikiem) identyfikuje rozszerzenie (expansion), a druga — konkretną wartość do pobrania. Na przykład:

• %player_name% — rozszerzenie player, zmienna name → nazwa gracza
• %vault_eco_balance% — rozszerzenie vault, zmienna eco_balance → saldo ekonomii
• %server_online% — rozszerzenie server, zmienna online → liczba graczy online
• %luckperms_prefix% — rozszerzenie luckperms, zmienna prefix → prefix z rangi

Gdy plugin obsługujący PAPI (np. plugin do scoreboardu) napotka taki znacznik w konfiguracji, wysyła zapytanie do PlaceholderAPI. PAPI przekazuje je do odpowiedniego rozszerzenia, które oblicza wartość i zwraca ją z powrotem. Cały proces trwa poniżej milisekundy i odbywa się w tle, niezauważalnie dla gracza.

Istnieje też specjalna składnia warunkowa: %placeholder_value% == coś ? wynik_tak : wynik_nie% — dostępna w pluginach które implementują logikę warunkową, np. TAB czy FeatherBoard. Dzięki temu można wyświetlać "Online" lub "Offline" w zależności od stanu, zielony lub czerwony kolor w zależności od wartości itp.

Warto odróżnić dwa rodzaje placeholderów:

• Wbudowane (built-in) — dostarczone razem z PAPI, m.in. player i server. Działają od razu bez dodatkowych plików
• Z rozszerzeń (expansions) — osobne pliki .jar pobierane z eCloud lub dostarczane przez inne pluginy. Wymagają instalacji przez /papi ecloud download NazwaExpansion lub umieszczenia w folderze plugins/PlaceholderAPI/expansions/

Instalacja i eCloud

Instalacja podstawowego pluginu jest standardowa — pobierasz plik .jar i wrzucasz do folderu plugins/. Po restarcie PAPI tworzy folder plugins/PlaceholderAPI/ z plikiem konfiguracyjnym i podfolderem expansions/.

Kluczową funkcją PAPI jest eCloud — wbudowane repozytorium rozszerzeń dostępne bezpośrednio przez komendy w grze lub konsolę. Zawiera ponad 200 rozszerzeń dla najpopularniejszych pluginów. Podstawowe operacje eCloud:

# Wyświetl listę dostępnych rozszerzeń
/papi ecloud list all

# Pobierz konkretne rozszerzenie
/papi ecloud download Vault
/papi ecloud download LuckPerms
/papi ecloud download Essentials
/papi ecloud download Player
/papi ecloud download Server

# Odśwież listę z serwera eCloud
/papi ecloud refresh

# Sprawdź zainstalowane rozszerzenia
/papi list

# Aktualizuj wszystkie rozszerzenia
/papi ecloud update all

Po pobraniu rozszerzenia przez eCloud plik .jar trafia automatycznie do folderu plugins/PlaceholderAPI/expansions/. Większość rozszerzeń ładuje się bez restartu serwera — wystarczy użyć /papi reload.

Część pluginów (np. LuckPerms, EssentialsX od wersji 2.20+) dostarcza własne rozszerzenie PAPI wbudowane w swój kod — w takim przypadku nie musisz nic pobierać z eCloud. Rozszerzenie rejestruje się automatycznie gdy oba pluginy są zainstalowane.

Minimalna konfiguracja serwera z pełną obsługą PAPI wygląda tak:

1. Zainstaluj PlaceholderAPI.jar w plugins/
2. Zrestartuj serwer
3. Pobierz potrzebne rozszerzenia przez /papi ecloud download NazwaExpansion
4. Użyj /papi reload lub zrestartuj ponownie
5. Skonfiguruj placeholdery w pluginach które ich potrzebują (scoreboard, chat, tab itp.)

Najważniejsze placeholdery

Poniżej zestawienie najczęściej używanych placeholderów podzielonych według rozszerzenia. Wszystkie wymagają zainstalowania odpowiedniego rozszerzenia z eCloud (lub wbudowanego w plugin).

Rozszerzenie: player (wbudowane)

Rozszerzenie: server (wbudowane)

Rozszerzenie: Vault (eCloud)

Rozszerzenie: Essentials (eCloud lub wbudowane)

Kompatybilne pluginy

PlaceholderAPI integruje się z praktycznie każdym popularnym pluginem serwerowym. Wyróżniamy dwie strony tej integracji: pluginy które dostarczają placeholdery (provider) i te które je konsumują (consumer).

Pluginy dostarczające placeholdery (providers):

• Vault — saldo, ranga, prefix, suffix
• LuckPerms — grupy, prefix, metadane gracza, uprawnienia
• EssentialsX — AFK, nick, mute, fly, vanish, balance
• CMI — dziesiątki placeholderów dla każdej funkcji CMI
• Jobs Reborn — statystyki pracy, poziom, XP, zarobki
• McMMO — poziomy umiejętności, XP, statystyki
• Lands — terytoria, podatki, relacje między graczami
• AuctionHouse — statystyki aukcji gracza
• WorldGuard — flagi regionów, nazwa regionu w którym stoi gracz

Pluginy konsumujące placeholdery (consumers) — wymagają PAPI:

• TAB — plugin do tablisty i nametagów. Jeden z najlepszych konsumentów PAPI, obsługuje warunki i animacje
• FeatherBoard / Animated Scoreboard — dynamiczne paski boczne ze statystykami gracza
• DeluxeChat / Carbon Chat — formatowanie chatu z rankingami i saldami
• HolographicDisplays / DecentHolograms — hologramy nad blokami z dynamicznymi danymi
• CMI Holograms — tablica topksy bogaczy aktualizowana co minutę
• Citizens / NPC pluginy — imiona i teksty NPC z danymi gracza
• ScoreboardStats — lekki scoreboard na podstawie PAPI
• PlaceholderAPI Condition Placeholders (PAPI CP) — rozszerzenie dodające logikę warunkową do każdego placeholdera

Pełna lista kompatybilnych pluginów dostępna jest w oficjalnym wiki na GitHub.

Komendy PAPI

PlaceholderAPI dostarcza zestaw komend administracyjnych. Wszystkie wymagają uprawnienia placeholderapi.admin lub operatora serwera:

Najbardziej przydatna komenda w codziennej pracy to /papi parse ja %placeholder% — pozwala natychmiastowo sprawdzić czy dany placeholder działa i jaką wartość zwraca dla zalogowanego gracza. Przykład:

/papi parse ja %player_name%
/papi parse ja %vault_eco_balance%
/papi parse ja %server_tps%
/papi parse ja %luckperms_prefix%

JavaScript Expansions

Jedną z potężniejszych funkcji PlaceholderAPI jest możliwość tworzenia placeholderów w JavaScript bezpośrednio z pliku konfiguracyjnego — bez pisania kodu w Javie i bez kompilacji. Służy do tego rozszerzenie JavaScript dostępne na eCloud.

/papi ecloud download Javascript
/papi reload

Po zainstalowaniu tworzysz pliki .js w folderze plugins/PlaceholderAPI/javascripts/. Każdy plik to osobny placeholder. Przykłady użytecznych skryptów:

// plik: health_bar.js
// Placeholder: %javascript_health_bar%
// Wyświetla pasek HP z symboli ❤

var health = Math.round(BukkitPlayer.getHealth());
var max = 20;
var bar = "";
for (var i = 0; i < max / 2; i++) {
  bar += (i < health / 2) ? "§c❤" : "§7❤";
}
bar;

// plik: rank_color.js
// Placeholder: %javascript_rank_color%
// Zwraca kolor zależny od rangi

var rank = BukkitPlayer.hasPermission("rank.admin") ? "admin" :
           BukkitPlayer.hasPermission("rank.vip") ? "vip" : "default";
var colors = { "admin": "§c", "vip": "§6", "default": "§7" };
colors[rank];

W skryptach dostępne są obiekty: BukkitPlayer (obiekt gracza Bukkit), PlaceholderAPI (możliwość wywołania innych placeholderów wewnątrz skryptu) oraz wszystkie klasy Java dostępne przez Nashorn/Rhino.

JavaScript Expansions sprawdzają się gdy potrzebujesz logiki warunkowej, formatowania lub obliczeń których nie oferują gotowe rozszerzenia. To idealne rozwiązanie dla adminów którzy chcą dostosować serwer bez tworzenia własnego pluginu.

Tworzenie własnych placeholderów

Jeśli tworzysz własny plugin i chcesz udostępnić jego dane przez PlaceholderAPI, wystarczy zaimplementować prostą integrację. PAPI udostępnia interfejs PlaceholderExpansion który rejestrujesz w swoim pluginie.

Minimalna implementacja w Javie wygląda następująco:

public class MojPlugin extends PlaceholderExpansion {

    @Override
    public String getIdentifier() {
        return "mojplugin"; // %mojplugin_...%
    }

    @Override
    public String getAuthor() {
        return "NazwaAutora";
    }

    @Override
    public String getVersion() {
        return "1.0";
    }

    @Override
    public String onPlaceholderRequest(Player player, String params) {
        if (player == null) return "";
        if (params.equalsIgnoreCase("points")) {
            return String.valueOf(getPoints(player));
        }
        if (params.equalsIgnoreCase("rank")) {
            return getRank(player);
        }
        return null; // nieznany placeholder
    }
}

Po zarejestrowaniu rozszerzenia (w metodzie onEnable pluginu przez new MojPlugin().register()), placeholdery %mojplugin_points% i %mojplugin_rank% stają się dostępne we wszystkich pluginach korzystających z PAPI.

Szczegółowa dokumentacja API dostępna jest w oficjalnym wiki PlaceholderAPI. Jeśli chcesz udostępnić swoje rozszerzenie publicznie, możesz zgłosić je do eCloud przez GitHub.

Więcej o ekosystemie pluginów serwerowych przeczytasz w katalogu: wszystkie pluginy w katalogu wiki.