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

***


---

# Agent Instructions: 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://docs.vexalstudios.com/minecraft-plugins/vexal-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.