> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://aetherskywarswiki.netlify.app/api/mcp` to find what you need.

# Achievements and leaderboards

What gets counted, what it pays, and where players can see how they rank.

## Stats tracked

Every player has a row of stats, kept in the database and carried across matches.

| Stat | Counted when |
| --- | --- |
| Kills | A player kills another player in a match. |
| Deaths | A player dies in a match. |
| Wins (Solo) | A player wins a Solo match. |
| Wins (Teams) | A player's team wins a Teams match. |
| Ranked wins (Solo and Teams) | The same, on an arena flagged as ranked. |
| Losses | A match ends without the player winning it. |

Ranked and casual are counted separately, so flagging an arena as ranked gives you a second,
cleaner set of numbers. See [Arenas and modes](/features/arenas-and-modes).

### Match history

Each match is also logged per player: the arena, the mode, the result, kills, and the time it
happened. Players see their own history in the profile menu, and staff can open anyone's with
`/asw player <name>`.

The timestamp format is yours to set:

```yaml
Config:
  Time:
    Formatting: dd-MM-yyyy HH:mm:ss
    Offset: 0                            # [1]
```

1. Hours to add or subtract, if the server clock is not in the timezone you want to show.

## Achievements

Achievements are milestones that pay coins once. They are defined in
`plugins/AetherSkyWars/achievements.yml`.

```yaml
Coins:
  Kills:                # [1]
    20: 50              # [2]
    50: 100
    100: 200
  Wins-Solo:
    20: 500
    50: 1000
  Wins-Teams:
    20: 500
  Games-Played:
    20: 500
```

1. The stat being tracked. The four categories are `Kills`, `Wins-Solo`, `Wins-Teams`, and
   `Games-Played`.
2. Reach 20 kills, get 50 coins. Add, remove, or re-price any line.

Players browse their progress in the achievements menu, reached from the profile.

:::note
Payouts happen once, when the milestone is crossed. Adding a new milestone below a
player's current total does not back-pay them.
:::

## Leaderboards

Eight leaderboards are built from the stats above:

| Casual | Ranked |
| --- | --- |
| Solo wins | Solo wins (ranked) |
| Teams wins | Teams wins (ranked) |
| Kills | Kills (ranked) |
| Deaths | Deaths (ranked) |

They are rebuilt on a timer rather than on every kill, so they cost nothing during a match:

```yaml
Config:
  Refresh-Leaderboards: 600
```

That is a refresh every 600 ticks. Run `/asw refreshLeaderboards` to rebuild them immediately.

### Showing them to players

Three ways:

* **A board in your world.** The plugin can put a floating head of whoever is top over a column of
  names and numbers, anywhere you like. This needs no other plugin. See below.
* **PlaceholderAPI.** Every leaderboard exposes positions 1 to 10 as placeholders, so you can
  put them on a scoreboard, a hologram from another plugin, or a menu. See
  [Placeholders](/reference/placeholders).
* **Holograms.** With DecentHolograms installed, the plugin can render leaderboards as floating
  text. See [Signs and holograms](/features/signs-and-holograms).

### Boards you place

<img src="/leaderboard-anatomy.svg" alt="A placed leaderboard: the top player's head above a title line and the ranking entries, anchored to where you stand" />

Stand where you want the bottom line of the board to sit and run:

```
/asw leaderboard create <name> <category> [rows]
```

The board anchors to the bottom of the block your feet are in and builds upward, so placing it
while flying or mid jump lands it in exactly the same spot as standing on the floor.

The name is yours to pick and is how you refer to it later. The category is one of `SOLO_WINS`,
`TEAMS_WINS`, `KILLS`, `DEATHS`, `SOLO_RANKED_WINS`, `TEAMS_RANKED_WINS`, `KILLS_RANKED` or
`DEATHS_RANKED`. Rows is how many places to show, up to ten, and defaults to ten.

| Command | What it does | Permission |
| --- | --- | --- |
| `/asw leaderboard create <name> <category> [rows]` | Places a board where you are standing. | `asw.admin` |
| `/asw leaderboard remove <name>` | Takes one down completely. | `asw.admin` |
| `/asw leaderboard list` | Every board, with its category and coordinates. | `asw.admin` |

The head wears the skin of whoever is top and turns slowly, so a board against a wall is still
readable from the front. Every board is redrawn on the same clock as the leaderboards themselves.

What a board looks like lives in `leaderboard-templates.yml`. The `Default` template is used by
every board, and a section named exactly after a category, such as `SOLO_WINS`, overrides it for
boards of that category. A per-category section only needs the keys it wants to change.

| Key | What it sets |
| --- | --- |
| `Lines` | The board, top to bottom, one entry per line. An empty line `""` leaves a gap. Add, remove and reorder freely. `%category%` is the board's name, and a line holding only `%entries%` becomes the ranking itself. `%player_1%` to `%player_10%` and `%value_1%` to `%value_10%` name any single place, for building your own layout. |
| `Entry` | What each place inside `%entries%` reads. `%place%`, `%player%` and `%value%` fill in. |
| `Line-Spacing` | How big the board is drawn. `0.28` is normal size; a bigger number makes the whole board bigger, a smaller one smaller. |
| `Head` | Whether the top player's head floats above the board at all. |
| `Head-Gap` | How far the head floats above the top line, in blocks. Negative brings it closer still. |
| `Category-Names` | What `%category%` reads per category, so `SOLO_WINS` can say `Solo Wins`. |

Colours work the same as everywhere else: `&`-codes, `&#RRGGBB`, gradients and rainbows. After
changing anything, `/asw refreshLeaderboards` redraws every board without a restart.

Nothing about a board is a block, so placing one changes no terrain and removing one leaves nothing
behind. Where they are is written to `leaderboards.yml`, which the plugin looks after for you.

A board in a world that is not loaded is kept in the file and skipped with a line in the console, so
loading that world later brings it back rather than losing it.

## Related pages

* [Shop and cosmetics](/features/shop-and-cosmetics), for what coins buy
* [Quests and challenges](/features/quests-and-challenges), for goals that repeat
* [Storage](/configuration/storage), for where stats live
* [Placeholders](/reference/placeholders)