Mitra Leaderboards

A flexible and high-performance leaderboard system for Fabric servers. It computes and publishes leaderboards from placeholders (e.g. blocks mined, play time, kills, etc.), with optional MongoDB support to store and display offline players.

---

✨ Features

• Multiple leaderboards: define as many holders as you want (e.g. blocks_mined, time_played, kills…).
• Native placeholders (pb4/Patbox): exposes values for TAB, HUDs, holograms, or any plugin/mod that reads placeholders.
• Per-holder update scheduling (configurable in seconds).
• Online or offline mode:
  • Online-only: TOP is computed with currently connected players (no DB).
  • Offline tracking: saves and queries from MongoDB for global TOPs.
• Asynchronous execution: safe capture on the server thread, heavy work in async workers.
• Optimized for thousands of players: efficient TOP-K selection, minimal I/O and CPU.
• Robust placeholder evaluation: cleans values and prevents crashes if a placeholder fails.

---

✅ Requirements

• Fabric Loader + Fabric API (server).
• pb4 Placeholders (Patbox) for placeholder resolution/registration.
• MongoDB (optional) only if you enable offline tracking (trackOffline: true in a holder).

---

📦 Installation

1. Download Mitra Leaderboards and its requirements.
2. Place the .jar files in the mods/ folder of the server (and client if you want HUDs).
3. Start the server to generate the config folders.
4. Configure leaderboard.yml (and mongo.yml if you plan to use offline tracking).
5. Restart.

---

⚙️ Configuration

leaderboard.yml

holders:
  blocks_mined:
    valueCheck: "%mitra:mined_total%"
    update: 20
    top: 10
    trackOffline: false

  time_played:
    valueCheck: "%mitra:play_time%"
    update: 30
    top: 15
    trackOffline: true

---

🧩 Placeholders

For a holder named blocks_mined:

---

📏 Size and timers

• %mitra:leaderboard blocks_mined_size% → number of entries.
• %mitra:leaderboard blocks_mined_update_in_s% → seconds until the next update.
• %mitra:leaderboard blocks_mined_update_in_hms% → remaining time in HH:MM:SS.

---

🏆 TOP by position (N ≥ 1)

• %mitra:leaderboard blocks_mined_value_N% → numeric value.

• %mitra:leaderboard blocks_mined_player_N% → player name.

• %mitra:leaderboard blocks_mined_uuid_N% → player UUID.

• #1 %mitra:leaderboard blocks_mined_player_1% — %mitra:leaderboard blocks_mined_value_1%

• #2 %mitra:leaderboard blocks_mined_player_2% — %mitra:leaderboard blocks_mined_value_2%

• #3 %mitra:leaderboard blocks_mined_player_3% — %mitra:leaderboard blocks_mined_value_3%

---

📜 Commands

(Base command may differ depending on your setup; examples use /lb)

• /lb reload
  Reloads the leaderboard.yml configuration and reschedules all tasks.
  Useful when you change values in the config without restarting the server.

• /lb recompute <holder>
  Forces an immediate recompute of the specified holder.
  Example: /lb recompute blocks_mined will update the ranking for the blocks_mined leaderboard instantly.

• /lb list
  Displays a list of all currently active holders.
  Example output:

---

👨‍💻 Authors & Credits

• Developer: srmast3r_ (SrMaster)
• Twitter/X: @SrMaster
• Credits: pb4 Placeholders by Patbox