DGuard
Start for free

PlaceholderAPI: placeholders, expansions and /papi commands

PlaceholderAPI is a free plugin that lets plugins show each other's data: name, ping, balance, rank, TPS — in the tab list, on scoreboards, in chat and on holograms. It ships with no placeholders of its own: they come from eCloud expansions or are built into plugins. Here's the setup, the commands you need, the usual failures and how to keep expansions safe.

The DGuard team6 min read

In short: install PlaceholderAPI, download the expansions you need with /papi ecloud download <expansion>, run /papi reload and test with /papi parse me %player_name%. Then put the placeholder into the settings of a plugin that supports PlaceholderAPI. Expansions are code that runs on your server, so take them only from the eCloud or official pages.

How placeholders work

A placeholder is a tag like %player_name% that a plugin replaces with a value for a specific player. The part before the underscore is the expansion name (player); the rest says what to output (name). PlaceholderAPI's own config spells it out: the plugin provides no placeholders by default — expansions do.

Kind of expansionHow to install
From the eCloud/papi ecloud download <name>, then /papi reload
Built into a pluginNothing to do: it arrives with the plugin (unless its description says otherwise)
A separate jarDownload it from the expansion's page, put it in plugins/PlaceholderAPI/expansions/ and run /papi reload
The placeholder list on the PlaceholderAPI wiki says which kind each expansion is

PlaceholderAPI is free under GPL-3.0 and runs on Paper, Spigot and Folia; Modrinth has builds up to 26.3. It installs like any plugin — see how to install a plugin.

First steps

in game as an operator; from the console, use a player's name instead of me
/papi ecloud download Player
/papi ecloud download Server
/papi reload
/papi parse me %player_name% ping %player_ping%
/papi list
CommandWhat it does
/papi ecloud download <name> [version]Downloads an expansion from the eCloud
/papi reloadReloads the settings; required after a download
/papi parse <player|me> <text>Shows the text with values filled in — the main way to test
/papi listLoaded expansions, including those built into plugins
/papi ecloud list installedExpansions installed from the eCloud; gold ones have an update
/papi ecloud placeholders <name>An eCloud expansion's placeholders (the list can lag behind the docs)
/papi dumpA report on versions and expansions for support
All commands are ops-only by default: permissions placeholderapi.admin and placeholderapi.ecloud.*

Expansions almost everyone needs

ExpansionHow to get itExamples
Player/papi ecloud download Player%player_name%, %player_ping%, %player_world%
Server/papi ecloud download Server%server_online%, %server_tps%, %server_uptime%
Vault/papi ecloud download Vault%vault_eco_balance%, %vault_prefix%, %vault_group%
LuckPerms/papi ecloud download LuckPermsThe list is on the LuckPerms wiki
Statistic/papi ecloud download Statistic%statistic_mob_kills%, %statistic_time_played%
Names and placeholders from the list on the PlaceholderAPI wiki

%vault_eco_balance% only works with Vault and an economy plugin on the server — see economy and Vault. Prefixes and groups are best kept in LuckPerms.

Where placeholders get used

  • Tab list and nametags. TAB reads PlaceholderAPI placeholders in the header, prefixes and scoreboard; on a network with TAB on the proxy, that takes TAB-Bridge on the game servers.
  • Discord. DiscordSRV supports placeholders in messages and alerts and provides its own.
  • Holograms, menus, scoreboards. DecentHolograms, for example, is marked as supporting placeholders in the plugin list on the PlaceholderAPI wiki.
  • Chat — not always. The PlaceholderAPI wiki warns that EssentialsXChat doesn't parse placeholders on its own; it needs an add-on.

Whether a plugin supports PlaceholderAPI, and in which settings, is in its documentation or in the plugin list on the PlaceholderAPI wiki (look for "Supports placeholders").

A placeholder doesn't work

  1. 1

    Is the expansion installed?

    /papi list shows whether it's loaded. eCloud expansions don't appear on their own — download them and run /papi reload.

  2. 2

    Test with parse

    /papi parse me %placeholder%. If the command shows a value but the plugin shows the raw %…%, that plugin (or that setting) doesn't support PlaceholderAPI.

  3. 3

    Check for typos

    Compare the name with the wiki list or the expansion's docs.

  4. 4

    Is the required plugin enabled?

    The Vault expansion needs Vault, the LuckPerms one needs LuckPerms. They should be green in /plugins.

Keeping expansions safe

An expansion is a jar that PlaceholderAPI loads into your server — code with every right the server has. That's why the eCloud has safeguards, and they're worth keeping:

  • The command only downloads verified expansions. Moderators review eCloud uploads; unverified ones have to be downloaded by hand — a good moment to stop and think.
  • Updates lose verification. A new version of a verified expansion is unverified again until a moderator reviews it — that's how the eCloud fights malware distribution.
  • Known-malware check. At startup and on /papi reload, PlaceholderAPI compares the hashes of files in the expansions folder with a list of known malicious expansions and stops the server on a match. Keep detect_malicious_expansions: true in its config.yml.
  • Permissions for admins only. /papi commands are ops-only by default; don't give placeholderapi.* to moderators.

How to spot an infected plugin and what to do if the server is already compromised is in malicious plugins.

Placeholders, TPS and the anticheat

A common setup is %server_tps% in the tab list or on a scoreboard to see when the server dips. When it does, the spark profiler shows what's eating the ticks — see why your server lags. DGuard — the best anticheat for a modern Minecraft server — is built not to take ticks away: its checks run in network threads, and on the main thread it uses 0.03% of one core. /dguard perf (permission dguard.admin) shows how long its checks take on your server.

FAQ

Why do I see %player_name% instead of the value?

Either the Player expansion isn't installed (/papi ecloud download Player, then /papi reload) or the plugin doesn't support PlaceholderAPI. Test it: if /papi parse me %player_name% prints your name, the plugin is the problem.

Where are PlaceholderAPI expansions stored?

In plugins/PlaceholderAPI/expansions/. A manually downloaded jar goes there too, followed by /papi reload.

Is it safe to download expansions?

From the eCloud by command, yes: only moderator-verified expansions download that way, and PlaceholderAPI also checks files against a list of known malware. Don't install jars from unknown sites.

Do I need to restart after installing an expansion?

No, /papi reload is enough. A restart is for installing or updating PlaceholderAPI itself.

Sources

Read next

All sections
Plugins6 min readThe TAB plugin: tab list, prefixes, nametags and scoreboardTAB by NEZNAMY is a free, open-source plugin that handles everything players see in the player list and above heads: the tab list header and footer, prefixes, nametags, the scoreboard and boss bars. It takes groups from LuckPerms, reads PlaceholderAPI placeholders and can run on a proxy — the recommended setup for a network.ReadServer protection7 min readMalicious plugins and backdoors: keeping your server cleanA plugin gets full access not just to the server but to the whole machine it runs on — Paper's docs say so directly. So a backdoored plugin isn't "a few cheats"; it's a stranger with owner rights. Here's where such plugins come from, how to avoid installing one, how to check your server, and what to do if it's already infected.ReadPlugins7 min readMinecraft server economy: Vault, a provider and shopsMoney on a Minecraft server rests on three layers: the Vault bridge (or its fork VaultUnlocked), a plugin that stores balances — EssentialsX, for example — and the plugins that spend and pay out money: shops, jobs, rewards. Here's how to wire them together, where to start with the settings, and what breaks an economy faster than any bug.Read

Run the best anticheat for modern Minecraft

DGuard catches all 47 kinds of cheats in our comparison — the closest rival, Intave, has 27. Full protection on every plan, free up to 30 players online.

Protect your server for freeLook inside the panel