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

# Vexal Leaderboards

A powerful and flexible Minecraft leaderboard plugin that allows you to create leaderboards from **any PlaceholderAPI placeholder**. Display rankings for kills, balance, blocks mined, playtime, or any other stat — all fully automated and easily configurable.

***

### 📦 Features

* 🧩 **PlaceholderAPI integration** — Generate leaderboards from any placeholder.
* 🪄 **Dynamic holograms** — Display leaderboards in the world using holograms.
* ⚡ **Efficient caching** — Keeps data updated while minimizing lag.
* 🔁 **Automatic refreshing** — Leaderboards update on a configurable schedule.
* 🧠 **Customizable formats** — Configure how leaderboards are displayed (titles, colors, lines, etc.).
* ⚙️ **Multi-source data** — Supports data from other plugins via PlaceholderAPI.
* 🛡️ **Optimized performance** — Lightweight and designed for high-performance servers.

***

### 🧱 Requirements

* Minecraft server running **Paper**, **Purpur**, or another Spigot-compatible fork.
* **PlaceholderAPI** plugin installed.
* (Optional) **HolographicDisplays** or **DecentHolograms** for hologram output.

***

### 🚀 Installation

1. Download the latest `VexalLeaderboards.jar` from the releases page.
2. Place it into your server's `/plugins/` folder.
3. Restart or reload your server.
4. Ensure **PlaceholderAPI** is installed and the placeholders you plan to use are functional.

***

### ⚙️ Configuration

After the first run, the plugin will generate a configuration file in:

```
/plugins/VexalLeaderboards/config.yml
```

#### Example Configuration

```yaml
leaderboards:
  top_money:
    placeholder: '%vault_eco_balance_top%'
    hologram-location: 'world,100,65,100'
    title: '&6Top Money'
    lines:
      - '&e#%position% &7%player% &f- &a$%value%'
    update-interval: 300 # in seconds
```

#### Available Options

| Option              | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `placeholder`       | The PlaceholderAPI placeholder used to generate the leaderboard. |
| `hologram-location` | Location to spawn the hologram leaderboard.                      |
| `title`             | Title text for the leaderboard.                                  |
| `lines`             | Format for each entry in the leaderboard.                        |
| `update-interval`   | Time (in seconds) between automatic updates.                     |

***

### 💬 Commands

| Command                      | Description                        | Permission                 |
| ---------------------------- | ---------------------------------- | -------------------------- |
| `/leaderboard reload`        | Reloads the plugin configuration.  | `vexalleaderboards.reload` |
| `/leaderboard update <name>` | Manually refreshes a leaderboard.  | `vexalleaderboards.update` |
| `/leaderboard list`          | Lists all configured leaderboards. | `vexalleaderboards.list`   |

***

### 🧾 Permissions

| Permission                 | Description                            |
| -------------------------- | -------------------------------------- |
| `vexalleaderboards.reload` | Allows reloading the config.           |
| `vexalleaderboards.update` | Allows manually updating leaderboards. |
| `vexalleaderboards.list`   | Allows viewing available leaderboards. |

***

### 🌈 Example Placeholders

Here are a few ideas of what you can track:

* `%statistic_mine_block_diamond_ore%` → Blocks mined
* `%vault_eco_balance%` → Player balance
* `%player_kills%` → Kills
* `%statistic_time_played%` → Playtime
* `%jobsreborn_jobs_level_<job>%` → Job level

Any valid PlaceholderAPI placeholder can be used — the plugin will handle sorting and ranking automatically.

***

### 🪧 Holograms

If you have **DecentHolograms** leaderboards can be displayed directly in-game as floating holograms.

* Supports dynamic updates without flicker.
* Automatically rebuilds holograms when refreshed.
* Customize colors, order, and size.

***