MCStatsCompiler

A Python script to compile Minecraft server statistics and generate various leaderboards and visualizations.

Features

• Vanilla Minecraft statistics processing
• Cobblemon mod statistics processing
• Multiple leaderboard types:
  • Standard leaderboard (total Pokémon caught)
  • Shiny Pokémon leaderboard
  • Legendary Pokémon leaderboard
  • Money leaderboard
• SQLite database output for real-time leaderboard updates
• Docker support for easy deployment
• Frontend web interface for displaying leaderboards

Docker Setup

The project includes Docker support with three main components:

1. Leaderboard Updater Service

   • Runs the main statistics compiler script
   • Updates every 5 minutes
   • Stores data in a SQLite database
   • Health check ensures database exists

2. Frontend Service

   • Web interface for displaying leaderboards
   • Connects to the SQLite database
   • Runs on port 8080
   • Health check ensures service is running

3. Data Volume

   • Shared volume between services
   • Stores the SQLite database and other data files

Running with Docker Compose

1. Create a downloads directory next to the docker-compose.yml file
2. Download required modpacks into the downloads directory
3. Set up your CF_API_KEY in a .env file
4. Run:

   docker compose up -d

The frontend will be available at http://localhost:8080

Environment Variables

The following environment variables are used to configure paths:

• DB_PATH: Path to the SQLite database (default: data/scoreboard.db)
• STATS_PATH: Path to Minecraft stats directory (default: data/stats)
• PLAYERDATA_PATH: Path to Minecraft playerdata directory (default: data/playerdata)
• ADVANCEMENTS_PATH: Path to Minecraft advancements directory (default: data/advancements)
• COBBLEMON_PLAYERDATA_PATH: Path to Cobblemon player data (default: data/cobblemonplayerdata)
• POKEMON_PCSTORE_PATH: Path to Pokémon PC store data (default: data/pokemon/pcstore)
• POKEMON_PARTYSTORE_PATH: Path to Pokémon party store data (default: data/pokemon/playerpartystore)
• USERCACHE_PATH: Path to Minecraft usercache directory (default: data/usercache)

Directory Structure

/data
├── world/
│   ├── stats/
│   ├── playerdata/
│   ├── advancements/
│   ├── cobblemonplayerdata/
│   ├── pokemon/
│   │   ├── pcstore/
│   │   └── playerpartystore/
│   └── usercache/
└── scoreboard.db

Configuration

The script is configured through config.ini. Key settings include:

• Input mode (manual, local, FTP, SFTP)
• Database settings
• Leaderboard types to generate
• Visualization options

Database Structure

The SQLite database contains four main tables:

1. standard_leaderboard

   • Rank
   • Player name
   • Score (total Pokémon caught)
   • Last update timestamp

2. shiny_leaderboard

   • Rank
   • Player name
   • Score (shiny Pokémon caught)
   • Last update timestamp

3. legendary_leaderboard

   • Rank
   • Player name
   • Score (legendary Pokémon caught)
   • Last update timestamp

4. money_leaderboard

   • Rank
   • Player name
   • Score (total money)
   • Last update timestamp

Requirements

• Python 3.9+
• Docker and Docker Compose (for containerized deployment)
• Required Python packages (see requirements.txt)

License

[Your license information here]

Fork modification

Removed the use of the xlsx file and created a SQLite database with a nodeJS frontend to display it. Containerized the entire stack and changed the paths to the following tree structure:

Automatically generated by the cobblemon-server

• /data: Minecraft server file
• /data/world: Minecraft maps folder
• /data/world/cobblemonplayerdata: Cobblemon player data

Leaderboard-updater

• /cobblemon_module: Current Cobblemon module
• /data/scoreboard.db: Database generated and displayed on the front panel
• /data/global.csv: Global CSV Scoreboard

These changes make it easier to deploy on kubernetes.

Disclaimer

This was coded for my own use originally, but I've decided to share it in case it can be useful to someone else. It is still work in progress, and requires some knowledge of Python.

The script is intended to be executed on your own computer and not on a server. It could be executed on a server, but it probably requires a little adaptation.

Also, most of the recent features have not been tested extensively, so there are probably some bugs. Feel free to report them in the Issues section.

Modules

For now, there are 2 "modules" in this project. Note: the 2 modules are now in the same Python file main.py

Main module

This module takes vanilla stats files (json and dat format) that can be found in the folder "stats". It has currently the following features:

• A leaderboard (console printed-only for now) of the desired statistic. For example, minecraft:play_time for the play time of each player.
• A "best-and-worst" (console printed-only for now) for the desired player. This gives the position of the player in each of the leaderboards of individual stats.
• An image containing multiple small leaderboards for desired statistics (configurable in the config). Also works with the Cobblemon module.

Cobblemon module

