A clientside Fabric mod for Minecraft 1.21.11 that enriches the vanilla statistics screen with server-wide rankings from a GrimStats server.
- Rank badges on the General statistics tab: your server-wide rank (
#3) next to each stat, gold/silver/bronze for podium spots. - Leaderboard tooltips: hover any row on the General, Items or Mobs tab to see the top players for that stat and where you stand.
- Server Rankings screen: browse a live leaderboard for any stat (including modded ones),
with search across every stat type. Opened from the Rankings button on the statistics
screen, an optional keybind, or
/grimstatsc open. - Zero setup on most servers: the mod derives the API address from the server you are
connected to (
http://<server-ip>:8765). If the dashboard runs elsewhere, point the mod at it with/grimstatsc url https://stats.example.com. - Quiet by design: on servers without GrimStats everything hides itself. Failed requests back off and stop retrying, so there is no log or network spam.
- Player roster and profiles: browse everyone on the server (sortable by activity, recency, kills, K/D, or name, with an online filter), and open any player's profile: highlight stats with server ranks, a combat panel (kills, deaths, K/D, damage in hearts, most killed and killed-by mobs), top mined blocks, and a distance breakdown. Clicking a leaderboard row opens that player's profile.
- Config menu: an in-game settings screen (URL, token, port, fetch limit, toggles),
reachable from the Rankings screen, ModMenu if
installed,
/grimstatsc config, or a keybind. - Keybinds: a GrimStats category in Options > Controls with bindings for the Server Rankings and config screens (unbound by default).
All clientside, under /grimstatsc:
| Command | Effect |
|---|---|
/grimstatsc status |
Ping the resolved API and report health |
/grimstatsc open |
Open the Server Rankings screen |
/grimstatsc url <url or auto> |
Override or reset the API base URL |
/grimstatsc token <token> / token clear |
Set an API key to see admin-hidden stats |
/grimstatsc ranks on/off |
Toggle inline rank badges |
/grimstatsc tooltips on/off |
Toggle leaderboard tooltips |
config/grimstats-client.json:
{
"baseUrl": "",
"apiPort": 8765,
"apiToken": "",
"showInlineRanks": true,
"showTooltips": true,
"leaderboardLimit": 500
}baseUrl empty means auto-derive from the current server address using apiPort.
leaderboardLimit caps how many entries are fetched per stat; if you rank below the cap the
badge shows nothing and the tooltip reports you as unranked.
- Values shown for other players come from the server's stat snapshot (rebuilt every ~10s by default), so they can trail live play by a few seconds.
- Hidden stats configured on the server are simply absent for anonymous users; set an API key to see them.
./gradlew build
The jar lands in build/libs/. Requires Java 21. ./gradlew runSmoke launches a dev client
that verifies the mixins apply and the rankings screen renders, then exits.
CI builds and tests every push. Publishing a v*.*.* tag creates a GitHub release with the
jar attached:
./scripts/bump-version.ps1 patch -Tag # or scripts/bump-version.sh patch --tag
git push; git push origin v<version>
The bump script updates gradle.properties and rolls the Unreleased section of
CHANGELOG.md into the new version; the release workflow refuses tags that do not match
mod_version.