Placeholders
Hit counts that survive restarts, ready for quest and scoreboard plugins through PlaceholderAPI.
The plugin counts how many times each player has hit a piñata. The count carries on across piñatas, across parties and across restarts, so a quest like "hit the piñata 10 times" can be spread over a whole week if you like.
Those counts are read back through PlaceholderAPI, which is the plugin nearly every quest, scoreboard and menu plugin uses to pull numbers out of other plugins.
PlaceholderAPI is optional. Hits are counted either way. Without PlaceholderAPI installed there is simply nowhere to show them yet — install it later and the numbers are already there waiting.
The placeholders
| Placeholder | What it gives you |
|---|---|
%pinataparty_hits% | Every hit the player has ever landed. |
%pinataparty_hits_24h% | Hits in the last 24 hours. |
%pinataparty_hits_current% | Hits on the piñatas that are up right now. |
%pinataparty_progress_10% | Reads 7/10. |
%pinataparty_progress_10_24h% | The same, counting only the last 24 hours. |
%pinataparty_remaining_10% | How many hits are still needed to reach 10. |
%pinataparty_active% | true while a party is running, false otherwise. |
%pinataparty_pinatas% | How many piñatas are up. |
Time windows
Anywhere you see 24h above you can write your own window: a number followed by a letter.
| Letter | Means | Example |
|---|---|---|
s | seconds | %pinataparty_hits_90s% |
m | minutes | %pinataparty_hits_30m% |
h | hours | %pinataparty_hits_24h% |
d | days | %pinataparty_hits_3d% |
w | weeks | %pinataparty_hits_2w% |
A bare number means hours, so %pinataparty_hits_12% is the last twelve hours.
Windows land on the hour. Hits are filed under the hour they happened in, which keeps the stats file small. A window can therefore reach up to an hour further back than you asked for. For a quest counted in hours or days you will never notice; for a window of a few minutes, expect it to behave like an hour.
Progress and remaining
progress is the one to reach for in a quest line. It prints the count, a slash, and your goal, and it stops at the goal.
# 7 hits in, goal of 10
%pinataparty_progress_10% -> 7/10
# 13 hits in, same goal
%pinataparty_progress_10% -> 10/10remaining is the same idea counting down, which suits a "3 to go" style line. It stops at 0.
Both take an optional window on the end, written exactly as above:
%pinataparty_progress_10_24h% # 10 hits, today
%pinataparty_remaining_50_1w% # 50 hits, this weekBoth also accept current in the window slot, which counts only the piñatas that are up at this moment:
%pinataparty_progress_5_current%Settings
stats:
enabled: true
retention-days: 30
save-interval-seconds: 300| Key | What it does | Default |
|---|---|---|
enabled | false stops counting entirely. Existing counts are left alone on disk, and every placeholder reports 0. | true |
retention-days | How far back the recent-hit windows can reach. Older hits are dropped to keep the file small. The lifetime total is never reduced. | 30 |
save-interval-seconds | How often the counts are written to disk, in the background. Minimum 30. | 300 |
Set retention-days a little higher than the longest window you actually use. Asking for 30d on a seven day retention gives you seven days of hits, not thirty.
Where the counts live
A stats.yml appears in the plugin folder. There is nothing in it you need to edit by hand. Deleting it resets everyone to zero, which is the quickest way to start a fresh event.
It is also written when the server shuts down, so a clean stop never loses anything. A crash can lose up to save-interval-seconds worth of hits.