This module takes statistics files generated by the Cobblemon mod (json format) that can be found in the folder "cobblemonplayerdata". It has currently the following features:

• A leaderboard of the players who caught the most Cobblemons, the most shiny Cobblemons, the most Legendary Cobblemons, and who has the most money. The leaderboard is output on an Excel sheet.
• A network graph representing the PvP duels done by players, where each player is represented by a node.
• A bar chart representing how often each Cobblemon type has been caught.
• A CSV file containing some stats about pokeballs used by the players.
• Individual player cards, formatted in a Minecraft way, each containing some stats about the player.

Running the scripts

1. Installation

In order to run the scripts, start by downloading this repo. You need a valid installation of Python, as well as the required libraries. The necessary libraries are listed in requirements.txt.

You can install them all at once by executing the following command in the project folder: pip install -r requirements.txt

2. Edit the config

There is 1 config to edit, config.ini. Read it, and if needed, edit it based on what you want.

3. Update usercache.json

All of your data files should be named [uuid].json, where [uuid] is the Minecraft UUID of the player. In order to work with the usernames of the players instead, you need to update the file data/usercache.json. Simply download it from your server (it should be at the root folder) and put it there. If you use the FTP setting (see below), the script will go and file the file for you (no need to update it manually then).

Note: if your server is in offline-mode (cracked mode), you might have players with same name but different UUIDs, which will crash the script. You need to fix that manually in the usercache.json.

4. Input files

You have the choice between 4 options to input data files: manual, local, ftp or sftp. In the config, manual is by default.

• manual: upload manually all the files in the relevant folders in the data folder of the project
• local: you have a server on your local machine/computer, in this case simply give the path to the main folder in the config.
• ftp: use an ftp connection to a distant server
• sftp: use an sftp connection to a distant server

If you use the manual option, drop the files in the appropriate subfolders in the data folder (stats, usercache...). The subfolders have the same name that they should have on your server. If you use other options, follow the instructions in the config.

5a. Prepare leaderboard_usernames.csv

If you intend on using the top-image, pvp network or player cards feature, you can update staticdata/leaderboard_usernames.csv to display other "real" nicknames instead of the Minecraft usernames.

(Cobblemon module only) 5b. Prepare output.xlsx

If you intend on using the leaderboard feature of the Cobblemon module, you can optionally modify the output.xlsx file. Simply adapt the table to your desired number of players (for example, if you expect 20 players, you can for example have a 5x4 table or a 10x2 table). You can also change the title, the colors and other formatting elements. Just make sure to keep 3 Excel columns per leaderboard column, and start it in the cell B3 (see example in the image below).

Don't forget to adapt the config file to your changes, especially the number of rows and columns if you have changed them! The subtitles of the table can also be configured there.

(Cobblemon module only) 5c. Prepare Pokemon.csv

If you intend on using the "Most Legendary Cobblemons" Leaderboard (which is disabled by default), you can edit staticdata/Pokemon.csv. This is not needed, but if you want to change which pokémons are considered as legendary for the leaderboard, it is done there.

(Cobblemon module only) 5d. Prepare cards.csv

If you intend on using the individual player cards feature (which is disabled by default), you can edit staticdata/cards.csv. This is where you can edit the text on the player cards.

6. Run the script

You can now run the main.py script of the module with your Python installation.

Frequent problems

1. This script uses local paths, so make sure that you are executing the Python script from the folder! If you get errors related json files, it's probably that the script couldn't find it.
2. The Cobblemon leaderboard feature only produces the XLSX table. To display an image in-game, you still need to convert the table to an image and then upload it somewhere. Feel free to contact me if you need help or tips with that.
3. This script is not automatic by default; you need to run it manually periodically for it to work. Optionnally, you can setup something on your own machine to run it automatically.

Interesting forks

The following forks of this project might be of interest to you:

• floooz/MCStatsCompiler-autoupload This fork implements a possible next step for the Cobblemon leaderboards, which is automatically converting the tables from the output.xlsx file to images and uploading them to a GitHub repo. These images can then be used in-game, for example with the projector from the SlideShow mod.
• ThibautChoppy/MCStatsCompiler This fork runs the script in a Docker container and outputs the leaderboard on a nice-looking web page rather than in an XLSX file.

---

Version française

MCStatsCompiler

Description

Ce projet vise à traiter un ensemble de fichiers de statistiques générés par des joueurs de Minecraft et à produire des statistiques formatées de manière lisible.

Configuration Docker

Le projet inclut le support Docker avec trois composants principaux :

1. Service Leaderboard Updater

   • Exécute le script principal de compilation des statistiques
   • Met à jour toutes les 5 minutes
   • Stocke les données dans une base de données SQLite
   • Vérification de santé pour s'assurer que la base de données existe

