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

GET /players

Returns a list of players with basic summary statistics.

---

Get player summary by name

GET /players/{playerName}

Example:

GET /players/Notch

---

Get player summary by UUID

GET /players/uuid/{uuid}

Example:

GET /players/uuid/069a79f4-44e9-4726-a5be-fca90e38aaf5

---

Get full raw statistics

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