Chronicle Stats

Please feel free to join my discord if you run into issues or have ideas! https://discord.gg/mKgxyk6qvb

…or you just want to hangout

Works with

Chronicle Stats runs on its own on any 0.7.0 server and picks these mods up by itself when they are installed. None of them is required and none needs any setup on the Chronicle Stats side.

Coming later. Dominion Factions standings, MMO Skill Tree, Endless Leveling, PartyPro and the VaultUnlocked economy bridge.

Overview

Chronicle Stats does not need any other mod. It is ten times better with TrackerAPI. With TrackerAPI installed, Chronicle Stats stops hooking the engine itself and reads every event from one shared tracker, so the server pays for tracking once however many stats plugins it runs, the counts agree with Feats and Atlas, and the dashboard shows "TrackerAPI connected" at the top right. Without it, everything on this page still works.

Chronicle Stats counts what happens on your server. Blocks broken and placed per block, creatures slain per creature, bosses with fastest kills by party size and hard mode clears, damage by cause, distance by how you moved, crafts per bench, zones, biomes and Memories, world events, weather, sessions and playtime, and the server's own tick rate, memory and entity counts. Everything is kept per player, per world and for the whole server, with history by day, so every leaderboard works for today, this week, this month and all time. Offline players are always ranked.

In game, /stats opens a tabbed browser with search, sorting and paging, /top shows a leaderboard with a podium, /stats vs puts two players side by side and /stats recap sums up your week. A small optional HUD and record toasts keep the tracking visible while you play.

The web dashboard runs inside the plugin on its own port, with nothing else to host and no outside service. It serves player profiles with a playstyle radar and an activity calendar, head to head comparisons, leaderboards that show who climbed since yesterday, a hall of records, boss boards in speedrun style, a bestiary, a danger index of where and when players die, retention cohorts and a performance page for admins. It updates live while you watch and fits a phone.

The mod is a server plugin with a small UI asset pack bundled in the jar. It works in singleplayer worlds and on dedicated servers alike, and players join with an unmodified client. All data stays on your server.

Features

New in 1.2

• Queued bench crafts count correctly. The engine reports one craft event per finished unit of a queued batch and stamps each with the whole batch quantity, which made a batch of a hundred count as ten thousand crafts. Instant crafts were always right. Totals counted before 1.2.1 are not rewound.
• Record and personal best toasts have a quiet window per record, so a growing kill streak is announced once, then once more with its final value, instead of on every kill. See recordToastQuietSeconds.
• Works with TrackerAPI. With TrackerAPI installed, Chronicle Stats stops registering 22 of its own tracking hooks and two polls and reads everything from TrackerAPI, with the same rules for placed blocks, own drops and boss credit. The dashboard header and the /stats page show whether it is connected.
• A few numbers move under TrackerAPI. Weather time follows the world's weather rather than each player's, the in game hour on a death record can lag by up to a minute, and the RPG Leveling level of a creature is not known on death records while TrackerAPI is in use.

What gets counted

• 116 named statistics, from time played and blocks broken to longest fall, biggest hit, close calls and blood moons. 12 of them belong to the server as a whole, such as chunks generated, restarts and the most players online.
• 31 creature groups such as goblins, Trorks, Void creatures, undead, livestock and each Gobliterator fight, so "any goblin" just works.
• 35 breakdowns by type. Blocks broken, placed and used, items crafted, gained, picked up, dropped and eaten, kills and deaths per creature and cause, damage by cause, abilities per ability, distance per movement mode, time per world, zone, biome and weather, ore by depth, crafts per bench, portals, Memories and mounts.
• Server performance once a minute. Ticks per second against each world's own target, tick times, memory, garbage collection, entities, chunks and players online, with restart and crash markers.

Leaderboards

• 46 leaderboard stats. 40 of them have today, this week, this month and all time boards, and 6 records such as longest session and best kill streak keep an all time board. With RPG Leveling installed, RPG level and RPG experience add two more all time boards.
• Per type boards for kills per creature, blocks broken, blocks placed and items crafted, up to 128 types each, and kills per boss, up to 64 bosses.
• Per world boards for up to eight worlds.
• Rank and percentile beside every stat on your own page, and movers that show who climbed and who fell since yesterday or last week.

