MCStat-Plugin

# MCStat - Minecraft Server Analytics Plugin MCStat connects your Minecraft server or proxy to **MCStat.org** with secure, signed HTTPS telemetry. It gives server owners more accurate analytics than public ping data alone: live player counts, player sessions, tracked playtime, uptime, TPS where supported, join/leave events, and dashboard-ready server activity. ## Supported Platforms MCStat provides separate jars for each platform family: - **Bukkit / Spigot / Paper / Purpur / Pufferfish / Folia** - **Velocity 3.x** - **BungeeCord / Waterfall** - Bukkit-compatible hybrid servers such as **Mohist, Arclight, Magma, CatServer** Pure Fabric, Forge, NeoForge, Quilt, or Sponge servers need a native adapter unless they run a Bukkit-compatible layer. ## Features - Live online player count and max player count - Signed server heartbeats - Player UUID and player name tracking - Join and leave event tracking - Session start time and total playtime tracking - TPS reporting on Bukkit-family servers - Proxy support for Velocity and BungeeCord networks - Retry queue for temporary network/API outages - `/vote` command with MCStat server vote link - Safe update checks through GitHub Releases - No chat, inventory, private command, world data, or player IP collection ## Privacy MCStat only sends operational telemetry needed for server analytics and public status pages. The plugin does **not** collect: - Chat messages - Private commands - Inventories - World data - Player IP addresses Telemetry is sent to `https://mcstat.org` over HTTPS using your server API key and local installation ID. ## Installation 1. Download the jar matching your platform. 2. Put the jar in your server or proxy `/plugins` folder. 3. Restart the server or proxy. 4. Open the generated MCStat config file. 5. Paste your server API key from the MCStat dashboard. 6. Run `/mcstat reload`. 7. Verify the connection with `/mcstat status`. ## Configuration Example Bukkit/Spigot/Paper config: ```yaml api-key: "YOUR_API_KEY_HERE" api-base-url: "https://mcstat.org" sync-interval: 90 metrics: tps: true player-count: true player-names: true player-playtime: true player-events: true updates: check: true notify-admins: true auto-download: false check-interval-hours: 24 ``` ## Config Reference | Key | Description | | --- | --- | | `api-key` | Server API key generated from the MCStat dashboard. | | `api-base-url` | MCStat API host. Keep as `https://mcstat.org` unless instructed otherwise. | | `sync-interval` | Heartbeat interval in seconds. Minimum is 10. | | `metrics.tps` | Sends TPS on Bukkit-family servers. Ignored by proxies. | | `metrics.player-playtime` | Tracks player sessions and playtime locally. | | `metrics.player-events` | Sends join and leave events when enabled. | | `updates.check` | Checks GitHub Releases for newer plugin versions. | | `updates.notify-admins` | Logs one warning when a newer version is available. | | `updates.auto-download` | Optional. Downloads the new jar into the local updates folder. Does not replace the running jar. | | `updates.check-interval-hours` | Update check interval in hours. Minimum is 1. | ## Commands | Command | Description | | --- | --- | | `/mcstat status` | Shows API connection, queue size, tracked players, uptime, version, and update status. | | `/mcstat reload` | Reloads config, validates the API key, and restarts heartbeat scheduling. | | `/mcstat link` | Shows masked API key info and dashboard link. | | `/mcstat update` | Checks whether a newer plugin version is available. | | `/mcstat update download` | Downloads the matching platform jar into the safe updates folder. | | `/vote` | Shows the public MCStat vote link for the connected server. | ## Safe Updates MCStat can check for updates automatically through official GitHub Releases. By default: ```yaml updates: check: true notify-admins: true auto-download: false ``` The plugin **never hot-swaps or replaces a running jar**. If download is enabled or `/mcstat update download` is used, the new jar is staged in the plugin data folder under `updates/`. To install a downloaded update: 1. Stop the server or proxy. 2. Replace the old MCStat jar in `/plugins`. 3. Start the server or proxy again. This avoids classloader issues, broken reloads, and partial update corruption. ## What MCStat Sends When enabled, MCStat sends: - Server name and version - Online player count - Max player count - Uptime - Timestamp - TPS on Bukkit-family servers - Player UUIDs and names - Session start times - Tracked playtime - Join and leave events Requests are signed with the server API key and installation ID. ## Troubleshooting ### `/mcstat status` says API key is invalid Create a new server API key in the MCStat dashboard, paste it into the config, then run `/mcstat reload`. ### Dashboard is not updating Check: - The server can reach `https://mcstat.org` - The API key belongs to the correct server - `/mcstat status` shows the API as connected - Firewall or hosting panel is not blocking outbound HTTPS ### TPS is missing on Velocity or BungeeCord This is expected. Proxies do not expose a Minecraft game tick loop. TPS is only sent by Bukkit-family server jars. ### Player events look duplicated Install MCStat at the layer you want to measure: - Use the proxy jar for network-wide session tracking. - Use the Bukkit jar on backend servers for per-server analytics. Avoid tracking the same player flow twice unless that is intentional. ## Downloads Official downloads and documentation: - Website: https://mcstat.org/plugin - GitHub: https://github.com/mcstatorg/MCStat-Plugin - Latest release: https://github.com/mcstatorg/MCStat-Plugin/releases/latest ## License MIT