MinecraftStats is a web browser application for the statistics that Minecraft servers collect about 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 Addict 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.

The system is highly customizable. All the awards are defined in Python modules that can be altered, added or removed to fit your needs. Additionally to simply reading Minecraft's original statistics, there are some awards that are combinations of various statistics.

A live demo of MinecraftStats in action is available here: DVG Snapshot Stats

This section describes how to set up MinecraftStats to work on your server.

Since version 2.0, MinecraftStats is compatible only to Minecraft 1.13 or later (more precisely: snapshot 17w47a or later). This is because starting with snapshot 17w47a, Minecraft stores statistics very differently from before. In the process of updating MinecraftStats for 1.13, the complete infrastructure has been rewritten and is in no way compatible to older servers.

If your server runs Minecraft 1.12.2 or prior, please use MinecraftStats 1.0 and do not follow this guide any further, but use the old guide.

I am trying to keep the statistics up to date with Minecraft snapshots. Since Mojang often decide to rename entity IDs, this may mean that compatibility to a prior release version of Minecraft breaks. If you notice such a case, please don't hesitate to open an issue about that!

If you used MinecraftStats 1.0 before, the only way to migrate is delete it and use this new version instead.

Any customizations (awards or other extensions) won't be compatible and need to be ported manually, because MinecraftStats 2.0 is a complete rewrite, much like the way Mojang apparently rewrote their statistics completely (more structured, but quite some stats have vanished).

Python 3.4 or later is required to feed MinecraftStats with your server's data.

Simply copy all files (or check out this repository) somewhere under your webserver's document root (e.g. htdocs/MinecraftStats).

The web application is simply index.html - so you'll simply need to point your players to the URL corresponding to the installation path.

The heart of MinecraftStats is the update.py script, which compiles the Minecraft server's statistics into a database that is used by the web application.

Simply change into the installation directory and pass the path to your Minecraft server to the update script like so: python3 update.py -s /path/to/server

You may encounter the following messages during the update:

• updating skin for <player> ... - the updater needs to download the player's skin URL every so often using Mojang's web API ,so that the browser won't have to do it later and slow the web application down. If this fails, make sure that Python is able to open https connections to sessionserver.mojang.com.
• unsupported data version 0 for <player> - this means that <player> has not logged into your server for a while and his data format is still from Minecraft 1.12.2 or earlier.

In case you encounter any error messages and can't find an explanation, don't hesistate to open an issue.

After the update, you will have a data directory that contains everything the web application needs. Fore more information about what it contains exactly, see below.

MinecraftStats does not include any means for automatic updates - you need to take care of this yourself. The most common way to do it on Linux servers is by creating a cronjob that starts the update script regularly, e.g., every 10 minutes.

If you're using Windows to run your server... shame on you, figure something out!

In case you use FTP to transfer the 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.

The update.py script accepts the following command-line options (and some more unimportant ones, try passing --help):

• -s <server> - the path to your Minecraft server. This is the only required option.
• -w <world> - if your server's main world (the one that contains the stats directory) is not named "world", pass its alternate name here.
• -d <path> - where to store the database ("data" per default). Note that the web application will only work if the database is in a directory called data next to index.html. You should not need this option unless you don't run the updater from within the web directory.
• --server-name <name> - specify the server's name displayed in the web app's heading. By default, the updater will read your server.properties file and use the motd setting, i.e., the same name that players see in the game.
• --inactive-days <days> - if a player does not join the server for more than <days> days (default: 7), then he is no longer eligible for any awards.
• --min-playtime <minutes> - only players who have played at least <minutes> minues (default: 0) on the server are eligible for awards.

The data directory will contain the following:

• db.json.gz - This is the database index used by the web application and for future updates. It is a simple JSON file compressed using gzip to reduce traffic by the web application. If you also need the uncompressed file for any reason, pass the --store-uncompressed option to the updater.
• server-icon.png - if your server has an icon, this will be a copy of it. Otherwise, a default icon will be used.
• rankings - this directory contains one JSON file for every award. These are dynamically loaded by the web application as needed.
• playerdata - this directory contains one JSON file for every player. These are dynamically loaded by the web application as needed.

I assume here that you have some very basic knowledge of Python, however, you may also get away without any.

update.py imports all modules from the mcstats/stats directory. Here you will find many .py files that define the awards in a pretty straightforward way.

The next time update.py is executed, changes here will be in effect.

For adding a new award, follow these steps:

1. Create a new module in mcstats/stats and register your MinecraftStat instances (see below).
2. Place an icon for the award in img/award-icons. If your award ID is my_award, the icon's file name needs to be my_award.png.

A MinecraftStat object consists of an ID, some meta information (title, description and a unit for statistic values) and a StatReader.

The ID is simply the award's internal identifier. It is used for the database and the web application also uses it to locate the award icon (img/award-icons/<id>.png).

The meta information is for display in the web application. The following units are supported:

• int - a simple integer number with no unit.
• ticks - time statistics are usually measured in ticks. The web application will convert this into a human readable duration (seconds, minutes, hours, ...).
• cm - Minecraft measures distances in centimeters. The web application will convert this to a suitable metric unit.

The StatReader is responsible for calculating the displayed and ranked statistic value. Most commonly, this simply reads one single entry from a player's statistics JSON, but more complex calculations are possible (e.g., summing up various statistics like for the mine_stone.

There are various readers, the usage of which is best explained by having a close look to the existing awards. If you require new types of calculations, dig in the mcstats/mcstats.py file and expand upon what's there.

In order to remove an award, find the corresponding module and delete or modify it to suit your needs.