Bosses and records

• Every boss fight is kept with its party, duration, damage per player, hard mode and outcome.
• Fastest kills by party size from one to five, first kills, hard mode clears and deathless Gobliterator kills.
• Server records with the current holder and the one before, personal bests, and server milestones that show as a big title for everyone.

In game pages

Four pages and a HUD, all built from the game's own UI.

• /stats has ten tabs. Overview, Combat, Bosses, Gathering, Items, Creatures, Travel, Discovery, Records and Server, plus Feats when Feats is installed. Items and Creatures are tables you can sort by any column, search and page through. The Server tab updates every second while it is open. With RPG Leveling, the Overview tab shows your level, XP, class, tier and XP by source.
• /top shows a podium for the top three, the rest of the board and your own rank pinned at the bottom, with tabs for each window.
• /stats vs compares twelve stats side by side, counts who leads, and shows your fights against each other and both playstyles.
• /stats recap covers this week with top deeds, new records, rank changes, your best day and your longest session.
• The HUD shows up to five lines. By default those are kills this session, blocks broken, time played, the deadliest creature of the day and your progress to the next record.

Web dashboard

Fifteen pages with fifteen kinds of chart, in a light and a dark theme.

The chart kinds are time series, sparklines, ranked bars, mirrored bars, columns, donuts, radars, calendars, punchcards, bullets, step lines, stacked areas, a 24 hour ring, a cohort triangle and a level ring. Every link is shareable and the page follows the server through one live event stream.

For other tools

• export/stats.json holds the top ten of each leaderboard, server totals and the latest records, with hidden players shown as "A player". Atlas reads it for its Chronicle tab.
• PlaceholderAPI forms are %chronicle_total_<key>%, %chronicle_today_<key>%, %chronicle_week_<key>%, %chronicle_month_<key>%, %chronicle_rank_<key>% and %chronicle_rank_<key>_<window>%, where the window is today, week, month or all.

Getting started

1. Download ChronicleStats-<version>.jar.
2. Put it in your Mods folder.
   • Windows %APPDATA%\Hytale\UserData\Mods
   • macOS ~/Library/Application Support/Hytale/UserData/Mods
   • Dedicated server, the server's mods/ directory
3. Start the world or server. Counting begins the moment a player joins.
4. Type /stats in game, or open http://<server address>:8124/ in a browser.
5. Run /chronicle link in game and click the link to sign your browser in as your player.

Warning Set publicUrl in chronicle.json before you share the dashboard, otherwise /chronicle and /chronicle link cannot give players a working address.

Warning Open port 8124 in the firewall only if the dashboard should be reachable from other machines.

Commands

Player commands are open to everyone. Admin commands need the chronicle.admin permission, and the server console has it.

A set of /chronicle debug test tools exists for admins and stays off unless debugCommands is true.

Configuration

chronicle.json is created in mods/Ryvrook_ChronicleStats/ on first start. Edit it and run /chronicle reload. Missing keys are written back with their defaults and values out of range are corrected with a line in the log. These are the keys most owners touch first.

The dashboard has thirteen visibility layers, each public, linked or admin. By default everything is public except the players list and CSV downloads, which need a linked browser, and performance, which is for admins. The retention keys are listed in the privacy policy.

Every key reloads live except maxWorldKeys, maxSeriesWorlds, boardWorldKeys, boardIdCaps and apiBoardKeysMax, which need a restart. timeZone and weekStart apply from the next day. A chronicle.json that does not parse is refused by the reload, so Chronicle Stats keeps the running settings, leaves the file as it is and says which line to fix.

Privacy

Everything Chronicle Stats records stays on your server, in the mod's folder. Nothing is sent to any outside service, IP addresses are never written to disk and chat text is never read. Players can go private with /chronicle privacy private, owners can keep players off the boards entirely, and death heights are shown to admins only. Players hidden on the Atlas map are treated like hidden staff, left off boards and /top. When a player asks to be removed, /chronicle admin erase <player> --confirm or the Erase button in the dashboard settings removes everything Chronicle Stats holds about them, and a record they held alone goes back to the player before them. An erase cut short by a restart finishes at the next start, and a later Feats import cannot bring the player back. A short privacy policy you can publish for your players ships as docs/PRIVACY.md, with every file and retention period spelled out.

