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

# Leaderboards

Leaderboards display player statistics and ranking data in configured locations.

## Configuration Files

| File                         | Purpose                      |
| ---------------------------- | ---------------------------- |
| `/gameplay/leaderboards.yml` | Leaderboard displays.        |
| `/gameplay/ranking.yml`      | Ranking tiers and rank data. |

## Leaderboard Entries

Leaderboard configs define:

| Key                                                    | What it controls                                                                                                                                     |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `leaderboard.<id>.location`                            | Hologram location list.                                                                                                                              |
| `leaderboard.<id>.page.<page>.statistic`               | Statistic shown on the page.                                                                                                                         |
| `leaderboard.<id>.page.<page>.mode`                    | `SOLO`, `TEAMS`, or `GLOBAL` (default, all modes combined).                                                                                          |
| `leaderboard.<id>.page.<page>.positions`               | Number of ranked entries on the page.                                                                                                                |
| `leaderboard.<id>.page.<page>.reserve-viewer-position` | Keeps a slot for the viewing player.                                                                                                                 |
| `leaderboard.<id>.page.<page>.placeholder`             | `viewer-symbol`, `player-symbol`, `viewer-name`, `player-name` used by `$<rank>{SYMBOL}` and `$<rank>{NAME}`.                                        |
| `leaderboard.<id>.page.<page>.display`                 | Text lines.                                                                                                                                          |
| `update.data-interval`                                 | Ticks between statistic refreshes.                                                                                                                   |
| `update.display-interval`                              | Ticks between hologram updates.                                                                                                                      |
| `style`                                                | Hologram `scale`, `shadowed`, `see-through`, `billboard` (`FIXED`, `VERTICAL`, `HORIZONTAL`, `CENTER`), and `alignment` (`CENTER`, `LEFT`, `RIGHT`). |
| `sound.click`                                          | Sound played when a player switches pages.                                                                                                           |

Display lines support `{REFRESH_TIME}`, `$<rank>{NAME}`, `$<rank>{VALUE}`, `$<rank>{RANK}`, `$<rank>{SYMBOL}`, `{PLAYER_<rank>}`, and `{VALUE_<rank>}`.

## Rank Placeholders

Rank display can use placeholders from [Placeholders](/arenalegends/integrations/placeholders.md).

| Placeholder                 | Meaning                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `{STATISTIC_RANK_NAME}`     | Rank name.                                                                                          |
| `{STATISTIC_RANK_TIER}`     | Rank tier.                                                                                          |
| `{STATISTIC_RANK_COLOR}`    | Rank color.                                                                                         |
| `{STATISTIC_RANK_SYMBOL}`   | Rank symbol.                                                                                        |
| `{STATISTIC_<MODE>_RANK_*}` | Mode-specific rank data, for example `{STATISTIC_SOLO_RANK_NAME}` or `{STATISTIC_TEAMS_RANK_TIER}`. |

{% hint style="info" %}
Leaderboards depend on persistent player statistics. If `progression.statistics.enabled` is disabled, leaderboard data does not accumulate.
{% endhint %}