AstralLeaderboards Overview

AstralLeaderboards is the network-wide ranking service for AstralRealms. Every paper server reports player scores for named leaderboards (economy, blocks mined, kills, …); a central master node aggregates and ranks them across the whole network, and every paper server reads back a cached top-N list plus each player's own standing. Leaderboards are tracked in three time windows simultaneously — all-time, weekly and monthly — so the same leaderboard id can be viewed as a rolling window without any extra configuration.

What it does

Network-wide ranking — scores written on any server are aggregated on the master node and broadcast back so every server's cache agrees.
Three period windows per leaderboard — ALL_TIME, WEEKLY (ISO week, e.g. 2026-W29) and MONTHLY (2026-07) buckets are maintained for every leaderboard at once; a menu can render the same leaderboard for any window.
Built-in trackers — blocks mined, mob kills and fish caught are recorded automatically via Bukkit listeners (permission-gated by leaderboards.bypass).
Custom leaderboards — any other plugin can push a score through the shared LeaderboardService (e.g. AstralEconomy, AstralJobs).
In-game UI — the /leaderboard command opens an AstralCore menu (leaderboards-list) and each entry is a chainable placeholder for building leaderboard/podium menus.
%leaderboards_*%/%leaderboard_*%/%entry_*% placeholders for reading a leaderboard's display, ranked entries, and a viewing player's own standing anywhere MiniMessage/placeholders are parsed.

Architecture at a glance

AstralLeaderboards ships as two separate deployables, both built from this repository:

Module	Runs on	Role
`paper`	Every Paper server (depends on AstralCore)	Player-facing: command, menu, placeholders, built-in trackers, per-player/per-leaderboard read cache.
`master`	One network-wide MageHic node	Authoritative: MariaDB `entries`/`leaderboards` tables, ranks every bucket, owns the Redis leaderboard cache, replies to paper's requests.

paper A: /leaderboard set ...──► UpdatePlayerEntryPacket ──┐
paper B: BlockBreakEvent ──► IncrementPlayerEntryPacket ───┤
                                                            ▼
                                              master: EntryService.save/increment
                                                            │
                                       ┌────────────────────┼────────────────────┐
                                       ▼                    ▼                    ▼
                              MariaDB `entries`     Redis ZSET (top N)   broadcast EntryUpdatedPacket
                              (all/weekly/monthly)  per (leaderboard,     + LeaderboardUpdatedPacket
                                                      period) bucket             │
                                                                                 ▼
                                                                 every paper's LeaderboardServiceImpl /
                                                                 EntriesService refreshes its Caffeine cache

See Architecture for the full cross-server sync flow, caches and the periodic rebuild safety nets.

Requirements

Dependency	Required	Notes
Paper 1.21+	Yes (paper module)	`api-version: 1.21`.
AstralCore	Yes (paper module)	Menus, messaging, cache, placeholders, `AstralPaperAPI.registerService`.
MageHic	Yes (master module)	Standalone network-core runtime the master node runs on (not a Paper plugin).
MariaDB / compatible SQL	Yes (master only)	Tables `entries` and `leaderboards`.
Redis	Yes (both modules)	Master: authoritative sorted-set cache. Paper: none directly — reads go through messaging, not Redis.
A messaging broker (RabbitMQ, via `MessagingService`)	Yes (both modules)	Exchange `leaderboards`, packets registered in `LeaderboardPacketRegistry`.

Where things live

Concern	Page
`config.yml` — declaring leaderboards, format, sort	Configuration
`/leaderboard` command and permissions	Commands
`%leaderboards_%`, `%leaderboard_%`, `%entry_*%`	Placeholders
Cross-server sync, caches, periodic rebuilds	Architecture
`LeaderboardService`, built-in trackers, extending	Developer API

Last modified: 25 July 2026