Placeholders
Every PlaceholderAPI placeholder exposed by TDX Leaderboards, with copy-paste examples for scoreboards, tab, holograms, and chat.
TDX Leaderboards registers a PlaceholderAPI expansion under the
identifier tdxleaderboards the moment PlaceholderAPI is detected.
Every placeholder below uses the prefix %tdxleaderboards_...%.
The expansion ships inside the plugin jar, no /papi ecloud download
step. On boot you should see
[TDXLeaderboards] PlaceholderAPI expansion registered.
in the console.
Leaderboards exposes three groups of placeholders:
- Points, the cross-board points leaderboard (see Points & Rewards).
- Board, one set of placeholders per configured board, keyed
by the board's config ID (e.g.
player-kills,ores-mined). - Reset time, a single placeholder counting down to the next monthly reset.
Points leaderboard
These power the global points ranking that aggregates across every board configured with a reward curve.
| Placeholder | Returns |
|---|---|
%tdxleaderboards_points_total% | Viewing player's total points this cycle. 0 if none. |
%tdxleaderboards_points_rank% | Viewing player's rank on the points leaderboard. N/A if unranked. |
%tdxleaderboards_points_name_<N>% | Player name at position N (1-indexed). N/A if no such position. |
%tdxleaderboards_points_value_<N>% | Points at position N, formatted with thousand separators (1,234). 0 if unavailable. |
%tdxleaderboards_points_uuid_<N>% | UUID at position N. Useful for head display plugins. |
Example, chat tag for top 3 point-earners
format: |
&8[&6⭐ &f#%tdxleaderboards_points_rank%&8] &f%player_name%&7: &f{message}Example, leaderboard hologram (DecentHolograms)
location: world,0.5,80.0,0.5
lines:
- "&6&l✦ POINTS LEADERBOARD ✦"
- ""
- "&e#1 &f%tdxleaderboards_points_name_1% &7- &a%tdxleaderboards_points_value_1%"
- "&7#2 &f%tdxleaderboards_points_name_2% &7- &a%tdxleaderboards_points_value_2%"
- "&c#3 &f%tdxleaderboards_points_name_3% &7- &a%tdxleaderboards_points_value_3%"
- ""
- "&7Resets in &f%tdxleaderboards_reset_time%"Per-board leaderboard
Every board you configure in boards.yml automatically gets its own
set of placeholders. Replace BOARDID with the board's config key -
lowercase, hyphen-separated, exactly as it appears in boards.yml
(for example player-kills, ores-mined, vault-balance).
Board-ID resolution is longest-match-first, so a placeholder like
%tdxleaderboards_board_ores-mined_name_1% won't collide with a
board named ores. You can use multi-word board IDs safely.
Top-N rows
| Placeholder | Returns |
|---|---|
%tdxleaderboards_board_BOARDID_name_<N>% | Player name at position N on this board |
%tdxleaderboards_board_BOARDID_value_<N>% | Formatted value with the board's unit label (e.g. 1,234 kills) |
%tdxleaderboards_board_BOARDID_score_<N>% | Raw numeric value at position N, formatted with commas (1,234) |
%tdxleaderboards_board_BOARDID_uuid_<N>% | UUID at position N (for head skins in GUIs / holograms) |
The difference between value and score: value includes the board's
display label (e.g. 1,234 kills) for use in human-readable output,
score is the bare number (1,234) for use inside progress bars,
math, or comparison placeholders.
Viewing-player fields
| Placeholder | Returns |
|---|---|
%tdxleaderboards_board_BOARDID_position% | Viewing player's rank on this board. N/A if unranked. |
%tdxleaderboards_board_BOARDID_value% | Viewing player's formatted value (with label) |
%tdxleaderboards_board_BOARDID_score% | Viewing player's raw number |
Example, sidebar scoreboard
title: "&6&lMONTHLY STATS"
lines:
- ""
- "&eKills &7» &f%tdxleaderboards_board_player-kills_value%"
- "&7Rank &7» &f#%tdxleaderboards_board_player-kills_position%"
- ""
- "&aOres &7» &f%tdxleaderboards_board_ores-mined_value%"
- "&7Rank &7» &f#%tdxleaderboards_board_ores-mined_position%"
- ""
- "&dMoney &7» &f$%tdxleaderboards_board_vault-balance_score%"
- ""
- "&7Resets: &f%tdxleaderboards_reset_time%"Example, per-board top-5 hologram
location: world,10.5,80.0,10.5
lines:
- "&c&l⚔ TOP KILLERS ⚔"
- ""
- "&e#1 &f%tdxleaderboards_board_player-kills_name_1% &7- &c%tdxleaderboards_board_player-kills_value_1%"
- "&7#2 &f%tdxleaderboards_board_player-kills_name_2% &7- &c%tdxleaderboards_board_player-kills_value_2%"
- "&c#3 &f%tdxleaderboards_board_player-kills_name_3% &7- &c%tdxleaderboards_board_player-kills_value_3%"
- "&8#4 &f%tdxleaderboards_board_player-kills_name_4% &7- &c%tdxleaderboards_board_player-kills_value_4%"
- "&8#5 &f%tdxleaderboards_board_player-kills_name_5% &7- &c%tdxleaderboards_board_player-kills_value_5%"Reset timer
A single countdown placeholder that respects whatever
reset.schedule / reset.day / reset.hour you've configured in
config.yml (monthly by default).
| Placeholder | Returns |
|---|---|
%tdxleaderboards_reset_time% | Human string like 12d 3h 22m until the next scheduled reset. |
Example, main menu footer
items:
footer:
slot: 49
material: CLOCK
name: "&7Season resets in &f%tdxleaderboards_reset_time%"
lore:
- ""
- "&8All boards reset together."Testing placeholders
Use /papi parse to verify a placeholder resolves correctly before
wiring it into scoreboards / chat / holograms:
> papi parse ToosieDX %tdxleaderboards_points_rank%
3
> papi parse ToosieDX %tdxleaderboards_board_player-kills_name_1%
ToosieDX
> papi parse ToosieDX %tdxleaderboards_reset_time%
12d 3h 22mIf a board placeholder returns its raw text, double-check the board
ID matches the key in boards.yml exactly, including case and
hyphens. A typo like playerkills vs player-kills will silently
fall through to null and PlaceholderAPI prints the raw input.
Cached leaderboards refresh on the interval set by
general.update-interval in config.yml (default 300 seconds). If
a placeholder value looks stale, it's because that refresh hasn't
fired yet, use /lbadmin update to force an immediate rebuild.