> For the complete documentation index, see [llms.txt](https://docs.xandtech.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xandtech.fr/home/xtimerewards/features/leaderboards.md). # Leaderboards & Leaderboard Rewards ## Viewing leaderboards * `/xtimerewards top [period] [page]` — playtime leaderboard for `daily`/`weekly`/`monthly`/`yearly`/`total` (defaults to `total`). * `/xtimerewards streaktop [page]` — current-streak leaderboard. * `/afk top [page]` — AFK-mode lifetime-seconds leaderboard. Each is backed by a [customizable menu](/home/xtimerewards/features/menus.md) when `playtime-menu.enabled` is on, otherwise printed as plain chat text. ## Automatic leaderboard rewards (`leaderboard-rewards.yml`) Automatically distributes rewards to the top players on a configured leaderboard the moment its period rolls over — e.g. a `weekly` entry fires right as a new ISO week begins, rewarding whoever was ranked on the week that just ended. No admin action needed. ```yaml leaderboards: - category: playtime period: weekly broadcast: header: "🏆 Weekly Playtime — Top players:" line: "#{rank} {player} played {value} this week" ranks: - rank: 1 display-name: "👑 #1 This Week" rewards: - type: economy value: "1000" - type: message value: "🏆 You finished #1 on this week's playtime leaderboard! +$1000" - rank: "2-3" display-name: "Top 3 This Week" rewards: - type: economy value: "300" - category: streak period: weekly ranks: - rank: 1 display-name: "❄ #1 Streak This Week" rewards: - type: economy value: "500" ``` | Field | Meaning | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `category` | `playtime` (the `/xtimerewards top` leaderboard) or `streak` (`/xtimerewards streaktop`). Only a `weekly`/`monthly` period makes sense for `streak`, since a streak isn't a per-day counter that resets. | | `period` | Which boundary triggers distribution: `daily`/`weekly`/`monthly`/`yearly`. | | `ranks` | A list of tiers. `rank` is a single place (`1`) or an inclusive range (`"2-3"`, same reward for every rank in it). `display-name` feeds the `{tier}` placeholder in the reward-granted chat message. | | `rewards` | Same [reward-entry format](/home/xtimerewards/features/playtime-and-milestones.md#reward-types) as milestones. | | `broadcast` | Optional per-entry override of the server-wide announcement (see below) — omit either line, or the whole block, to fall back to the shared lang-file template. | A player who wasn't online at distribution time gets their reward **queued** and granted automatically the next time they log in — nobody misses out for being offline. {% hint style="info" %} Distribution is exactly-once and cross-server safe: if two servers share the same MySQL database and both notice the rollover, only one of them actually pays it out. Server restart doubles as catch-up — the very first check after start picks up any rollover that happened while offline, with no separate "was it down during the boundary" logic needed. {% endhint %} ## Config (`config.yml`) ```yaml leaderboard-rewards: enabled: true check-interval-seconds: 60 broadcast: enabled: true top-count: 5 ``` `check-interval-seconds` only affects how soon after a rollover the payout happens — never whether it happens, and never a duplicate. `broadcast` is a server-wide announcement of the top-`top-count` ranking whenever a leaderboard's period rolls over, independent of whether a tier's rewards are actually configured for those ranks (it always shows the true top-N). Uses `leaderboard.broadcast-header`/`broadcast-line` in the [language files](/home/xtimerewards/getting-started/getting-started.md#language) by default, or the per-entry `broadcast:` override above. ## Admin management The per-player [admin GUI](/home/xtimerewards/features/admin-tools.md) and reward-history log both reflect leaderboard-reward grants like any other reward. There's no dedicated command to force a distribution — it's driven entirely by the period boundary. ## Placeholders & Discord `%xtimerewards_top_playtime___%` and `%xtimerewards_top_streak__%` (fields: `name`/`value`/`value_formatted`) resolve an arbitrary leaderboard rank **without needing a viewing player** — usable on a sign or hologram, unlike `%xtimerewards_rank_%` which is always the requesting player's own rank. See [PlaceholderAPI](/home/xtimerewards/reference/placeholderapi.md). Every distribution can also post a Discord embed listing the top ranks — see [Discord Integration](/home/xtimerewards/features/discord.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xandtech.fr/home/xtimerewards/features/leaderboards.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.