2. Service Frontend

   • Interface web pour afficher les classements
   • Se connecte à la base de données SQLite
   • Fonctionne sur le port 8080
   • Vérification de santé pour s'assurer que le service fonctionne

3. Volume de Données

   • Volume partagé entre les services
   • Stocke la base de données SQLite et autres fichiers de données

Exécution avec Docker Compose

1. Créez un dossier downloads à côté du fichier docker-compose.yml
2. Téléchargez les modpacks requis dans le dossier downloads
3. Configurez votre CF_API_KEY dans un fichier .env
4. Exécutez :

   docker compose up -d

L'interface frontend sera disponible à l'adresse http://localhost:8080

Variables d'Environnement

Les variables d'environnement suivantes sont utilisées pour configurer les chemins :

• DB_PATH: Chemin vers la base de données SQLite (par défaut: data/scoreboard.db)
• STATS_PATH: Chemin vers le dossier des statistiques Minecraft (par défaut: data/stats)
• PLAYERDATA_PATH: Chemin vers le dossier des données joueurs Minecraft (par défaut: data/playerdata)
• ADVANCEMENTS_PATH: Chemin vers le dossier des avancées Minecraft (par défaut: data/advancements)
• COBBLEMON_PLAYERDATA_PATH: Chemin vers les données joueurs Cobblemon (par défaut: data/cobblemonplayerdata)
• POKEMON_PCSTORE_PATH: Chemin vers les données du PC Pokémon (par défaut: data/pokemon/pcstore)
• POKEMON_PARTYSTORE_PATH: Chemin vers les données du stockage d'équipe Pokémon (par défaut: data/pokemon/playerpartystore)
• USERCACHE_PATH: Chemin vers le dossier usercache Minecraft (par défaut: data/usercache)

Structure des Dossiers

/data
├── world/
│   ├── stats/
│   ├── playerdata/
│   ├── advancements/
│   ├── cobblemonplayerdata/
│   ├── pokemon/
│   │   ├── pcstore/
│   │   └── playerpartystore/
│   └── usercache/
└── scoreboard.db

Avertissement

Ce projet a été initialement codé pour mon propre usage, mais j'ai décidé de le partager au cas où il pourrait être utile à quelqu'un d'autre. Il est encore en cours de développement et nécessite une certaine connaissance de Python.

Le script est destiné à être exécuté sur votre propre ordinateur et non sur un serveur. Il pourrait être exécuté sur un serveur, mais cela nécessiterait probablement quelques adaptations.

De plus, la plupart des fonctionnalités récentes n'ont pas été testées de manière approfondie, et il est donc probable qu'il y ait des bugs. N'hésitez pas à les signaler dans la section Issues.

Modules

Actuellement, ce projet comporte deux "modules". Note : les deux modules sont désormais dans le même fichier Python, main.py.

Module principal

Ce module traite les fichiers de statistiques vanilla (au format JSON et dat) situés dans le dossier "stats". Il propose actuellement les fonctionnalités suivantes :

