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.

MinecraftStats is compatible only to Minecraft 1.13 or later (more precisely: snapshot 17w47a or later).

I am trying to keep the statistics up to date with Minecraft snapshots. Mojang sometimes decide to rename entity or statistic IDs, which may break stats. I am trying my best to update accordingly, but please don't hesitate to open an issue in case you notice something is wrong!

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 profile 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.
• HTTP Error 429 - Mojang has some limitations on their API that MinecraftStats uses to get player skins. If too many requests for the same player are done within a certain time frame (the exact specs are not known to me), Mojang's API refuses the request with a 429 code. This normally shouldn't happen if you use the default profile update interval.
• unsupported data version 0 for <player> - this means that <player> has not logged into your server for a long time 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.

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 less important ones, check --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. Minecraft color codes are supported! 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's server browser.
• --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.
• --crown-gold <score> - worth of a gold medal against the crown score (default: 4).
• --crown-silver <score> - worth of a silver medal against the crown score (default: 2).
• --crown-bronze <score> - worth of a bronze medal against the crown score (default: 1).
• --start-event <id> - see below.
• --stop-event <id> - see below.
• --delete-event <id> - see below.

The data directory will contain the following after running an update:

• summary.json.gz - This is a summary for the web application, containing information about the server and everything needed to display the award listing.
• server-icon.png - if your server has an icon, this will be a copy of it. Otherwise, a default icon will be used.
• playercache - cache of player names and skin IDs, grouped by player UUIDs.
• playerdata - contains one JSON file for every player, containing information displayed in the player view.
• playerlist - contains an index for player information used by the player list.
• rankings - contains one JSON file for every award containing player rankings.

Events allow you to track a specific award stat for a limited amount of time. For example, let's consider a Halloween-themed event called "Skeleton Hunt" that tracks how many skeletons people kill between October 30 and November 1.

An event can be started by passing --start-event <id> to the updater, where <id> is a unique identifier for the event. You cannot have multilple events with the same ID. Additionally, you require to pass the following two parameters:

• --event-title <title> - sets the title of the event displayed in the browser.
• --event-stat <id> - sets the stat to be tracked in the event according to the given award ID.

To set up our example Skeleton Hunt event, we would use this:

update.py [...] --start-event halloween2019 --event-title "Skeleton Hunt" --event-stat kill_skeleton

Note the [...] - you will have to pass all parameters that you usually pass for an update, which will be changed in the future (see issue #85).

To stop an event, use --stop-event <id>, with <id> being the identifier of the event to stop. Note that a stopped event cannot be restarted. So in our example,

update.py [...] --stop-event halloween2019

would stop the Halloween event. Again, [...] means that this is a normal update and all the other parameters have to be passed.

Using --delete-event <id>, the event with identifier <id> is deleted completely. This cannot be undone.

Like with automatic updates, MinecraftStats provides no such concept of its own. Automatic event schedules can also be done using cronjobs that run exactly once - one for starting and a second one for stopping.

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.

Any changes will be in effect the next time update.py is executed.

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.

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 (e.g., commercial) licenses if modified.

Concerning the attribution part, the only requirement 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 index.html footer, where you will also find a reminder about this.