Reference

Placeholders

Every %imperiummc_*% PlaceholderAPI variable — for chat formats, scoreboards, TAB lists, and Discord bots.

Imperium ships a PlaceholderAPI expansion registered under the imperiummc identifier — every variable on this page is written as %imperiummc_<name>%. Drop them straight into any plugin that consumes PlaceholderAPI: chat formatters (DeluxeChat, LPC, ChatControl), scoreboards (ScoreboardRE, FastAsyncBoard), TAB list (TAB, NametagEdit), holograms (DecentHolograms, FancyHolograms), Discord bridges, and the website's stats widgets.

All placeholders are read-only and cached for 2 seconds per player, so spamming them on a fast-refresh scoreboard costs effectively nothing. Currency values are formatted in K/M/B/T shorthand; raw numeric values are available via the Vault bridge.

How PlaceholderAPI Resolves Imperium Variables

Two expansion classes share the imperiummc namespace so server owners see a single consistent prefix:

ImperiumMCExpansion handles player, rank, prestige, currency, vault, legion, boost, and stat placeholders. Every supported identifier is whitelisted server-side and resolved through the live rank, currency, and legion managers.
CratePlaceholderHook owns the crate_* family. It surfaces per-player key counts, server-wide open totals, and the last rare-reward winner tracked by CrateService. It never mutates crate state.

Each placeholder is computed on a worker thread with a 250 ms timeout and an empty string fallback, so a slow data source can never block the main thread. The placeholder resolves to "" (blank) if the player is offline, the identifier is unknown, or a backing service is disabled.

Placeholders by Category

Every supported placeholder is listed below. Where a placeholder has an alias, both are shown. Dynamic placeholders (those that take a parameter such as a currency key, legion name, or leaderboard position) are listed last in each table.

Player

Placeholder	What it returns
`%imperiummc_player_name%`	The player's display name.
`%imperiummc_player_online%`	Whether the player is currently online (true/false).

Server & Modules

Placeholder	What it returns
`%imperiummc_server_name%`	Server display name from server.properties.
`%imperiummc_online_players%`	Count of players currently online.
`%imperiummc_max_players%`	Server player cap.
`%imperiummc_server_uptime%`	Server uptime in seconds (raw number).
`%imperiummc_formatted_server_uptime%`	Server uptime as e.g. "2d 5h 13m".
`%imperiummc_tps%`	Current server TPS (truncated to 20.0 max).
`%imperiummc_module_enabled_ranks%`	true if the rank module is loaded.
`%imperiummc_module_enabled_currency%`	true if the currency module is loaded.
`%imperiummc_module_enabled_legions%`	true if the legion module is loaded.

Rank

Placeholder	What it returns
`%imperiummc_rank%`	Current rank name (alias of current_rank).
`%imperiummc_current_rank%`	Current rank name.
`%imperiummc_rank_next%`	Next rank name (alias of next_rank).
`%imperiummc_next_rank%`	Next rank name.
`%imperiummc_rank_cost%`	Denarius cost to rank up, formatted (e.g. 12.5K).
`%imperiummc_rank_progress%`	Progress toward next rank, 0–100 (one decimal).
`%imperiummc_rank_bar%`	A 20-cell ASCII progress bar coloured with §a/§7/§8.
`%imperiummc_rank_max%`	true if the player has hit the max rank (2500).
`%imperiummc_max_rank%`	The hard rank cap, always "2500".
`%imperiummc_can_rank_up%`	true if the player can afford the next rank-up.
`%imperiummc_ranks_per_prestige%`	Ranks per prestige level, always "100".
`%imperiummc_required_prestige%`	Prestige level required for the current rank.
`%imperiummc_rank_boost%`	Current per-rank currency boost, e.g. "12%".
`%imperiummc_currency_boost%`	Combined rank + prestige currency boost, as a percent.
`%imperiummc_total_currency_boost%`	Total currency boost (alias of currency_boost).
`%imperiummc_rank_system_enabled%`	true if the rank system is enabled.

Prestige

