mcStats-parser

Python script to parse player statistics from Minecraft's stats folder and generate a leaderboard.

How it works

• Reads .json stat files from the specified directory.
• Extracts a given statistic key (e.g., mined:stone).
• Detects the value type (time, distance, etc.) and formats it.
• Maps each player's UUID to their username using usercache.json.
• Sorts players by their stat values in descending order.
• Outputs two files:
  • rating.json: list of players with results and ranking.
  • total.json: total value across all players.

Usage

If you are unsure of the exact stat names, use the --list flag to scan your files and generate an available.json helper file:

python main.py --stats ./stats --usercache ./usercache.json --list

Generate leaderboards:

# Parse specific stats (use colon for path, comma for list)
python main.py --stats ./stats --usercache ./usercache.json --params "custom:jump,used:golden_carrot"

# Collect ALL discovered statistics from all players
python main.py --stats ./stats --usercache ./usercache.json --all --exclude-zero

Command arguments:

Parameter	Description	Example
--stats	Path the world stats/ directory	--stats ~/server/world/stats
--usercache	Path to usercache.json	--usercache ~/server/usercache.json
--params	Stats to collect	--params used:apple,custom:play_time
--exclude-zero	Exclude players with "result": 0	--exclude-zero
--list	Generate available.json and exit	--list
--all	Process every available stat found in files	--all
--name	Custom name for the output folder (default: results)	--name my_leaderboard

How to determine what to use in --params

To specify the correct statistic path for the --params argument, follow these steps:

1. Run the script with --list

2. Open the generated available.json.

3. Locate the category and parameter. Example: If you see "minecraft:used": ["minecraft:diamond_pickaxe"], your param is used:diamond_pickaxe.

Requirements

• Python 3.10+