✅CustomLeaderboards [1.21-26.2]

A lightweight and customizable Minecraft leaderboard plugin for Spigot and Paper servers.

Create daily, weekly and monthly leaderboards for playtime, mob kills, blocks mined, items crafted, economy balances and any supported PlaceholderAPI value.
DAILY •
WEEKLY •
MONTHLY •
PERMANENT

Paper & Spigot 1.21 • SQLite & MySQL • Rewards • Hologram Support

MORE PLUGINS BY DONCASPER99
Click a plugin to view its resource page.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

WHAT IS CUSTOMLEADERBOARDS?

CustomLeaderboards is a lightweight and configurable leaderboard plugin for Minecraft servers.

It tracks changes in numeric PlaceholderAPI values and creates daily, weekly, monthly, and permanent rankings. This makes it possible to build leaderboards for economy, statistics, jobs, tokens, points, playtime, or almost any other plugin that provides a numeric placeholder.

Everything is displayed through placeholders, allowing you to use your preferred hologram, scoreboard, menu, or chat plugin.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

MAIN FEATURES

• Timed leaderboards
  Daily, weekly, monthly, and permanent tracking periods.
  
• PlaceholderAPI sources
  Create leaderboard categories from configurable numeric placeholders.
  
• Automatic resets
  Configure reset days, times, month days, and Java timezones.
  
• Top rewards
  Run console commands, player commands, messages, centered messages, and broadcasts.
  
• SQLite and MySQL
  Use simple local SQLite storage or connect to an external MySQL database.
  
• Playtime support
  Raw Bukkit playtime tracking prevents localized text such as "4 days 22h" from breaking rankings.
  
• Hologram integration
  Use the included placeholders with DecentHolograms or another PlaceholderAPI-compatible display plugin.
  
• Safe command execution
  Database work is processed separately while Minecraft reward commands are dispatched safely on the server thread.
  
• Included documentation
  English configuration comments, a complete guide, reward examples, and a DecentHolograms example are generated automatically.
• Interactive GUI & Citizens NPC displays
  Browse leaderboards through /clb and display current or previous top-three players as individually placed Citizens NPCs with automatic skins and customizable text.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

DEFAULT LEADERBOARDS

CustomLeaderboards includes five example categories:

• Playtime
• Mob kills
• $ Money earned
• Items crafted
• Blocks mined
• ✦ Fish caught
  
• Weighted resource points

These are only defaults. Categories, sources, and resource point values can be customized in config.yml. Player-placed resources can also be excluded to prevent point farming.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

IMAGES

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

HOW IT WORKS

1. CustomLeaderboards reads each configured source for online players.
2. The first reading becomes the player's starting baseline.
3. Positive changes are added to the active periods.
4. Players are sorted by their earned value.
5. At reset time, rewards are resolved and the period begins again from zero.

This means a player with old lifetime statistics will not automatically receive those values on a new weekly leaderboard.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

REQUIREMENTS

• Minecraft: 1.21
• Java: 21
• Server software: Paper or Spigot
• Required: PlaceholderAPI
• Optional: Vault and an economy plugin for the default money source
• Optional: DecentHolograms

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

INSTALLATION

1. Stop your Minecraft server.
2. Install PlaceholderAPI.
3. Place CustomLeaderboards.jar in the plugins directory.
4. Start the server.
5. Edit plugins/CustomLeaderboards/config.yml.
6. Configure rewards in rewards.yml.
7. Restart the server or run /customleaderboards reload.

SQLite is enabled by default and requires no external database setup.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

COMMANDS

/customleaderboards reload
/customleaderboards update
/customleaderboards top <period> <top>
/customleaderboards forcereset <period> <true|false>
/customleaderboards debug

Short command alias:

/clb

Permission:

customleaderboards.admin

The permission is granted to server operators by default.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PLACEHOLDERS

General formats:

%customleaderboards_top_<top>;<period>;top_name;<position>%
%customleaderboards_top_<top>;<period>;top_value;<position>%
%customleaderboards_reset_cooldown_<period>%

Examples:

%customleaderboards_top_eco;weekly;top_name;1%
%customleaderboards_top_eco;weekly;top_value;1%

%customleaderboards_top_playtime;weekly;top_name;1%
%customleaderboards_top_playtime;weekly;top_value;1%

%customleaderboards_reset_cooldown_weekly%

Valid periods:

daily
weekly
monthly
permanent

PLACEHOLDERAPI SETUP

CustomLeaderboards requires PlaceholderAPI.
After installing PlaceholderAPI, run the following commands:

/papi ecloud download Statistic
/papi reload

If you use the Money leaderboard, install Vault and a compatible economy plugin.
The Vault placeholder may also require the Vault expansion:

/papi ecloud download Vault
/papi reload

You can test a placeholder with:

/papi parse me %statistic_time_played%

CustomLeaderboards registers its own placeholders automatically.
Do not download a separate CustomLeaderboards expansion.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CONFIGURATION EXAMPLES

