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

# leaderboards

DialogMaster features high-performance, asynchronous leaderboards with dynamic pagination and layout grids.

## 1. Leaderboard Data Sources

| Source      | Description                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `vault`     | Fetches balance from your server's economy provider (requires Vault)                              |
| `statistic` | Fetches native Minecraft player statistics (e.g. `PLAYER_KILLS`, `PLAY_ONE_MINUTE`, `MINE_BLOCK`) |

{% hint style="warning" %}
The `database` source is not yet implemented. Any leaderboard configured with `stat-source: database` will show an empty list and log a warning. Use `vault` or `statistic` instead.
{% endhint %}

## 2. Leaderboard Defaults

Repeated fields like `entries-per-page`, `button-width`, `columns`, and button configs are the same across most leaderboards. Instead of duplicating them, define them once in `leaderboard-defaults` inside `config.yml`:

```yaml
leaderboard-defaults:
  entries-per-page: 10
  button-width: 300
  columns: 1
  entry-click: "run-command"
  entry-click-value: "/profile %player%"
  entry-tooltip: "<gray>Click to view %player%"
  empty-label: "<gray>No data yet."
  back-button-label: "<gray>← Back"
  back-button-width: 100
```

Individual leaderboard blocks only need to define what's unique to them (title, stat-source, header-item, entry-label). Everything else falls back to `leaderboard-defaults`.

## 3. Individual Leaderboard Configuration

```yaml
leaderboards:

  money:
    title: "<gold><bold>⚡ Top Richest"
    stat-source: vault
    refresh-interval: 60        # Async refresh rate in seconds

    # Item shown at the top of the dialog above the entries
    header-item:
      material: GOLD_INGOT
      name: "<gold>Money Leaderboard"
      show-decorations: true
      show-tooltip: false
      width: 48
      height: 48

    # Label for each entry button — supports %rank%, %player%, %value%
    entry-label: "<white>#%rank% <aqua>%player% <gray>— <gold>$%value%"

    # Override defaults for this leaderboard only (optional)
    entry-tooltip: "<gray>Total server balance"
    empty-label: "<gray>No economy data yet."
```

### Statistic leaderboard example

```yaml
  kills:
    title: "<red><bold>☠ Top Killers"
    stat-source: statistic
    statistic: PLAYER_KILLS      # Any Bukkit Statistic enum value
    refresh-interval: 120
    header-item:
      material: IRON_SWORD
      name: "<red>Kill Leaderboard"
      show-decorations: true
      show-tooltip: false
      width: 48
      height: 48
    entry-label: "<white>#%rank% <aqua>%player% <gray>— <red>%value% kills"
```

### Statistic with value divisor

For statistics stored in raw ticks (like `PLAY_ONE_MINUTE`), use `value-divisor` to convert the raw value before display:

```yaml
  playtime:
    stat-source: statistic
    statistic: PLAY_ONE_MINUTE
    value-divisor: 1200          # ticks ÷ 1200 = minutes
    entry-label: "<white>#%rank% <aqua>%player% <gray>— <aqua>%value% min"
```

## 4. Entry Click Actions

The `entry-click` field controls what happens when a player clicks an entry button.

| Value             | Behaviour                                              |
| ----------------- | ------------------------------------------------------ |
| `run-command`     | Runs `entry-click-value` as the player (default)       |
| `suggest-command` | Pre-fills `entry-click-value` in the player's chat bar |
| `open-url`        | Opens `entry-click-value` in the browser               |
| `copy`            | Copies `entry-click-value` to the clipboard            |

Use `%player%` inside `entry-click-value` to substitute the entry's player name:

```yaml
entry-click: "run-command"
entry-click-value: "/profile %player%"
```

## 5. Value Formatting

Leaderboard values are formatted automatically:

* **Whole numbers** display without decimal places (e.g. `1,234`)
* **Fractional numbers** display with exactly 2 decimal places (e.g. `1,234.56`)
* Thousands separators are always applied

Use `%value%` in `entry-label` and `entry-tooltip` to insert the formatted value.

## 6. Opening Leaderboards from Menus

Use the `open-lb` action on any button to open a paginated leaderboard dialog:

```yaml
buttons:
  - label: "<gold>💰 Money"
    tooltip: "<gray>Top richest players"
    width: 150
    action: open-lb
    target: money              # Must match a key under leaderboards: in config.yml
    action-key: "dm:leaderboard_open"
```

## 7. Administrative Controls

Force an immediate async refresh on a specific leaderboard:

```bash
/ydm lb refresh <leaderboard_id>
```

*(Permission: `dialogmaster.admin`)*


---

# 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:

```
GET https://yowsef-development.gitbook.io/yowsef-development-docs/features/leaderboards.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.