MinecraftStats

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!

Overview

This is to give a brief overview as to how MinecraftStats works.

Data Updates

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.

Plugin vs. CLI

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.

Plugin Exclusives

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).

Setup

This section will guide you through getting MinecraftStats up and running.

Requirements

MinecraftStats supports Minecraft 1.13 or later. For the web frontend, a webserver is required.

Plugin

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:

• dynmap
• BlueMap
• squaremap

That said, if you have any of the above plugins installed, there is no need to setup a webserver yourself unless you desire to.

CLI

Java 8 or later is required to run the CLI. You will need to setup a webserver yourself.

Installation

Plugin

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.

CLI

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.

Combining Multiple Servers (BungeeCord)

The server → sources setting supports multiple entries, so you can combine multiple servers into a single statistics browser.

Web Frontend Setup

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.

Migrating from Python

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.

:warning: The former workflow of simply cloning this repository and updating away is now deprecated. The repository only contains the source code, the runnable jar and ready web frontend files must be built from source or can be downloaded from the releases. To migrate, keep your config and follow the steps described for the CLI and Web Frontend above, then do the following config updates.

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.

Configuration

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 the data directory that contains all the data for the web frontend to display. In the plugin, leave this to null to 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 your config.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 your config.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 under data/playercache exponentially (!), 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 to null to use the server's MOTD.

• client → showLastOnline : If set to true, the last online date and time will be displayed in the web frontend.

• players → excludeBanned : If true, exclude banned players from the stats.

• players → excludeOps : If true, 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.

Plugin

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