> For the complete documentation index, see [llms.txt](https://lethium.gitbook.io/lethium-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lethium.gitbook.io/lethium-docs/gameplay/leaderboards.md).

# Leaderboards

The 60+ leaderboards, how they refresh, seasonal boards, payouts and placeholders.

File: `plugins/ClickEmCore/modules/leaderboards.yml`. Module id: `leaderboards`. Commands: `/leaderboards`, `/lb`, `/leaderboard`.

`/leaderboards` opens a **board picker**, then the top players of the chosen board.

### The boards

| Group               | Boards                                                                                                                                                                                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Lifetime counters   | `KILLS`, `CURRENCY_EARNED`, `REBIRTHS`                                                                                                                                                                                                                                                                                                           |
| Stats (live values) | One per stat: `STAT_DAMAGE`, `STAT_CURRENCY`, `STAT_CRIT_CHANCE`, `STAT_CRIT_DAMAGE`, `STAT_ESSENCE`, `STAT_LUCK`, `STAT_BOSS_DAMAGE` and so on, including the flat ones (`STAT_POWER_FLAT` ...).                                                                                                                                                |
| Vanilla statistics  | `PLAYTIME_HOURS`, `DEATHS`, `MOB_KILLS`, `PLAYER_KILLS`, `DAMAGE_DEALT`, `DAMAGE_TAKEN`, `BLOCKS_WALKED`, `JUMPS`, `FISH_CAUGHT`, `ANIMALS_BRED`                                                                                                                                                                                                 |
| From other modules  | `PETS_OWNED`, `HIGHEST_PET_LEVEL`, `PET_PRESTIGE_TOTAL`, `ARTIFACT_LEVELS`, `ARTIFACT_ESSENCE`, `SKILL_LEVELS`, `UPGRADE_LEVELS`, `MASTERY_LEVELS`, `ABILITY_LEVELS`, `ACHIEVEMENTS_UNLOCKED`, `ECHOES_OWNED`, `COSMETICS_OWNED`, `COINS_BALANCE`, `SEASON_LEVEL`, `DAILY_STREAK`, `KILLSTREAK`, `CLAN_LEVEL`, `PROFILE_LEVEL`, `CHAT_GAME_WINS` |
| Meta                | `TOP_PLACEMENTS` ("Top of the Top"): how many other boards you are top 3 on                                                                                                                                                                                                                                                                      |

A board from a disabled module shows 0 for everyone.

### How boards update

| Key                                   | Default | Meaning                                                                    |
| ------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `top-size`                            | 10      | Entries shown in the menu and in placeholders.                             |
| `snapshot-interval-seconds`           | 30      | How often stat and module boards re-check every **online** player.         |
| `gui.refresh-cooldown-seconds`        | 15      | Cooldown of the **Refresh Now** button, per player. `0` = none.            |
| `offline-cache.save-interval-seconds` | 300     | How often `leaderboards-cache.yml` is rewritten. Also written on shutdown. |
| `offline-cache.keep-per-board`        | 200     | Top entries saved per board.                                               |

Rankings are saved to `plugins/ClickEmCore/leaderboards-cache.yml` so **offline players stay on the boards** across restarts at their last known value, replaced with a live value when they log in. A player never seen since install is not ranked.

### Seasonal boards

`seasonal.enabled: true` also tracks `KILLS`, `CURRENCY_EARNED` and `REBIRTHS` **per season** (see [Season Pass](/lethium-docs/gameplay/season-pass.md)) and shows a toggle button. Stat boards stay lifetime-only. The seasonal half is discarded when the season changes.

### Display overrides

```yaml
display:
  stat_damage:
    name: "<red>Damage Kings</red>"
    lore: ["<gray>Top raw damage on the server</gray>"]
```

Keyed by the lower-case board name. `lore` lines are added after the built-in rank line.

### Payout

```yaml
payout:
  enabled: false
  interval-hours: 168
  board: KILLS
  rewards:
    1: 10000
    2: 5000
    3: 2500
```

Automatically pays Coins to the top N on one board on a schedule. Only **online** players are paid. Coin amounts here are **flat** (not scaled).

### Using boards in other plugins

PlaceholderAPI: `%clickem_leaderboard_<board>_<rank>_name%` and `_value%`, for example `%clickem_leaderboard_kills_1_name%`. Also `%clickem_leaderboard_first_count%`, `_second_count%`, `_third_count%`, `_podium_count%`. See [Progress placeholders](/lethium-docs/placeholders/progress.md). Use them on holograms to build a hub leaderboard (see [FancyHolograms](/lethium-docs/server-setup/portals-npcs-holograms.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lethium.gitbook.io/lethium-docs/gameplay/leaderboards.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.