DirtyLeaderboards

<div align="center"> (https://img.shields.io/static/v1?label=romix42&message=DirtyLeaderboards&color=blue&logo=github)](https://github.com/romix42/DirtyLeaderboards "Go to GitHub repo") (https://img.shields.io/github/stars/romix42/DirtyLeaderboards?style=social)](https://github.com/romix42/DirtyLeaderboards) </div> <br> <div align="center"> (https://github.com/romix42/DirtyLeaderboards/actions/workflows/build.yml/badge.svg)](../../actions/workflows/build.yml) (https://img.shields.io/badge/License-CC_BY--NC_4.0-blue)](https://creativecommons.org/licenses/by-nc/4.0/) </div> <br> (https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate/?hosted_button_id=KPXD92CM944RL) (https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L3L71Q7HGY) <br> <div align="center"> !(https://cdn.modrinth.com/data/cached_images/8e85c2461fca1bbe7a97c7e1bd3b186c283c6fae_0.webp) </div> # DirtyLeaderboards > The ultimate™ leaderboards plugin. Allows you to make modern leaderboards easily. ## 📖 How It Works Everything you see is just vanilla `BlockDisplay`/`TextDisplay` entities, positioned and animated by the plugin every tick. Ten rows that slide in and out with real player heads (`<head:uuid>`) and item/particle icons (`<sprite:atlas:path>`). Displays cycle through however many leaderboards you configure, one at a time, with slide animations between them. You can run as many separate displays as you want, each with its own location and its own rotation. ## ⚠️ Important Notice > **Compatibility:** Requires **Paper 1.21.9 or newer**. The row > icons rely on the vanilla `sprite`/`head` text components added in 1.21.9, so this won't work > on Spigot or older versions (They will show as ` ` ⬅ a space). > > __(https://www.gamergeeks.net/apps/minecraft/list-of-atlas-sprites/java/1.21.9)__ ## ✨ Features - 🖼️ **Fully entity-based displays** - 🔁 **Multiple leaderboards per display**, rotating on a timer you control - 🔢 **Three data sources** - vanilla Bukkit **statistics**, a custom **Skript** syntax and **PlaceholderAPI** placeholder - 🎨 **Custom styling** - colors, icons (including animated ones, like the playtime clock), rank colors, number/time formatting are customizable for each leaderboard - 🧩 **Skript integration** - effects, expressions, a condition and a rotate event - 🔗 **PlaceholderAPI expansion** - 📡 **A Bukkit event** (`LeaderboardRotateEvent`) for plugin developers - ♻️ **Live reload** - `/dlb reload` reloads all three config files without a restart - 🏷️ **Multiple displays**, each independently started, stopped, skipped or moved ## 🗃️ Leaderboard Sources Each leaderboard in `leaderboards.yml` picks one `source`: - **`statistic`** - pulls straight from a vanilla Bukkit statistic (kills, deaths, playtime, you name it). Can't be manipulated without another plugin. - **`custom`** - Most commonly changed by our custom skript syntax. - **`placeholder`** - modified by PlaceholderAPI placeholders. Offline players are resolved in small batches per tick (`placeholder-players-per-tick` in `config.yml`) so it doesn't slow down the main thread on servers with lots of players. ## 🛠️ Commands Base command is `/dirtyleaderboards`.<br> Aliases: `dlb`, `leaderboards`, `dirtyboards`, `boards`, `db`, `dirtyboard`, `leaderboard`, `lb`, `dlbs`. If you only have one display configured, you can leave `<display>` empty and it'll default to your only leaderboard. | Command | Description | |---|---| | `/dlb help` | Lists the commands below | | `/dlb list` | Lists every display and whether it's running | | `/dlb reload` | Reloads `config.yml`, `leaderboards.yml` and `messages.yml` | | `/dlb start <display>` | Starts a display | | `/dlb stop <display>` | Stops a display | | `/dlb skip <display>` | Skips to the next leaderboard in the rotation | | `/dlb move <display>` | Moves a display to where you're standing and facing | ## 🔐 Permission | Permission | Description | Default | |---|---|---| | `dirtyleaderboards.admin` | Access to every `/dlb` subcommand | OP | ## 🧩 Skript The Skript addon registers itself automatically if Skript is present. ```ruby # control a display start the leaderboard display "main" stop the leaderboard display "main" skip the leaderboard display "main" # check state current leaderboard of display "main" leaderboard display "main" is running # read/write a single player's score on a "custom" source board set leaderboard data of player in "points" to 100 add 5 to leaderboard data of player in "points" remove 2 from leaderboard data of player in "points" reset leaderboard data of player in "points" # wipe an entire board for every player (not just yours) clear the leaderboard data for leaderboard "points" # react whenever any display rotates to a new leaderboard on leaderboard