• Un classement (affiché uniquement en console pour l'instant) de la statistique souhaitée. Par exemple, minecraft:play_time pour le temps de jeu de chaque joueur.
• Un "meilleur-et-pire" (affiché uniquement en console pour l'instant) pour un joueur donné. Cela indique la position du joueur dans chaque classement de statistiques individuelles.
• Une image contenant plusieurs petits classements pour les statistiques souhaitées (configurables dans la config). Fonctionne également avec le module Cobblemon.

Module Cobblemon

Ce module traite les fichiers de statistiques générés par le mod Cobblemon (au format JSON) situés dans le dossier "cobblemonplayerdata". Il propose actuellement les fonctionnalités suivantes :

• Un classement des joueurs qui ont attrapé le plus de Cobblemons, le plus de Shiny Cobblemons, le plus de Cobblemons légendaires, et qui ont le plus d'argent. Le classement est affiché sur une feuille Excel.
• Un graphique en réseau représentant les duels PvP effectués par les joueurs, où chaque joueur est représenté par un noeud.
• Un diagramme à barres représentant le nombre de fois où chaque type de Cobblemon a été attrapé.
• Un fichier CSV contenant des statistiques sur les pokéballs utilisées par les joueurs.
• Des fiches individuelles de joueurs, formatées à la manière de Minecraft, contenant chacune des statistiques sur le joueur.

Exécution des scripts

1. Installation

Pour exécuter les scripts, commencez par télécharger ce dépôt. Vous avez besoin d'une installation valide de Python ainsi que des bibliothèques requises. Les bibliothèques nécessaires qui ne sont pas installées par défaut avec Python sont listées dans requirements.txt.

Vous pouvez les installer tous en même temps en exécutant la commande suivante dans le dossier do projet : pip install -r requirements.txt.

2. Modifier la configuration

Un seul fichier de configuration est à modifier : config.ini. Lisez-le et modifiez-le si nécessaire en fonction de vos besoins.

3. Mettre à jour usercache.json

Tous vos fichiers de données doivent être nommés [uuid].json, où [uuid] correspond à l'UUID Minecraft du joueur. Pour utiliser les noms d'utilisateur des joueurs, vous devez mettre à jour le fichier data/usercache.json. Il vous suffit de le télécharger depuis votre serveur (il se trouve normalement à la racine du dossier) et de le placer dans ce répertoire. Si vous utilisez l'option FTP (voir ci-dessous), le script récupérera automatiquement ce fichier (pas besoin de le mettre à jour manuellement).

4. Fichiers d'entrée

Vous avez le choix entre quatre méthodes pour importer les fichiers de données : manuel, local, FTP ou SFTP. Par défaut, l'option "manuel" est activée dans la configuration.

• manuel : ajoutez manuellement tous les fichiers dans les dossiers appropriés du dossier "data" du projet.
• local : si vous exécutez un serveur sur votre machine locale, indiquez simplement le chemin du dossier principal dans la configuration.
• ftp : utilisez une connexion FTP vers un serveur distant.
• sftp : utilisez une connexion SFTP vers un serveur distant.

Si vous utilisez l'option manuelle, déposez les fichiers dans les sous-dossiers appropriés du dossier data (stats, usercache...). Les sous-dossiers ont le même nom que celui qu'ils devraient avoir sur votre serveur. Pour les autres options, suivez les instructions dans la configuration.

(Module Cobblemon uniquement) 5a. Préparer leaderboard_usernames.csv

Si vous avez l'intention d'utiliser les fonctions top-image, réseau pvp ou cartes de joueurs, vous pouvez mettre à jour staticdata/leaderboard_usernames.csv pour afficher d'autres surnoms "réels" au lieu des noms d'utilisateur Minecraft.

(Module Cobblemon uniquement) 5b. Préparer output.xlsx

Si vous souhaitez utiliser la fonctionnalité de classement du module Cobblemon, vous pouvez optionnellement modifier le fichier output.xlsx. Adaptez simplement le tableau à votre nombre de joueurs prévu (par exemple, si vous attendez 20 joueurs, vous pouvez opter pour un tableau de 5x4 ou 10x2). Vous pouvez également modifier le titre, les couleurs et les éléments de mise en forme. Assurez-vous simplement de garder trois colonnes Excel par classement et de commencer dans la cellule B3.

N'oubliez pas d'adapter le fichier de configuration à vos modifications, notamment le nombre de lignes et de colonnes. Les sous-titres du tableau peuvent également être configurés ici.

(Module Cobblemon uniquement) 5c. Préparer Pokemon.csv

Si vous utilisez le classement "Cobblemons Légendaires" (désactivé par défaut), vous pouvez modifier Pokemon.csv. Ce n'est pas obligatoire, mais si vous souhaitez définir quels Pokémons sont considérés comme légendaires pour le classement, vous pouvez le faire ici.

(Module Cobblemon uniquement) 5d. Préparer cards.csv

Si vous avez l'intention d'utiliser la fonction de cartes de joueur individuelles (qui est désactivée par défaut), vous pouvez éditer staticdata/cards.csv. C'est là que vous pouvez modifier le texte sur les fiches de joueurs.

6. Exécuter le script

Vous pouvez maintenant exécuter le script main.py avec votre installation Python.

Problèmes fréquents

1. Ce script utilise des chemins locaux, assurez-vous donc de l'exécuter depuis le bon dossier ! Si vous obtenez des erreurs liées aux fichiers JSON, il est probable que le script ne les trouve pas.
2. La fonction de leaderboard Cobblemon ne produit que le tableau XLSX. Pour afficher une image dans le jeu, vous devez toujours convertir le tableau en image, puis le télécharger quelque part. N'hésitez pas à me contacter si vous avez besoin d'aide ou de conseils à ce sujet.
3. Ce script n'est pas automatique par défaut ; vous devez l'exécuter manuellement périodiquement pour qu'il fonctionne. Optionnellement, vous pouvez configurer quelque chose sur votre propre machine pour l'exécuter automatiquement.

Forks intéressantes

Les forks de ce projet suivantes peuvent potentiellement vous intéresser :

• floooz/MCStatsCompiler-autoupload Cette fork implémente une fonctionnalité supplémentaire pour les leaderboards Cobblemon, qui consiste à convertir automatiquement les tableaux du fichier output.xlsx en images et à les uploader sur un repo GitHub. Ces images peuvent ensuite être utilisées en jeu avec le projecteur du mod SlideShow par exemple.
• ThibautChoppy/MCStatsCompiler Cette fork fait tourner le script dans un container Docker, et affiche le leaderboard sur une magnifique page web plutôt que dans un fichier XLSX.