Leaderboard data and controls reference
Mod version shipped with FlammiCraft: 1.18.0
Requirements and installation
- Minecraft 1.21.1
- NeoForge 21.1.250 or newer within the 21.1 series
- LDLib2 2.2.37 or newer
- Java 21
- TD LeaderBoard 1.18.0
- Network protocol 5
The mod is built against NeoForge 21.1.250 and accepts versions >= 21.1.250 and < 21.2 at runtime. Versions such as 21.1.250 and 21.1.251 are therefore supported. Install the same TD LeaderBoard build and compatible libraries on both the client and server. The network handshake requires matching payload channels and protocol 5; it does not compare TD LeaderBoard release numbers or JAR contents. Different releases using the same protocol can therefore pass this check. This version does not support a server-only installation.
Client settings are stored in config/tdleaderboard-client.toml. By default, deaths, distance walked, and total distance are visible; the leaderboard is sorted by deaths in descending order, and offline players are hidden.
Metrics
- Play time: Vanilla
minecraft:play_time, displayed as hours and minutes. AFK time is included. - Mob kills: Vanilla
minecraft:mob_kills; this is not limited to hostile mobs. - Deaths: Minecraft's
minecraft:deathsstatistic. - Distance walked: The sum of walking, sprinting, and crouching distances.
- Total distance: Distance walked plus swimming, climbing, falling, creative flight, Elytra flight, walking on water, walking underwater, and travel by minecart, boat, pig, horse, and Strider.
Minecraft stores distances in centimeters. TD LeaderBoard formats them as meters or kilometers without modifying the stored statistics.
Online and offline data
TDUtilities 1.29.0 with cluster AFK synchronization supplies the AFK icon for remote UUIDs without local vanilla TAB entries. Use updated TDUtilities builds on clients and every backend. Idle-display settings and useWatutAfkStatus still control the icon. Older renderers remain supported for local players. Ownership, heartbeat expiry and disconnect cleanup are handled by TDUtilities; visible cross-backend icons still need manual runtime acceptance.
Dedicated servers use TDLibrary 0.74.0 or newer for shared storage when [database] enabled = true in config/tdlibrary-database.toml. Configure every backend with the same MariaDB database, enable [cluster] enabled = true, and give each backend a unique id in cluster-node.toml. No separate leaderboard database settings are needed. Single-player and dedicated servers with database storage disabled retain local storage.
Database totals are keyed by player UUID. The earliest captured vanilla observation supplies the initial baseline, even if a later observation reaches MariaDB first. Later offline imports leave that baseline intact. Keep backend clocks synchronized so timestamps reflect the order of transfers. Old independent backend histories are not automatically summed because their counters may include copies of the same activity. Subsequent samples add locally observed progress. Vanilla statistics remain unchanged and no external profile requests or chunk loads are made.
TDLibrary supplies the player's current backend. The leaderboard shows a remote player as online only when a matching active session has a visible sample from the last five seconds. Session start time determines which session wins when updates arrive out of order. Logouts close their own session. A transfer may briefly show a player offline while the next session or TDLibrary presence is being published. Keep backend clocks synchronized and install this version on every backend. Backends running 1.14.0 still write the old presence table and cannot supply the new session view. AFK icons still depend on the optional client-side TDUtilities integration.
A background worker writes batches of at most 256 current UUIDs and refreshes the shared snapshot, normally every 20 server ticks when the previous job has completed. Transactions lock one player at a time with a two-second row-lock wait limit. A separate disk worker checkpoints pending live statistics under data/tdleaderboard-outbox/ in the server's world directory before database writes, including during a database outage. After a restart, earlier runs are replayed in bounded batches. Replays use the original backend and run ID so a commit followed by a crash counts once. Replays restore statistics and leave live session status to the current server. Samples captured since the last completed checkpoint can be lost if the process stops abruptly.
Database failures retain the last successful ranking totals and show synchronization as unavailable. Back up td_leaderboard_player, td_leaderboard_sample and td_leaderboard_session together. Preserve any pending files when moving or restoring a world, along with the original backend ID and the associated database. A damaged or mismatched pending file is preserved and reported in the server log. The new session table is created automatically. Existing statistics and write receipts carry forward, and the old presence table is left in place.
The database-mode offline importer checks local profiles first and looks up missing names in TDLibrary's shared name history in bounded asynchronous batches. A failed name lookup leaves the batch pending for retry. Profiles absent from both sources count as unresolved.
The earlier unpublished database preview used an incompatible schema. If its tables exist, the mod reports the incompatibility and preserves their data. Back up the preview tables and use a fresh leaderboard schema. The preview totals lack the information needed to recover the original baseline or capture periods automatically.
Without database storage, the startup importer scans local vanilla stats files on a background worker and resolves names from the local profile cache. It publishes up to 256 profiles per tick, skips unresolved names, reports malformed files and never overwrites players already captured live in the session. Local connected players supply live statistics; vanished players are treated as offline.
Reset shared statistics
Update every backend sharing the database to TD LeaderBoard 1.18.0 or newer before using a reset. The commands require active shared database storage and operator permission level 4. The server console can also run them.
/tdleaderboard reset player <name|UUID>resets one player, including offline players. Names come from TDLibrary's shared name history. Use the UUID when a name is unknown or matches multiple accounts./tdleaderboard reset all confirmresets everyone, including offline players whose local statistics have yet to be imported.
All five metrics in the all-time, weekly, and monthly rankings are reset in one transaction. The server confirms the reset after the transaction commits. Each backend picks up the change on its next successful synchronization and uses its first subsequent live sample as the new baseline. Older pending samples cannot restore the old totals. Vanilla statistics files remain the source for measuring new activity.
Include td_leaderboard_reset with the other leaderboard tables in backups. It stores which pending samples and historical imports the database can accept. The table is created automatically.
Usage
- Hold
TAB: show the compact leaderboard instead of the vanilla player list. - Run
/tdleaderboard: open the full-screen view. - Place either the dark
3D Leaderboardor the lightStone Brick Leaderboard: both require two free blocks of width, four free blocks of height, and solid ground beneath both base positions. All eight parts must be inside the world border. - As an operator, right-click a 3D leaderboard: open the server-authorized configuration for that board and select any of the five metrics and edit a plain-text title of up to 48 characters. An empty title restores the default heading; save with Done or discard with Cancel. The single-player host has the required permission. The configuration screen also provides a button for the complete leaderboard.
- Without operator permission, a regular right-click opens the full-screen view. Sneaking while right-clicking does not modify the board.
- Metric selection: browse Activity, Combat, and Travel categories; select a sort metric and toggle visible columns. Selecting a metric also enables its column.
- Period button: cycle between all-time, current calendar week, and current calendar month.
- Player search: enter part of a name and press Search or Enter; an empty search restores all players. Search preserves ranks from the full selected ranking.
- To me: clear the search and jump to the page containing your UUID.
- Player names: open a detail snapshot containing all five metrics for the selected period; Back returns to the same ranking.
- Direction: sort in ascending or descending order.
- Offline: include or exclude known offline players and recalculate the ranks.
- Column toggles: choose the visible metrics. At least one metric always remains enabled.
For the three original metrics, ties retain their previous secondary metric ordering. Play-time and mob-kill ties use player name and UUID as stable, deterministic criteria. The full-screen view returns at most 50 rows per page. The TAB view shows only the rows that fit the current resolution and directs players to /tdleaderboard when more results are available.
The interfaces use the current GUI-scaled screen dimensions; GUI Scale 2 is not required. The full-screen view adjusts its column widths and row count to the available space and uses tighter control spacing below 200 GUI pixels in height, keeping the table and navigation separate at 180 GUI pixels. If a window is too small to display every control safely, the full-screen and board-configuration views show a resize hint; the TAB view falls back to the vanilla player list.
Changing the sort order, page, or visible columns never mixes old and new query states. TAB, full-screen, and world-board snapshot requests share a client queue with at least 350 milliseconds between sends, so all five board metrics can load alongside the other views without exceeding the per-player snapshot limit. New queries replace queued requests for the same view; closing a view removes its queued request. When a request times out, the interface marks the state and automatically retries. Disconnecting clears the complete client cache and request queue so a leaderboard from a previous connection cannot be displayed. After resizing, the TAB view immediately limits cached rows to the new panel capacity and includes locally clipped rows in its count of players available in the full view. It falls back to the vanilla player list below 129 GUI pixels in height to preserve space for one row and the HUD. Unchanged client preferences are not saved again during automatic refreshes or page changes.
TDUtilities (tdutilities) 0.10.0 or newer provides the optional AFK integration. When its integrated player-status module is active, its client and server player-list idle displays are enabled, and useWatutAfkStatus is true in tdleaderboard-client.toml (the default), AFK players use its Z icon instead of the green online dot in the TAB and full-screen leaderboards. The legacy configuration key is retained so existing settings continue to apply. With the option disabled or without the active TDUtilities integration, TD LeaderBoard keeps the normal online and offline symbols. Installing standalone WATUT disables TDUtilities' integrated module and therefore this AFK indicator.
Both 3D leaderboard variants consist of eight connected block parts and have no crafting recipe. The original uses a blackstone frame, while the light variant uses normal stone bricks; both retain the gold accents, roof overhang, display behavior, and configuration options. Both items are available in the Functional Blocks creative tab. Separate left and right panel and roof models omit internal center-seam faces. The side frames match the complete front-to-back depth of the display, and every face outside the standard model cube uses UV coordinates bounded to its own texture sprite so adjacent atlas textures cannot bleed into the frame. The roof extends beyond the outer frame instead of sharing a coplanar face that can flicker. The renderer uses the bounds of the complete 2x4 structure, including the overhang, so text remains visible while looking up, crouching, or moving partly out of view.
Each controller stores its selected metric in its own block entity NBT. The server validates changes and synchronizes them to all tracking clients. The six highest-ranked known players for that metric are always shown in descending order and refreshed every five seconds. Client settings and screen periods do not affect world boards: each board displays its selected all-time metric. Custom titles are stored in block entity NBT and synchronized to tracking clients.
Breaking any part removes the complete structure and returns exactly one fresh item without the previous board setting. Returned boards can therefore stack up to 64 and use deaths as their default metric when placed again.
Weekly and monthly rankings
Periods use UTC calendar boundaries: Monday 00:00 for weeks and the first day at 00:00 for months. They measure increases in vanilla counters, not historical estimates. Each player's first observation establishes a baseline; existing totals are never assigned to the current period. The measurement-start label shows the later of the period boundary and the time local or shared period tracking was created. Players first observed later have a shorter measurement window.
In database mode, all backends read shared UTC week and month totals from MariaDB. Each increment is assigned to the UTC week and month of its sample. A delayed write preserves those periods. Activity between two samples falls into the period of the later sample. Local world history is preserved separately in data/tdleaderboard_periods.dat.
The following file and counter-reset rules apply to local storage. The current week and month are stored in data/tdleaderboard_periods.dat in the world and survive restarts. Completed periods are not archived. Live totals are sampled every 20 server ticks while the server runs, and on login/logout; period boundaries use the last sampled totals. Activity between the last sample and a boundary may be assigned to the new period. If a player's vanilla counters decrease, that player's week and month baselines are re-established to avoid inventing progress. Missing period data starts fresh tracking; corrupt or unsupported existing data fails explicitly instead of being silently overwritten. Include this file in world backups.
Category, column and board-metric changes rebuild the inner controls while retaining one screen wrapper. Board-metric changes preserve an unsaved title draft. Long player buttons retain separate name/title colors and styled text widths when shortened.
Detail views show the selected row's snapshot, not a continuously updating player monitor. Return to the ranking to refresh. TAB and world boards continue to show all-time values. Name resolution and offline availability follow the same rules for every period.
World boards keep available rows visible while explicitly reporting an ongoing or failed offline import, a pending refresh, or stale data. These states use a warning-colored footer instead of presenting an incomplete ranking as complete. After using To me, automatic refreshes retain the last valid snapshot for the resolved page, including when a refresh times out.
Structure-template mirroring and rotation preserve each board's controller, title, and metric. Mirrored boards use the matching panel and roof halves, text position, and render bounds. Existing boards load with the original, unmirrored layout.
Current limitations
- No integration with TDEconemy accounts or other economy data.
- No command blocks or external statistics services beyond TDLibrary's shared MariaDB.
- No global server configuration for the
TABand full-screen views; their visibility and sorting are client settings. World boards instead use their own server-side NBT.