PlaceholderAPI auf Minecraft-Servern: Einrichtung, Expansions, Beispiele

PlaceholderAPI (meist als PAPI abgekürzt) ist ein Bridge-Plugin, über das andere Plugins dynamische Daten austauschen. Ohne PAPI funktioniert die Hälfte der modernen Inhalte in TAB, Scoreboard und Chat schlicht nicht. Wir gehen durch, wie du es installierst, welche Expansions du brauchst und wo es im Server-Alltag landet.

Was PlaceholderAPI ist und wozu

PAPI selbst macht nichts. Es ist ein API-Plugin, das anderen Plugins ein einheitliches Format zum Einsetzen von Daten in Strings bereitstellt. Jedes Plugin, das den Spielernamen, das Guthaben, die LuckPerms-Gruppe oder die aktuellen TPS anzeigen will, schreibt einfach %player_name% oder %vault_eco_balance% in seine Config, und PAPI ersetzt das zur Laufzeit durch den echten Wert.

Der grosse Vorteil: ein Format für alles. Früher hatte das TAB-Plugin eigene Platzhalter, das Scoreboard-Plugin andere, das Chat-Plugin wieder andere. Mit PAPI gibt es eine universelle Syntax, und jedes Plugin, das damit umgehen kann, liest Daten aus jeder Quelle.

In der Praxis läuft PAPI auf rund 90% der Server, vom kleinen SMP bis zum grossen Minigame-Netzwerk. Wer einen Server mit TAB, Scoreboard, Custom-Chat oder Hologrammen betreibt, wird es fast sicher brauchen.

PlaceholderAPI installieren

Die stabile Version gibt es auf Spigot. Die .jar in plugins/ legen, Server neu starten. Fertig.

Beim ersten Start legt PAPI den Ordner plugins/PlaceholderAPI/ mit dem Unterordner expansions/ an. Dort landen die Add-ons, die die eigentlichen Platzhalter liefern. PAPI alleine ist fast nutzlos, also zählt der nächste Schritt mehr als die Installation selbst.

Versionskompatibilität: Paper und Spigot 1.16.5 bis 1.21.x. Für Folia gibt es einen separaten PAPI 2.11+ Fork. Die normale Version startet auf Folia nicht wegen Unterschieden im Scheduler.

Funktionsprinzip: Provider und Consumer

PAPI folgt einem einfachen Modell. Provider (Expansions) sind Plugins oder Module, die Daten liefern. Consumer sind Plugins, die diese Daten in ihre Nachrichten einbauen.

Beispiel: Du schreibst in der Config eines TAB-Plugins:

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

Das TAB-Plugin sieht %server_online%, fragt PAPI, PAPI findet die passende Expansion (hier Server) und gibt die aktuelle Spielerzahl zurück. Das TAB-Plugin muss nicht wissen, wie der Server diese Zahl ermittelt, und das ist genau der Punkt.

Nützliche Befehle

PAPI bringt ein paar Befehle für Debugging und Verwaltung mit:

/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> ist das wichtigste Debug-Werkzeug. Wenn ein Platzhalter im TAB oder Chat wörtlich angezeigt wird (%player_name% statt des Namens), führ diesen Befehl aus. Löst PAPI ihn korrekt auf, liegt das Problem beim Consumer-Plugin. Bekommst du den Roh-Text zurück, ist die Expansion nicht installiert oder du hast einen Tippfehler.

Expansions per ecloud installieren

Früher hat man Expansions manuell von der Website geladen. Heute geht das direkt mit ecloud:

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

Nach jedem Download /papi reload oder Server-Restart. Solange das nicht passiert, liegt die Expansion zwar im Ordner, ist aber inaktiv.

Solides Grundpaket für die meisten Server: Player, Server, Vault (wenn Economy), LuckPerms (wenn als Permissions-Plugin im Einsatz), Statistic (für Spielstatistiken).

Die wichtigsten Expansions

Player - die Basis, fast immer installiert. Liefert %player_name%, %player_displayname%, %player_uuid%, %player_health%, %player_food_level%, %player_world%, %player_ping%, Koordinaten, Gamemode und dutzende weitere Felder.

Server - Server-Info. %server_online%, %server_max_players%, %server_unique_joins%, %server_tps_1%, %server_uptime%, %server_ram_used%. Die TPS-Platzhalter sind Gold für Admin-Scoreboards.

