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

Click to view the list of sprites and their path.

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

# 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 rotate:
    broadcast "%rotated display id% just switched to %rotated leaderboard id%"

🔗 PlaceholderAPI

Registers as %dirtyleaderboards_...% once PlaceholderAPI is installed:

Placeholder	Returns
%dirtyleaderboards_top_<board>_<rank>_name%	Name of the player at that rank
%dirtyleaderboards_top_<board>_<rank>_value%	Their value, formatted (e.g. 15.2k)
%dirtyleaderboards_top_<board>_<rank>_raw%	Their value, unformatted
%dirtyleaderboards_value_<board>%	The viewing player's own value, formatted
%dirtyleaderboards_raw_<board>%	The viewing player's own value, unformatted

⚙️ Configuration

• config.yml - global settings: caching, number/time formatting, and one displays: entry per billboard (location, rotation order, colors, block types).
• leaderboards.yml - the leaderboards themselves: source, title, icon, formatting, and stored values for custom boards.
• messages.yml - every message the plugin sends. Uses MiniMessage.

A single leaderboard entry looks like this:

leaderboards:
  kills:
    enabled: true
    source: statistic
    statistic: player_kills
    title: "TOP KILLS"
    title-color: "#ee2a2a"
    value-color: "#FFD263"
    icon: "<sprite:items:item/diamond_sword>"
    icon-width: 12
    format: number
    minimum-value: 1
    duration-seconds: 15

---