Requirements

• Hytale server 0.7.0 or newer, tested on 0.7.1.
• Java 25.
• No other mods required. TrackerAPI, Feats, Atlas, RPG Leveling, BetterMap and PlaceholderAPI are picked up when present.

Server owners

One hostname for the map and the dashboard

To share one login with Atlas, serve both from one hostname under two base paths, such as https://example.com/map/ and https://example.com/stats/. Set basePath to /map in atlas.json and to /stats in chronicle.json, keep the same cookieName in both, bind both to 127.0.0.1 and list the proxy in trustedProxies. Set publicUrl in Chronicle Stats to the full address and chronicleUrl in Atlas to the same address, so the Chronicle tab in Atlas links to the dashboard, and set atlasUrl in Chronicle Stats to the map address so profiles link to the map. Both cookies carry Path=/, so a login on either site works on the other.

In the proxy, send /map/ to http://127.0.0.1:8123 and /stats/ to http://127.0.0.1:8124 with the full path left on, since each mod strips its own base path. Pass the X-Forwarded-For and X-Forwarded-Proto headers, and turn response buffering off for both so the live event streams reach browsers at once.

Warning Behind a reverse proxy, list it in trustedProxies. Otherwise every browser shares the proxy's address for rate limits and the login cookie is never marked Secure.

The admin token

adminToken is generated on first start and grants full access to the API, including private players and death heights. It is meant for scripts and tools. Staff in a browser run /chronicle link instead and get the admin view when they hold chronicle.admin.

Warning Keep chronicle.json private. If the token ever leaks, change it and run /chronicle reload.

Excluded players and hidden staff

• excludedPlayers keeps test accounts and bots off every board and out of every record. Their activity still counts toward server totals.
• hideStaffPermission does the same for staff. Grant chronicle.hide to a player or group. The * wildcard operators hold does not count, so an owner who plays is still ranked, and an explicit -chronicle.hide wins.
• Players hidden in Atlas are treated like hidden staff. They are left off boards, the board CSV and /top, and /stats <name> answers them like an unknown name.
• Hidden and private players show as "A player" on boards, records, the death feed and the export, and their profile opens only for themselves and admins.

Note Players who played before Chronicle Stats was installed start from zero. With Feats installed, /chronicle admin import feats brings over what Feats kept for players Chronicle Stats has never seen.

Known limits

Chronicle Stats 1.2.1 runs on a live 0.7.1 server with real players beside Feats, Atlas and TrackerAPI, and every release is checked on a headless server with synthetic players, unit tests, a load test of 200 browsers and screenshots of every dashboard page at desktop and phone width. What has not been confirmed in a real client yet is how the in game pages, the HUD next to BetterMap, the toasts and the TrackerAPI chip on /stats look, since no client has drawn them so far.

• With TrackerAPI installed, weather time follows the world's weather rather than each player's, the in game hour on a death record can lag by up to a minute, the level of a creature from RPG Leveling is not known on death records, and health, stamina and mana need vitalsSeconds set to 1 in TrackerAPI.json. Without TrackerAPI none of this applies.
• Crafts queued at a bench before 1.2.1 were over counted, see New in 1.2. Those totals stay as they are unless an admin resets them.
• The RPG Leveling class and tier of a player show once they were online since the server started. Levels and XP show for everyone.
• /chronicle admin reset clears a player's counters but keeps their records and logged sessions, deaths and boss fights until those expire. /chronicle admin erase removes everything, but only for a player who is offline, and it leaves Feats files and backups alone. A Feats import skips an erased player until they join again.
• A logout on the map while Chronicle Stats is not running is not seen by the dashboard, which keeps that login until the player logs out there or leaves it unused for sessionDays.

Links

• Source code https://github.com/ryvrook/chronicle-stats (Private)
• Discord https://discord.gg/mKgxyk6qvb
• More mods by ryvrook https://www.curseforge.com/members/ryvrook/