Vault - Economy und Gruppen via Vault API. %vault_eco_balance%, %vault_eco_balance_formatted% (mit Tausendertrennzeichen), %vault_prefix%, %vault_suffix%, %vault_group%. Funktioniert mit jeder Economy, die Vault hooked: EssentialsX, CMI, TheNewEconomy.

LuckPerms - die Wahl, wenn du LuckPerms nutzt (und das tun die meisten). %luckperms_primary_group_name%, %luckperms_prefix%, %luckperms_suffix%, %luckperms_meta_<key>%. Besser als Vault für Prefix/Suffix, weil Farbcodes sauber erhalten bleiben.

Statistic - Spielstatistiken aus der Bukkit API. %statistic_play_one_minute% (Gesamtspielzeit), %statistic_mob_kills%, %statistic_deaths%, %statistic_blocks_broken%. Vorsicht: einige Felder sind teure Lookups, nicht 20 davon pro Spieler ins TAB packen.

Math - Mathe direkt im Platzhalter. %math_0_{%player_health%}/2% gibt die Hälfte der Lebenspunkte zurück. Praktisch für Berechnungen im Scoreboard, ohne ein Skript zu schreiben.

Custom-Platzhalter via JavaScript

Für Sonderfälle gibt es die JavaScript Expansion. Damit baust du eigene Platzhalter in JS, ohne ein separates Plugin zu kompilieren.

Beispiel: du willst einen %js_kdr%, der die K/D-Ratio des Spielers berechnet. Lege plugins/PlaceholderAPI/javascript_placeholders.yml an:

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

Und das Skript 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);
}

Nach /papi reload funktioniert %javascript_kdr% überall. Die Nashorn-JS-Engine wurde in Java 11+ entfernt, also auf modernen Versionen GraalVM JS installieren oder den PlaceholderAPI Javascript Expansion Fork nutzen.

Wo PAPI auf dem Server zum Einsatz kommt

TAB / Tablist (TAB plugin) - der Klassiker. Header, Footer, Spielernamen in der Liste, sogar Scoreboard im selben Plugin, alles über PAPI.

Scoreboard-Plugins - FeatherBoard, AnimatedScoreboard, TAB selbst. Dynamische Boards mit Guthaben, Rang und Spielzeit basieren komplett auf PAPI.

Chat-Plugins - DeluxeChat, EssentialsXChat, VentureChat. Nachrichtenformat und Hover/Click-Events laufen über Platzhalter.

Hologramme - HolographicDisplays, DecentHolograms. Top-Spieler-Leaderboards, Guthaben-Anzeige über dem Bank-Automaten, aktueller Online-Counter.

ItemsAdder, Oraxen, MMOItems - Anzeigename und Lore von Items nutzen PAPI oft für dynamische Werte.

Skript-Skripte - eingebaute Unterstützung über parsed placeholder.

Praxis: TAB- und Chat-Format

TAB-Plugin-Config mit Platzhaltern:

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'

DeluxeChat-Config für den Chat:

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}'

In EssentialsXChat aktivierst du Platzhalter in essentials/config.yml:

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

EssentialsXChat unterstützt PAPI seit EssentialsX 2.19+. Davor brauchte man ein separates EssentialsXChat-PlaceholderAPI-Hook-Plugin.

Performance und Caching

PAPI selbst ist schnell. Probleme entstehen mit teuren Expansions, die bei jedem Platzhalter-Aufruf in die Datenbank gehen. Beispiel: %statistic_play_one_minute% für alle 100 Spieler im TAB alle 2 Sekunden sind 50 SQL-Queries pro Sekunde, und wenn die Statistik in einer DB liegt, ist das spürbar.

Was tun:

• Nicht mehr als 5-10 Platzhalter pro Spieler in eine TAB-Zeile packen. Pro-Spieler-Stats multiplizieren sich mit dem Online-Count.
• Refresh-Intervall im TAB-Plugin erhöhen. Standard ist meist 1 Sekunde, 5-10 reichen für die meisten Platzhalter mit Reserve.
• Relational placeholders nur, wenn nötig. Sie sind teurer, weil sie für Spielerpaare berechnet werden.
• Mit Timings profilieren. /timings paste zeigt CPU-Fresser, dort kann eine bestimmte Expansion auftauchen.

Wenn ein Platzhalter nicht funktioniert

