⚡

MineStat Fabric Mod

Automatic stat uploads with zero manual effort. Play your singleplayer world and your stats stay synced in real time.

Built from source — use the button matching your Minecraft version.

What the Mod Does

⏱️

Live Stat Uploading

Every 15 seconds, the mod flushes your stats to disk and uploads them to your MineStat account. Walk, mine, craft, die — it's all tracked automatically.

🗺️

BlueMap Sync

If you run BlueMap, the mod watches for changed map tiles and uploads them in batches. Your 3D world map stays up to date without manual file transfers.

📡

Smart Differential Sync

Only new or modified stats are sent. The mod tracks file modification times so it never re-uploads unchanged data — efficient even on slower connections.

🔐

API Key Authentication

Generate an API key from your Settings page. The mod includes it in every request — no passwords stored locally, revocable at any time.

💬

In-Game Chat Feedback

On world join you'll see a confirmation message with your configured interval. If something is misconfigured, the mod tells you right in chat.

👋

Final Upload on Leave

When you quit a world, the mod performs one last upload and map sync so nothing is lost between sessions.

How It Works

World join — the mod detects you're in singleplayer and starts a background scheduler.

Each cycle — forces a stat flush via the integrated server, reads saves/<world>/stats/<uuid>.json, and POSTs it to /api/mod/upload with your API key.

BlueMap sync — walks the bluemap/web/ directory, base64-encodes changed files, and sends batches of up to 200 files to /api/mod/map-upload.

World leave — cancels the scheduler and performs a final upload + map sync.

Multiplayer guard — if you join a server, the mod detects it and displays a warning. It never attempts to access stats from remote servers.

Installation

Install Fabric Loader for your Minecraft version.

Download Fabric API and place it in your .minecraft/mods/ folder.

Download the MineStat mod from the button above for your MC version and place the JAR in .minecraft/mods/.

Launch Minecraft. The mod creates a default config at .minecraft/config/minestat.json.

Go to Settings, generate an API key, and paste it into the config file.

Join any singleplayer world — the mod confirms setup in chat and starts uploading.

Configuration

The mod creates .minecraft/config/minestat.json on first launch. Here are all available options:

{
  "serverUrl": "https://minestat.donutsaregreat.com",
  "apiKey": "<paste your API key here>",
  "uploadIntervalSeconds": 15,
  "mapSyncEnabled": true,
  "mapSyncIntervalSeconds": 300
}

serverUrlThe MineStat server to upload to. Leave as default unless self-hosting.

apiKeyYour personal API key from the Settings page. Required for uploads.

uploadIntervalSecondsHow often to upload stats (minimum 1). Default 15 seconds.

mapSyncEnabledSet to false to disable BlueMap sync entirely.

mapSyncIntervalSecondsHow often to check for BlueMap changes (minimum 60). Default 300 (5 minutes).

Requirements

Minecraft

Java Edition 1.20.1 — 1.21.4

Mod Loader

Fabric Loader 0.14+

Fabric API

Latest for your version

Java

Java 17+ (JDK for building)

Platform

Windows, macOS, Linux

World Type

Singleplayer only

Build from Source

The mod ships with a build script that produces JARs for multiple Minecraft versions:

cd minestat-mod
./build-all.sh

Output lands in public/downloads/ as minestat-1.1.3-mc<version>.jar. Requires Java 17+ JDK and an internet connection for Gradle dependencies.