MinecraftStats is a web browser application for the statistics that Minecraft servers collect for players.
The presentation is done by giving awards to players for certain achievements. For example, the player who played on the server for the longest total time receives the Dedication award. Every award has a viewable ranking associated to it with medals - the award holder gets the gold medal, the second the silver medal and the third the bronze medal for the award. Each medal gives players a crown score (1 for every bronze medal, 2 for every silver, 4 for every gold medal), which is displayed in a server hall of fame.
A live demo of MinecraftStats in action is available here: DVG Snapshot Stats. Feel free to join the project's Discord for help – or just for fun!
This is to give a brief overview as to how MinecraftStats works.
The web frontend of MinecraftStats is initially empty and needs to be fed data from your Minecraft server. This is done via an update.
The updater (either the plugin or the CLI, see below) will look at your players' statistics, which are typically stored in JSON files under world/stats in your Minecraft server's directory. From this, using predefined awards and events, it will compute rankings as well as a Hall of Fame score. The data is contained in a data directory in the web frontend's directory.
Using the Configuration, you can change some behaviour like excluding certain players. It is possible to run Events that track certain statistics only for a fixed amount of time – for example, picture a Skeleton Hunt event over Halloween. The system is extensible and you can add Custom Awards.
MinecraftStats comes in two flavors. You can use it as a Plugin or via the command-line interface (CLI). Briefly, if your server supports plugins (e.g., SpigotMC or PaperMC), using the plugin is the much easier way. If you are running a vanilla server or prefer to have data updates under more careful control, you will have to use the CLI.
This documentation is written for both variants. If anything special applies to one variant in particular, you will always find a corresponding subsection.
The Plugin has some exclusive features, making its use much easier than the CLI. Some features are for communication with other plugins, others are conveniences that are enabled by being run in the scope of a server application.
- Automatic updates at regular intervals.
- Automatic detection of webservers run by other plugins (dynmap).
- Support for offline-mode skins via SkinsRestorer (v15.0.0 or later).
This section will guide you through getting MinecraftStats up and running.
MinecraftStats supports Minecraft 1.13 or later. For the web frontend, a webserver is required.
The plugin can be used in any server capable of running Spigot plugins, particularly Spigot or PaperMC. MinecraftStats automatically detects the following plugins that feature a webserver:
That said, if you have any of the above plugins installed, there is no need to setup a webserver yourself unless you desire to.
Java 8 or later is required to run the CLI. You will need to setup a webserver yourself.
Simply place MinecraftStats.jar into your server's plugins directory.
If you intend to use your own webserver, follow the steps described for the web frontend setup below.
Unpack the MinecraftStatsCLI.zip from the release wherever you like. In the Configuration, you must set the data → documentRoot and server → sources settings to match your system.
Furthermore, follow the steps described for the web frontend setup below.
The server → sources setting supports multiple entries, so you can combine multiple servers into a single statistics browser.
Extract the contents of MinecraftStatsWeb.zip to the place within your document root that you configured in the data → documentRoot setting.
Make sure that the updater has write permissions to that directory.
If you previously used the Python version, you can use MinecraftStats almost like before by using the CLI. Bascially, update.py is now MinecraftStatsCLI.jar that you run via java -jar rather than Python. Just like for Minecraft 1.13, Java 8 or later is required.
In your config.json, you will now have to add the data → documentRoot setting that points to your webserver (see Configuration for details):
"data": {
"documentRoot": "/var/www/html"
},The server → customName setting has been renamed to client → serverName.
If you created custom awards, you will have to translate them to a JSON representation; the Python scripts will no longer work. Head to Custom Awards for details. If you used events, they are no longer stated in config.json but in separate files. See Events for details.
Depending on whether you use the plugin or the CLI, the configuration is done in a YAML or JSON file, respectively. The following settings apply for both.
-
data → documentRoot: Set this to where the web frontend of MinecraftStats resides (e.g.,index.html). This is where the updater will generate thedatadirectory that contains all the data for the web frontend to display. In the plugin, leave this tonullto make the plugin look for a supported webserver. -
data → eventsDir: The directory that event definitions are loaded from. See Events for details. In the plugin, this is relative to the plugin's directory; in the CLI, this is relative to the location of yourconfig.json. -
data → statsDir: The directory that custom award definitions are loaded from. See Custom Awards for details. In the plugin, this is relative to the plugin's directory; in the CLI, this is relative to the location of yourconfig.json. -
crown → bronzeMedal: The crown score a player gets in the Hall of Fame for a bronze medal. -
crown → silverMedal: The crown score a player gets in the Hall of Fame for a silver medal. -
crown → goldMedal: The crown score a player gets in the Hall of Fame for a gold medal. -
client → defaultLanguage: The ISO 639-1 code of the default language to use when none was explicitly selected by the user. -
client → playerCacheUUIDPrefix: Short explanation: do not touch. Determines player cache grouping by UUIDs. Most of the time you should leave the default value of 2 untouched. If you have many active players on your server (e.g., thousands) and wish to reduce traffic and load times somewhat, you may try increasing this to 3 to see if it helps. Note that increasing this value will increase the number of files underdata/playercacheexponentially (!), so handle with care. -
client → playersPerPage: How many players to display at most on one page of the players list. -
client → serverName: If this is set, this will be shown as the server's name in the web frontend. Leave it tonullto use the server's MOTD. -
client → showLastOnline: If set totrue, the last online date and time will be displayed in the web frontend. -
players → excludeBanned: Iftrue, exclude banned players from the stats. -
players → excludeOps: Iftrue, exclude ops from the stats. -
players → excludeUUIDs: An array of player UUIDs that will be excluded from the stats. -
players → inactiveDays: If a player is inactive for this many days, they will no longer be eligible for any awards. -
players → minPlaytime: Only players who have played at least this many minutes will be considered in the stats. -
players → profileUpdateInterval: Update player names and skins using the Mojang API every this many days. -
players → updateInterval: Update names and skins of inactive players.
The configuration is done in the plugin's config.yml. If it does not exist, the default configuration will be created.
The following settings are for the plugin only:
data → webSubdir: The name of the directory that MinecraftStats creates in the webserver's document root. This only applies ifdata → documentRootisnulland the plugin found a supported webserver.data → unpackWebFiles: If set totrue, the plugin will automatically unpack all the necessary files required for the web frontend. This only applies ifdata → documentRootisnulland the plugin found a supported webserver.⚠️ If you modify the web frontend, set this tofalseto ensure that your changes won't be overridden.data → updateInterval: The data for the web frontend is updated every this many minutes.
The configuration must be given in a JSON file. Edit the default config.json to reflect your server.
The following setting is required for the CLI:
-
server → sources: An array of data sources, each of which must define the following properties: -
path: The path to your Minecraft server. -
worldName: the name of the world on the server that contains the player statistics (i.e., thestatsdirectory with JSON files in it). In most cases, this is simplyworld.
This section describes the everyday use of MinecraftStats.
By installing the plugin with the default configuration and if you have a plugin featuring a webserver (see Requirements), you're already set. The plugin will automatically update the data for the web frontend once started, and then regularly according to the data → updateInterval setting.
If you rely on MinecraftStats to find a webserver plugin, this is how you and your players access the web frontend using a browser:
- dynmap: Let's say your URL is
my-server.com:8123, then you access the MinecraftStats frontend viamy-server.com:8123/stats/index.html. Note that due to how dynmap's webserver is configured, you cannot leave the/index.htmlpart by default. If you change thedata → webSubdirsetting, the/stats/part in the URL must be changed accordingly. - BlueMap: The same as for dynmap applies, but note that the default port there is different. The default URL in BlueMap will be
my-server.com:8100/stats/index.html. - squaremap: The same as for dynmap applies, but note that the default port there is different. The default URL in squaremap will be
my-server.com:8080/stats/index.html.
When using the CLI, the data for the web frontend needs to be updated by executing MinecraftStatsCLI.jar like so:
java -jar MinecraftStatsCLI.jar config.jsonThe CLI does not include any means for automatic updates - you need to take care of this yourself. The following lists some possibilities you might have.
The most common way to do automatic updates (on Linux servers) is by creating a cronjob that starts the update script regularly, e.g., every 10 minutes. Typically, a cronjob for MinecraftStats will look like this:
# update MinecraftStats every 5 minutes
*/5 * * * * java -jar MinecraftStatsCLI.jar config.json
data → documentRoot setting.
In case you use FTP to transfer the player's statistics JSON files to another machine before updating, please note that MinecraftStats uses a JSON file's last modified date in order to determine a player's last play time. Therefore, in order for it to function correctly, the last modified timestamps of the files need to be retained.
Events allow you to track a specific award for a limited amount of time. Events are defined in a JSON file each in the events directory either in the plugin's directory (or next to config.json for the CLI)..
The following information needs to be specified for an event:
-
name: The unique (internal) name of the event, which needs to be a valid file and URL name, i.e., you should not use spaces or special characters here. Every event needs a different name, even if they share the same title. -
title: The title of the event displayed in the browser. -
stat: The ID of the award stat counted for the event. An easy way to find these IDs is by clicking an award in the browser and getting it from the URL. -
startTime: The time at which the event starts in ISO 8601 format (e.g.,YYYY-MM-DD HH:MM, where the hour field assumes a 24h day). -
endTime: The time at which the event ends (same format asstartTime).
Be sure to align your start and end times to your update interval in order to avoid inaccuracies.
As an example, consider a Halloween-themed event called "Skeleton Hunt" that tracks how many skeletons people kill between October 30, 10 AM in the morning and midnight of November 1. We would create the file skeleton-hunt-2023.json in the events directory with the following contents:
{
"name": "skeleton_hunt_2023",
"title": "Skeleton Hunt",
"stat": "kill_skeleton",
"startTime": "2023-10-30 10:00",
"endTime": "2023-11-01 00:00"
}The awards are defined in the stats directoy in a JSON file each. You can create additional awards simply by adding another JSON file. By convention, the name of the JSON file should match the ID of the award.
A JSON object defining an award consists of the following felds:
- **
id**: The unique ID of the award. This is also the ID that you will later find in the URL in the web frontend. It must be a valid name for a file as well as a portion of a URL, so avoid special characters as well as spaces. unit: The unit in which award scores are measured. The following units commonly occur in Minecraft and are recognized:int: A plain integer number (e.g., the number of times a player has done something).cm: A number of centimeters, in which Minecraft measures distances (e.g., the distance a player has traveled in some way).ticks: A number of ticks, in which Minecraft measures durations (e.g., for how long a player has done something).tenths_of_heart: 1/10 of a heart, in which Minecraft measures health and damage (e.g., how much damage was done for something).
reader: Defines how data is read from the player statistics JSON files, see Data Readers for more information.minVersion(optional): The minimum data version that the server must have in order for this award to be enabled. If the server runs an older version of Minecraft, the award is not included in the web frontend. If no minimum version is specified, the default is 1451, which is the data version of snapshot 17w47a, the first version supported by MinecraftStats. You can find the data version of a specific Minecraft version by consulting the info panel on a version page in the Minecraft Wiki.
As a hint, if you wish to create a custom award, it is a good idea to find an already existing award that is similar to what you have in mind, and then copy its JSON file and edit it as needed. Especially regarding data readers, this is by far the most simple way that should work for almost all cases.
Readers define how an award score is determined from a player's statistics JSON. There are different types of readers that can be selected using the $type field. The other fields that are available depend on the selected type. The following is a listing of the available reader types, each with an example award (ID) for reference.
int: Reads a single integer from the nested object given by thepatharray. The final entry inpathis the name of the field to read. Example:jump.match-sum: Reads multiple integers from the nested bject given bypath. The fields that are read are given in thepatternsarray, which may contain regular expressions. Example:break_tools.set-count: Counts the number of distinct entries in the nested object or array given bypath. Example:biomes.
MinecraftStats also loads players' advancements. These can be accessed by stating advancements as the first node. An example can be found in the biomes award, which counts the number of different biomes a player has visited.
Place your award's icon into the img/award-icons directory of the web frontend. It must be named after the award's ID.
You give your award a human-readable title and description by editing the localization. The localization files are found in the localization directory of the web frontend with one JSON file per language each.
MinecraftStats is a Gradle project. By executing the release task, all release artifacts (Plugin, CLI and standalone web frontend) are generated from the source.
Here is some help troubleshooting common issues.
-
The CLI tells me
org.json.JSONException: JSONObject["data"] not found.- You have likely just migrated from Python and did not configure a document root yet.
-
The plugin tells me
No document root specified -- please state one explictly in the configuration, or install a supported plugin featuring a webserver!- You may not have a supported plugin with a webserver installed (see Requirements). Please install one of those, or set up a webserver by yourself following Installation.
-
The web frontend is stuck at the loader image and does not show anything.
- This typically means that the data generated by an update cannot be loaded. Please open the browser console (
F12 → Consolein most browsers) and look for error messages. - Any file not found (code 404) errors may hint that data has not been generated. Make sure there is a
datafolder in your webserver's document root. If not, chances are you did not run any update, or the data was written to a wrong location (double-check the configuration). - If there is anything logged about a CORS Policy, chances are you are trying to open
index.htmlfrom your filesystem directly. As a security measure, most browsers do not support loading JavaScript from the filesystem, hence the frontend will not work. Please use a local webserver instead. - In case you have configured your webserver to compress files before transfer to the client, this may cause it to compress the
.json.gzfiles of MinecraftStats and confuse the frontend, rendering it unable to properly decompress them. Please make sure that there is an exception for*.gzfiles – they are already compressed!
- This typically means that the data generated by an update cannot be loaded. Please open the browser console (
The project started as a hyper-casual idea to get player rankings for certain things. It was meant as a special attraction on our small snapshot survival server at DVGaming. Because we ran snapshot versions of Minecraft, vanilla servers had to be supported and thus a plugin for Bukkit was out of question. The project was a very simple command-line script in the beginning, and I chose Python to do that.
MinecraftStats was rewritten twice. The first rewrite happened in 2018 following the release of snapshot 17w47a for Minecraft 1.13, where Mojang change the structure of how Minecraft stores player statistics completely.
Throughout the years, MinecraftStats gained some popularity, much more than anticipated. With that, requests for a Bukkit (Spigot / PaperMC) plugin became more frequent. A first shot at a plugin that simply executed the Python script failed, because many hosters don't allow that. For that reason, and to reflect the fact that the project had become much more complex and the Python code became more and more of a mess, the project was rewritten in Java in a way that both plugin and vanilla servers are supported.
Only since the Java implementation, MinecraftStats officially has numbered versions that follow the Semantic Versioning scheme.
This update uses a newer API of SkinsRestorer and fixes more MOTD issues.
- Updated the SkinsRestorer API – version 15.0.0 or later is now required. Because of breaking changes in their API, older versions of SkinsRestorer are no longer supported.
- Fixed winners of finished events not displayed correctly.
- Fixed newlines being incorrectly replaced in the MOTD, causing the summary to become unparseable.
This update adds automatic detection of squremap's webserver and fixes bugs in both the plugin and CLI.
- The plugin now also auto-detects the webserver of squaremap.
- Fixed a 404 error in the frontend if the server has no (active) players.
- Fixed decoding of
server.propertiesto cause wrong display of server names / MOTDs. - Fixed parsing of BlueMap's web root directory.
This update fixes future events being displayed as "Finished" in the web frontend, as well as the "Invalid Date" display for event end times.
This update adds automatic detection of BlueMap's webserver and fixes bugs in the plugin.
- The plugin now also auto-detects the webserver of BlueMap.
- Fixed the
data → unpackWebFilesbeing ignored. - Fixed an issue with non-ASCII characters in generated JSON files, color-coded server MOTDs should now work again.
This update adds SkinsRestorer for the plugin and avoids unnecessary Mojang API calls.
- The plugin can now get skins from SkinsRestorer
14.2.215.0.0 or later. - If a player is detected to be an offline player (e.g., Floodgate players or if the Mojang API gave an empty response), no further attempts at asking the Mojang API will be made.
- Minimized the log output of the plugin.
This patch release fixes issues that occurred for offline-mode servers.
- The message logged when a player's UUID cannot be found by Mojang's API is now less scary.
- The plugin now gets dynmap's actual
webpathrather than assuming it to be "web". - Fixed a player's default name being their UUID, which causes their name never to be updated if they cannot be found by Mojang's API.
In full 202X fashion, here's a release-day patch that fixes an issue in the plugin. The CLI and web frontend are not affected.
- The plugin now gets the default world's actual name from the Bukkit server rather than assuming it to be
world.
This was the initial release of the Java reimplementation.
MinecraftStats is released under the Creative Commons BY-SA 4.0 license. This means you can pretty much use and modify it freely, with the only requirements being attribution and not putting it under restrictive licenses if modified.
The only requirement regarding attribution is that you provide a visible link to this original repository in your installment. The easiest way to do this is by not removing it from the footer in index.html where you will also find a reminder about this.