Typische Situationen, in denen %player_name% wörtlich erscheint:

1. PAPI ist nicht installiert oder nicht geladen - in /plugins nachsehen, sollte grün sein.
2. Expansion ist nicht heruntergeladen - /papi list zeigt aktive an. Fehlt deine, dann /papi ecloud download <name>.
3. Das Plugin nutzt PAPI nicht - nicht jedes Plugin liest Platzhalter. Bukkit MOTD aus server.properties parst sie nicht, dafür braucht es ein eigenes MOTD-Plugin mit PAPI-Support.
4. Tippfehler im Namen - %player_health% funktioniert, %player_hp% nicht. /papi list zeigt die exakten Namen.
5. PAPI-Hook im Consumer-Plugin ist optional - manche Configs haben ein placeholderapi: true, das standardmässig aus ist.

/papi parse me <text> ist dein Hauptwerkzeug. Löst es den Platzhalter auf, das Consumer-Plugin aber nicht, dann hat das Consumer-Plugin seinen PAPI-Hook nicht aktiviert.

FAQ

Was ist besser, PlaceholderAPI oder MVdWPlaceholderAPI

PAPI ist heute der Industriestandard. MVdWPlaceholderAPI war auf 1.8 und 1.12 verbreitet, der Autor pflegt es aber seit Jahren nicht mehr. Die meisten modernen Plugins kommen über das Bridge-Plugin MVdWPlaceholderAPI Hook mit beiden klar, aber wer einen Server frisch aufsetzt, nimmt einfach PAPI.

Wie schreibt man eine eigene Expansion

Java-Plugin oder Standalone-.jar im expansions/-Ordner. Klasse erbt von PlaceholderExpansion, du überschreibst onPlaceholderRequest(Player p, String identifier) und gibst den gewünschten Wert zurück. In getIdentifier() legst du das Prefix fest (z.B. myplugin für %myplugin_xxx%). Das PAPI GitHub Wiki hat funktionierende Beispiele.

Kann man PAPI im Item-Namen nutzen

Nur wenn das Plugin, das das Item rendert, Platzhalter unterstützt. Bukkit-ItemStack parst sie nicht. ItemsAdder, Oraxen, MMOItems und DeluxeMenus können das. Für eigene GUIs nimmt man üblicherweise DeluxeMenus als Frontend.

Warum gibt %vault_eco_balance% 0 zurück

Drei Gründe. Erstens: Vault ist nicht installiert oder findet keinen Economy-Provider (du brauchst EssentialsX, CMI oder ein anderes Plugin mit Vault-Hook). Zweitens: der Spieler hat noch kein Economy-Konto (Essentials legt eins beim ersten Join nach Installation an). Drittens: du nutzt %vault_eco_balance_formatted% und der Wert ist einfach klein genug, um auf 0 gerundet zu werden.

Belasten viele Platzhalter im TAB den Server stark

Hängt davon ab, welche. Player- und Server-Platzhalter sind günstig, sie lesen aus dem Speicher. Statistic, LuckPerms-Meta und SQL-gestützte Custom-Platzhalter sind teurer. In der Praxis fallen 5-10 Platzhalter pro Spieler im TAB mit 5-Sekunden-Intervall selbst bei 200 Online nicht ins Gewicht. Probleme entstehen ab 50+ Platzhaltern, die jede Sekunde aktualisiert werden.

Was sind relational placeholders

Platzhalter der Form %rel_<expansion>_<id>%, die für ein Spielerpaar (viewer und target) berechnet werden. Werden vor allem im TAB benutzt, um Namen je nach Verhältnis einzufärben (Gegner rot, Verbündeter grün). Teurer als normale Platzhalter, weil sie N×M statt N mal laufen.

Was als nächstes

Installier das Grundpaket - Player, Server, Vault, LuckPerms - und führ /papi list aus, um zu sehen, was zur Verfügung steht. Dann ein TAB-Plugin dazu und ein Scoreboard bauen. Wenn du etwas Eigenes brauchst, deckt die JavaScript Expansion die meisten Fälle ohne separates Plugin.

Wer PAPI auf einem grossen Server intensiv nutzt, sollte wöchentlich /timings paste laufen lassen und prüfen, ob eine Expansion in die Top der CPU-Fresser gerutscht ist. Meist ist es Statistic oder eine selbstgebaute Expansion mit teuren Queries.