Placeholder	What it returns
`%imperiummc_prestige_level%`	Current prestige level (0–25).
`%imperiummc_prestige_progress%`	Progress through current prestige cycle (0–100).
`%imperiummc_prestige_cost%`	Cost to prestige next level, formatted Denarius.
`%imperiummc_prestige_next_level%`	The next prestige level number.
`%imperiummc_prestige_total_cost%`	Total prestige cost (cost × 1.5), formatted.
`%imperiummc_can_prestige%`	true if the player can prestige right now.
`%imperiummc_max_prestige%`	The prestige cap, always "25".
`%imperiummc_prestige_boost%`	Per-prestige boost (level × 5%) as a percent.
`%imperiummc_total_prestige_boost%`	Total prestige boost (alias of prestige_boost).

Currency

Placeholder	What it returns
`%imperiummc_currency_money%`	Denarius balance, formatted (e.g. 1.2M).
`%imperiummc_currency_tokens%`	Auctoritas balance, formatted.
`%imperiummc_currency_beacons%`	Civitas balance, formatted.
`%imperiummc_currency_gc%`	Aureus balance, formatted.
`%imperiummc_currency_formatted_money%`	Denarius with §a colour and $ symbol.
`%imperiummc_currency_formatted_tokens%`	Auctoritas with §e colour and ⛁ symbol.
`%imperiummc_currency_formatted_beacons%`	Civitas with §b colour and ⌖ symbol.
`%imperiummc_currency_formatted_gc%`	Aureus with §d colour and 🪙 symbol.
`%imperiummc_currency_display_name_money%`	"Denarius" — friendly name for money.
`%imperiummc_currency_display_name_tokens%`	"Auctoritas" — friendly name for tokens.
`%imperiummc_currency_display_name_beacons%`	"Civitas" — friendly name for beacons.
`%imperiummc_currency_display_name_gc%`	"Aureus" — friendly name for gc.
`%imperiummc_currency_symbol_money%`	"$" — Denarius symbol.
`%imperiummc_currency_symbol_tokens%`	"⛁" — Auctoritas symbol.
`%imperiummc_currency_symbol_beacons%`	"⌖" — Civitas symbol.
`%imperiummc_currency_symbol_gc%`	"🪙" — Aureus symbol.
`%imperiummc_currency_enabled_list%`	A pre-coloured list of enabled currencies.
`%imperiummc_currency_total_count%`	Number of currencies, always "4".
`%imperiummc_currency_system_enabled%`	true if the currency system is enabled.
`%imperiummc_currency_balance_<key>%`	Dynamic: balance of any currency key (money/tokens/beacons/gc).
`%imperiummc_currency_formatted_<key>%`	Dynamic: formatted balance of any currency.
`%imperiummc_currency_display_name_<key>%`	Dynamic: friendly name of any currency.
`%imperiummc_currency_symbol_<key>%`	Dynamic: symbol of any currency.

Vault Economy Bridge

Placeholder	What it returns
`%imperiummc_vault_enabled%`	true if the Vault economy bridge is wired up.
`%imperiummc_vault_eco_balance%`	Vault-economy balance, formatted.
`%imperiummc_vault_eco_balance_formatted%`	Vault-economy balance with §a and $.

Legion

