Server Leaderboard

Server-side player statistics leaderboard with a customizable client HUD panel and chat commands. Tracks playtime, deaths, mob kills, and PvP kills across all online and offline players without server tick lag.

What does this mod do?

Server Leaderboard aggregates vanilla player statistics from active sessions and saved stats/<uuid>.json files, calculates server-wide rankings, and displays them via a lightweight, glassmorphic HUD panel or in chat.

1. Two HUD Display Styles

The overlay supports two distinct visual layouts that can be toggled on the fly:

• Category View (Style 1): A compact card focusing on one active category at a time. Displays category name, page count (1/4), ranks 1–10, and formatted values.
• Full Table View (Style 2): A comprehensive data matrix displaying player names and all enabled categories in side-by-side columns (Player, ⏱ Playtime, 💀 Deaths, 🗡 Mob Kills, ⚔ PvP Kills). Cycling the sort key dynamically re-sorts the table and highlights the active column.

2. Rank Badges & Active Player Row

• Rank Badges: First place is marked with a gold ① badge, second place with a white ② badge, third place with bronze ③, and 4th+ with clean light gray numbers.
• Current Player Highlight: The viewing player's row is highlighted with a cyan border accent and a soft background glow.
• Out-of-Top Pinning: If the viewing player is not in the top 10, a dedicated row is pinned at the bottom of the panel showing their exact server rank and personal score.

3. In-Game HUD Repositioning

Pressing the edit keybind enters an interactive positioning mode:

• Move the panel across a 9-point screen grid (top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right).
• Pulsating neon reticles frame the panel to indicate the active bounding box.
• Use arrow keys to reposition and press Enter or Esc to save.

4. Chat Commands

Players can check rankings directly in chat without opening the HUD:

• /leaderboard time — Top players by total playtime.
• /leaderboard deaths — Top players by death count.
• /leaderboard mob_kills — Top players by mob kills.
• /leaderboard player_kills — Top players by PvP kills.
• /leaderboard style <1|2> — Switch HUD display mode directly from chat.

Chat entries display player rank badges, username, an online status indicator (●), and the formatted score.

Default Controls & Keybindings

All keybindings can be rebound in the standard Minecraft Controls menu (Options -> Controls -> Key Binds -> Server Leaderboard):

Configuration

Client Settings (config/server_leaderboard-client.toml)

• display_style (1–2, default 1): Default HUD style (1 = Category card, 2 = Full table).
• position (1–9, default 3): Default screen grid position (3 = top-right corner).

Server Settings (config/server_leaderboard-server.toml)

• enabled_categories (default: ["play_time", "deaths", "mob_kills", "player_kills"]): List and display order of active tracking categories.
• hud_player_limit (1–20, default 10): Maximum number of top players shown on the HUD overlay.
• command_player_limit (1–50, default 10): Maximum number of players printed by /leaderboard chat commands.

Server Performance & Caching

Calculating server-wide rankings across hundreds of player files can introduce disk I/O bottlenecks. Server Leaderboard implements a dedicated thread-safe caching architecture:

• 30-Second Cache TTL: Online player statistics are read into memory and cached for 30 seconds (ConcurrentHashMap), eliminating up to 90% of disk read overhead.
• Non-Blocking Background Updates: Offline player files are loaded without stalling the main server tick.
• Smart Invalidation: Player cache entries automatically invalidate upon player connect and disconnect to keep rankings current.