tops:
  playtime:
    name: Playtime
    placeholder: '%statistic_time_played%'
    parse_time: true
    time_unit: ticks
    time_format: short

  kills:
    name: Mob Kills
    placeholder: '%statistic_mob_kills%'

  eco:
    name: Money Earned
    placeholder: '%vault_eco_balance%'

topResets:
  weekly:
    day: MONDAY
    time: '00:00:00'
    timezone: UTC

MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY

database:
  type: sqlite

  sqlite:
    file: leaderboards.db

database:
  type: mysql

  mysql:
    host: localhost
    port: 3306
    database: leaderboards
    user: root
    password: 'change-me'
    use-ssl: false

rewards:
  weekly:
    eco:
      top1:
        top: 1
        rewards:
          - 'console_command: give <player> diamond 3'
          - 'message: &7'
          - 'center_message: &6&l TOP &e#<top> &6&lMONEY &f- &b$<amount>'
          - 'message: &aYou placed first in weekly money!'

      top2:
        top: 2
        rewards:
          - 'console_command: give <player> diamond 2'
          - 'message: &7'
          - 'center_message: &6&l TOP &e#<top> &6&lMONEY &f- &b$<amount>'
          - 'message: &aYou placed second in weekly money!'

      top3:
        top: 3
        rewards:
          - 'console_command: give <player> diamond 1'
          - 'message: &7'
          - 'center_message: &6&l TOP &e#<top> &6&lMONEY &f- &b$<amount>'
          - 'message: &aYou placed third in weekly money!'

    kills:
      top1:
        top: 1
        rewards:
          - 'console_command: give <player> diamond 3'
          - 'message: &7'
          - 'center_message: &6&l TOP &e#<top> &6&lKILLS &f- &b<amount>'
          - 'message: &aYou placed first in weekly mob kills!'

      top2:
        top: 2
        rewards:
          - 'console_command: give <player> diamond 2'
          - 'message: &7'
          - 'center_message: &6&l TOP &e#<top> &6&lKILLS &f- &b<amount>'
          - 'message: &aYou placed second in weekly mob kills!'

      top3:
        top: 3
        rewards:
          - 'console_command: give <player> diamond 1'
          - 'message: &7'
          - 'center_message: &6&l TOP &e#<top> &6&lKILLS &f- &b<amount>'
          - 'message: &aYou placed third in weekly mob kills!'

    playtime:
      top1:
        top: 1
        rewards:
          - 'console_command: give <player> diamond 3'
          - 'message: &7'
          - 'center_message: &6&l⏱ TOP &e#<top> &6&lPLAYTIME &f- &b<amount>'
          - 'message: &aYou placed first in weekly playtime!'

      top2:
        top: 2
        rewards:
          - 'console_command: give <player> diamond 2'
          - 'message: &7'
          - 'center_message: &6&l⏱ TOP &e#<top> &6&lPLAYTIME &f- &b<amount>'
          - 'message: &aYou placed second in weekly playtime!'

      top3:
        top: 3
        rewards:
          - 'console_command: give <player> diamond 1'
          - 'message: &7'
          - 'center_message: &6&l⏱ TOP &e#<top> &6&lPLAYTIME &f- &b<amount>'
          - 'message: &aYou placed third in weekly playtime!'

<player> - Player name
<top>    - Leaderboard position
<amount> - Player's leaderboard value

location: world:0.500:100.000:0.500
enabled: true
display-range: 48
update-range: 48
update-interval: 10
facing: 0.0
down-origin: false

pages:
  - lines:
      - content: '&6&lBest Players of the Week'
        height: 0.3

      - content: '&7(Resets in %customleaderboards_reset_cooldown_weekly%)'
        height: 0.3

      - content: '&eTop Playtime: &f%customleaderboards_top_playtime;weekly;top_name;1% &7(&b%customleaderboards_top_playtime;weekly;top_value;1%&7)'
        height: 0.3

    actions: {}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

INCLUDED FILES

The plugin automatically generates:

• config.yml – leaderboard, reset, database, and performance settings
• rewards.yml – configurable winner rewards
• GUIDE.md – complete setup and troubleshooting guide
• hologram-example.yml – ready-to-edit DecentHolograms example
• leaderboards.db – created automatically when SQLite is selected

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TEST SERVER

Want to test the plugin before downloading it?
Join our test server using the IP below:

202.36.95.132

SUPPORT & FEEDBACK

Questions, bug reports, and feature suggestions are welcome in the resource discussion thread.

Please include your server version, plugin version, configuration without passwords, and the relevant console error when reporting a problem.

CustomLeaderboards is my first publicly released Minecraft plugin.
Feedback, suggestions, and bug reports are greatly appreciated!

★ DOWNLOAD MILESTONES ★

Thank you to everyone who has downloaded and supported CustomLeaderboards!

• 30 Downloads — August 1, 2026
• 40 Downloads — August 3, 2026
• 50 Downloads — August 6, 2026
• 60 Downloads — August 13, 2026
• 70 Downloads — August 15, 2026
• 80 Downloads — August 17, 2026
• 90 Downloads — August 20, 2026
• 100 Downloads — August 23, 2026
  
• Thank you so much for supporting my first plugin!

More milestones will be added as CustomLeaderboards continues to grow. Thank you for the support!