Placeholder	What it returns
`%imperiummc_legion_name%`	Player's legion name, or "None" (alias: legion).
`%imperiummc_legion%`	Alias for legion_name.
`%imperiummc_legion_leader%`	Leader's name (alias: legion_leader_name).
`%imperiummc_legion_leader_name%`	Leader's name.
`%imperiummc_legion_members%`	Current member count.
`%imperiummc_legion_max_members%`	Member slot cap.
`%imperiummc_legion_member_slots%`	Members/slots, e.g. "7/10".
`%imperiummc_legion_online_members%`	Currently-online members.
`%imperiummc_legion_value%`	Composite value score (level × 1000 + beacons).
`%imperiummc_legion_level%`	Legion level (1–10).
`%imperiummc_legion_points%`	Legion points (beacons / 1000).
`%imperiummc_legion_rank%`	Server-wide legion rank by beacons (alias: legion_beacons_rank).
`%imperiummc_legion_beacons_rank%`	Server-wide legion rank by beacons.
`%imperiummc_legion_level_progress%`	Level progress, 0–100.
`%imperiummc_legion_level_cost%`	Cost in Civitas to level up, formatted.
`%imperiummc_legion_beacons_total%`	Total Civitas beacons held, formatted.
`%imperiummc_legion_beacons_formatted%`	Beacons with ⌖ symbol.
`%imperiummc_legion_beacon_multiplier%`	Beacon boost multiplier (level + upgrades).
`%imperiummc_legion_bank%`	Legion bank (currently "0").
`%imperiummc_legion_bank_currency%`	Legion bank currency, always "beacons".
`%imperiummc_legion_vault_level%`	Vault upgrade level (currently "1").
`%imperiummc_legion_vault_size%`	Total vault slots (pages × 54).
`%imperiummc_legion_vault_upgrade_cost%`	Cost to add a vault page, formatted.
`%imperiummc_legion_slot_level%`	Current member-slot cap.
`%imperiummc_legion_slot_upgrade_cost%`	Cost to add member slots, formatted.
`%imperiummc_legion_created%`	Legion creation date.
`%imperiummc_legion_upgrades_count%`	Total purchased upgrades.
`%imperiummc_legion_top_<pos>_<field>%`	Dynamic: field for the top-N legion. Fields: name, beacons, level, members, leader. Pos 1–10.
`%imperiummc_legion_beacons_<name>%`	Dynamic: beacon total for a legion by name.

Legion Role & Permissions

Placeholder	What it returns
`%imperiummc_player_legion_rank%`	Player's legion role (alias: player_legion_role).
`%imperiummc_player_legion_role%`	Alias for player_legion_rank.
`%imperiummc_player_legion_leader%`	true if this player is the legion leader.
`%imperiummc_player_legion_can_invite%`	true if the player's role can invite (Centurion+).
`%imperiummc_player_legion_can_kick%`	true if the player's role can kick (Tribunus+).
`%imperiummc_player_legion_can_upgrade%`	true if the player's role can upgrade (Tribunus+).
`%imperiummc_player_in_legion%`	true if the player is in any legion.

Personal Boosts

Placeholder	What it returns
`%imperiummc_player_boost_beacons%`	Player's Civitas-beacon boost, as a signed percent.
`%imperiummc_player_boost_money%`	Player's Denarius boost, signed percent.
`%imperiummc_player_boost_tokens%`	Player's Auctoritas boost, signed percent.
`%imperiummc_player_boost_exp%`	Player's XP boost, signed percent.
`%imperiummc_player_total_boost%`	Average of all four boost categories.

Lifetime Stats

Placeholder	What it returns
`%imperiummc_stats_total_rank_ups%`	Lifetime rank-ups the player has earned.
`%imperiummc_stats_total_prestiges%`	Lifetime prestiges (alias of prestige_level).
`%imperiummc_stats_total_legion_beacons%`	Legion beacons contributed, formatted.

Crates

Placeholder	What it returns
`%imperiummc_crate_keys_<type>%`	Virtual key count for a given crate type (e.g. keys_vote).
`%imperiummc_crate_keys_total%`	Total virtual keys across all crate types.
`%imperiummc_crate_last_winner%`	Name of the last player to win a rare reward.
`%imperiummc_crate_last_reward%`	Display name of the last rare reward won.
`%imperiummc_crate_total_opens%`	Total crate openings server-wide.
`%imperiummc_crate_player_opens%`	This player's total crate openings.

Using Placeholders in Chat — DeluxeChat

DeluxeChat is one of the most popular chat formatters and a perfect fit for Imperium. The example below layers the player's Imperium rank prefix over a clean Roman style:

# DeluxeChat config.yml — Roman chat format
deluxechat:
  formats:
    default:
      priority: 2147483647
      # %imperiummc_rank%      -> "Proletarius"
      # %imperiummc_currency_money% -> "12.5K"
      prefix: '&8[&6%imperiummc_rank%&8] &7%player_displayname% '
      name_color: '&f'
      suffix: ' &8» &f%message%'
      # Per-tier override using a donor prefix placeholder from LuckPerms:
      # prefix: '&8[%luckperms_prefix%&8] &7%player_displayname%'

