averninstats

README

averninstats

A stats processor for Minecraft Java Edition servers. It reads the per-player stats JSON files that Minecraft writes to disk, resolves player names and skins via the Mojang API, and generates a static website with highscores, per-block, per-item, per-entity breakdowns and individual player profiles.

Live Demo

Website: stats.avernin.one

Github Repository: averninstats-website

Highscore	Player

Command-Line Options

$ ./averninstats --help
Usage of ./averninstats:
    --cache-dir string            Directory for cache files (default "./cache")
    --cache-max-age int           Max cache age in hours before renewal (default 336)
    --config string               Path to a optional YAML config file
    --exclude-uuids strings       Exclude UUIDs from being processed
    --frontend                    Copy frontend files to the configured output directory (default true)
    --help                        Print this help message and exit
    --languages strings           Languages used in frontend for translations (default [en-gb])
    --last-check-jitter int       Random jitter in hours added to cache expiry (default 96)
    --list-languages              List available languages and exit
    --log-debug                   Enable debug logging
    --log-json                    Enable JSON log format
    --log-no-color                Disable log colors
    --min-play-time int           Minimum playtime in minutes to include a player (default 10)
    --minecraft-version string    Target Minecraft version (default "26.1.2")
    --minify                      Minify output files (default true)
    --num-highscores int          Global highscore list size per stat (default 10)
    --num-player-highscores int   Per-player top-N scores per category (default 5)
    --output-dir string           Directory for output files (default "./output")
    --stats-source-dir string     Directory with per-player stats JSON files (default "./stats")
    --version                     Print version information and exit

Customization

In the final output in assets/templates you will files that start with a _underscore (_footer.mustache, _title.mustache, _topnav-links.mustache, ...). Those files are meant to give a easy entrypoint to edit dynamic parts of the website. Of course you can completly overwrite all parts the generated output.

How to use

The output directory will contain a ready-to-serve static website. Point any web server (nginx, caddy, apache) at it, or push it into a github repository and serve it via github-pages.

The cache directory should be persistent to avoid unnecessary API calls, downloads and rebuilding of the lookup maps.

Docker

docker pull ghcr.io/avernin-one/averninstats

docker run --rm \
  -v /path/to/minecraft/world/players/stats:/stats:ro \
  -v /path/to/output:/output \
  -v /path/to/cache:/cache \
  ghcr.io/avernin-one/averninstats \
  --stats-source-dir /stats \
  --output-dir /output \
  --cache-dir /cache \
  --languages=en-gb,de-de \
  --minecraft-version 26.1.2

Run Binary

Download Release

Go to the Release Page and download the latest binary for your system.

Build From source

git clone https://github.com/avernin-one/averninstats
cd averninstats
go build -o averninstats .

Execute

./averninstats \
  --stats-source-dir /path/to/world/stats \
  --output-dir ./output \
  --cache-dir ./cache \
  --languages=en-gb,de-de \
  --minecraft-version 26.1.2