Placeholders
Gavel's PlaceholderAPI expansion — listing counts, mailbox, earnings and grand-auction state for scoreboards and holograms.
Gavel v1.0.0Paper · Folia supported1.21 – 1.21.x
With PlaceholderAPI installed, Gavel registers the gavel expansion automatically. No extra
download, no /papi ecloud step — it comes from the plugin.
Player placeholders
| Placeholder | Returns |
|---|---|
%gavel_listings% | Number of active listings the player currently holds |
%gavel_limit% | The player's listing limit from gavel.limit.<n> or the config default |
%gavel_mail% | Number of unclaimed items in their mailbox |
%gavel_sales% | Completed sales as a seller |
%gavel_purchases% | Completed purchases as a buyer |
%gavel_earned% | Total money earned, formatted with your economy settings |
%gavel_spent% | Total money spent, formatted |
Grand auction placeholders
| Placeholder | Returns |
|---|---|
%gavel_grand_running% | true or false |
%gavel_grand_bid% | Current highest bid, formatted |
%gavel_grand_leader% | Name of the current leader |
Caching
Every value is cached per player for a short interval. Placeholders are evaluated on a scoreboard tick — often several times a second per player — and hitting the database that often would be a performance problem on its own.
The practical consequence: %gavel_listings% may lag a second or two behind an action the player
just took. That is deliberate, and it is the right trade.
Money values respect your formatting
%gavel_earned%, %gavel_spent% and %gavel_grand_bid% come out formatted with
economy.currency-format, the separators and compact-numbers. You do not need to post-process
them.
Examples
A scoreboard line showing usage against the rank limit:
&7Listings: &e%gavel_listings%&7/&e%gavel_limit%A mailbox reminder that only appears when there is something to claim — most scoreboard plugins support a conditional on a placeholder value:
&6You have %gavel_mail% items waiting in /ah mailA hologram over an auction NPC, live during grand auctions:
&e&lGRAND AUCTION&fLeader: &a%gavel_grand_leader%&fBid: &e%gavel_grand_bid%If a placeholder shows as raw text
Three things to check, in order:
- PlaceholderAPI is installed and Gavel started after it. Gavel declares PlaceholderAPI as a
softdepend, so load order is handled — but only if PAPI is actually present at startup. /aha infoconfirms Gavel loaded correctly./papi parse me %gavel_listings%tests the expansion directly, outside whatever plugin is rendering your scoreboard.
If step 3 works and your scoreboard does not, the problem is in the scoreboard plugin's parsing, not in Gavel.