Prefer to surface the player's donor tier prefix instead? Use the %luckperms_prefix% placeholder — see the LuckPerms snippet at the bottom of this page.

Using Placeholders in TAB

The TAB plugin can show a per-player header/footer and a below-name tag. Imperium placeholders drop in cleanly:

# TAB config.yml — tab list with rank, prestige and Denarius
tablist:
  enabled: true
  # Header shows server-wide stats, footer shows your progression
  header:
    - "&6ImperiumMC &7- &f%imperiummc_server_name%"
    - "&7Online: &e%imperiummc_online_players%&8/&e%imperiummc_max_players%  &7TPS: &a%imperiummc_tps%"
  footer:
    - "&7Rank: &6%imperiummc_rank% &8(&e%imperiummc_rank_next%&8)"
    - "&7Prestige: &d%imperiummc_prestige_level%&8/&d25  &7Denarius: &a%imperiummc_currency_money%"
    - "&8%imperiummc_rank_bar%&8"

The %imperiummc_rank_bar% placeholder returns a pre-coloured 20-cell ASCII bar — perfect for the footer. You can also stack %imperiummc_prestige_level%next to %imperiummc_rank% to show progression at a glance.

Using Placeholders in a Sidebar Scoreboard

Any FastAsyncBoard/ScoreboardRE-style plugin lets you bind a sidebar with text lines. Here is a complete Roman-themed layout using only Imperium placeholders:

# Any scoreboard plugin — a sidebar using Imperium placeholders
# Example lines for your scoreboard config:
title: "&6&lIMPERIUM"
lines:
  - "&7Rank: &f%imperiummc_rank%"
  - "&7Next: &e%imperiummc_rank_next% &8(&a%imperiummc_rank_progress%&8%)"
  - "&7Denarius: &a$%imperiummc_currency_money%"
  - "&7Auctoritas: &e⛁%imperiummc_currency_tokens%"
  - "&7Civitas: &b⌖%imperiummc_currency_beacons%"
  - "&7Aureus: &d🪙%imperiummc_currency_gc%"
  - "&7Prestige: &d%imperiummc_prestige_level%"
  - "&7Legion: &3%imperiummc_legion_name%"
  - "&8%imperiummc_rank_bar%"

The currency placeholders auto-format into K/M/B/T shorthand, so a balance of 1,250,000 renders as 1.25M. The formatted_* variants additionally prepend the colour code and currency glyph, which can clash with your scoreboard's own colour palette — use the plain currency_* form when you want full control.

Surfacing Your Donor Prefix via LuckPerms

Imperium ships a full LuckPerms donor group ladder (see the Permissions article). You can give each group a Roman prefix and surface it in chat with %luckperms_prefix%:

# Optional: surface your donor tier prefix from LuckPerms in chat
/lp creategroup donor_peregrinus
/lp group donor_peregrinus meta setprefix "&f[&bPeregrinus&f] "
/lp group donor_peregrinus parent set imperiummc.group.donor.peregrinus
# Then in chat: "%luckperms_prefix% %player_displayname% &8» &f%message%"

Imperium's own donor ranks already inherit these groups automatically — see the donor-ranks article for the full ladder.

Tips & Gotchas

Blank output is normal offline. Most player-scoped placeholders return an empty string when there is no online player. Console and Discord-bot contexts should account for this.
Use the dynamic currency placeholders sparingly. %imperiummc_currency_balance_money% and the dedicated currency_money form return identical values; pick one style per scoreboard for consistency.
Top-N legion lookups cap at 10. The legion_top_<pos>family supports positions 1–10 with fields name, beacons,level, members, and leader. Anything beyond 10 returns an empty string.
Colour codes are pre-baked. The formatted_* currency placeholders already include §a/§e/§b/§d colour codes, so they show correctly even in plain-text contexts. Strip them if you need raw numbers.
The Vault bridge mirrors Denarius. If another plugin reads Vault balances, %imperiummc_vault_eco_balance% returns the same Denarius value through the Vault economy provider — no extra config required.