PlayerStats API

**PlayerStats API** is a lightweight and stable **Paper plugin for Minecraft 1.21.x** that exposes **vanilla player statistics** via a simple and efficient **HTTP / REST API**. The plugin is designed for external integrations such as **web dashboards, analytics services, monitoring tools, and custom frontends**. --- ## Features * 📊 Reads vanilla player statistics from `world/stats/*.json` * 🧍 Supports **online and offline** players * 🔍 Fetch statistics by **UUID or player name** * 📈 Provides aggregated summaries (playtime, deaths, kills, distance, etc.) * 🌐 Built-in **HTTP server** with REST endpoints * ⚡ Data caching for improved performance * 🔒 Uses only public **Bukkit / Paper API** (no NMS, no CraftBukkit) --- ## Compatibility * **Minecraft / Paper:** 1.21.x (1.21, 1.21.1 … 1.21.11) * **Java:** 21 * **Server type:** Paper The plugin is built against the **stable Paper API 1.21 branch** and is not tied to patch-specific versions, ensuring compatibility across all 1.21.x releases. --- ## Configuration StatsPlugin uses a simple YAML configuration file to control: * HTTP server port * Enabling / disabling the web server * World path for reading statistics No rebuild is required after configuration changes. --- ## API Endpoints > Base URL example: `http://localhost:8080` ### 🔹 Get all players ```http GET /players ``` Returns a list of players with basic summary statistics. --- ### Get player summary by name ```http GET /players/{playerName} ``` Example: ```http GET /players/Notch ``` --- ### Get player summary by UUID ```http GET /players/uuid/{uuid} ``` Example: ```http GET /players/uuid/069a79f4-44e9-4726-a5be-fca90e38aaf5 ``` --- ### Get full raw statistics ```http GET /players/{playerName}/stats ``` Returns the full vanilla statistics parsed from the `stats` JSON file. --- > Endpoint paths may slightly vary depending on configuration and version. > Always refer to the project README for the most up-to-date list. --- ## Installation 1. Download the plugin JAR file 2. Place it into the `plugins/` folder 3. Start the server 4. Adjust `config.yml` if needed --- ## Stability & Safety * No usage of NMS or CraftBukkit * Safe across all Paper 1.21.x updates * Does not embed Paper API into the final JAR * Proper resource cleanup on server shutdown --- ## Use cases PlayerStats API is suitable if you: * Build a **web-based player statistics dashboard** * Collect and visualize **server analytics** * Need programmatic access to vanilla statistics * Develop external services around your Minecraft server --- ## Screenshots & Examples TODO