---

EN

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

---

📘 Notes

PlayerStats API was created to display statistics on websites without unnecessary resources or plugins. All data is sourced directly from Minecraft’s vanilla statistics system.

---

RU

PlayerStats API - это лёгкий и стабильный Paper-плагин для Minecraft 1.21.x, который предоставляет доступ к ванильной статистике игроков через удобный HTTP / REST API.

Плагин предназначен для интеграции с внешними сервисами: веб-панелями, дашбордами, аналитическими системами и кастомными фронтендами.

---

✨ Возможности

• 📊 Чтение ванильной статистики игроков из world/stats/*.json
• 🧍 Поддержка онлайн и оффлайн игроков
• 🔍 Получение статистики по UUID или имени игрока
• 📈 Агрегированная ✨дка (время игры, смерти, убийства, дистанция и др.)
• 🌐 Встроенный HTTP-сервер с REST-эндпоинтами
• ⚡ Кэширование данных для высокой производительности
• 🔒 Используется только публичный Bukkit / Paper API (без NMS и CraftBukkit)

---

✅ Совместимость

• Minecraft / Paper: 1.21.x (1.21, 1.21.1 … 1.21.11)
• Java: 21
• Тип сервера: Paper

Плагин собирается против стабильной ветки Paper API 1.21 и не привязан к патч-версиям, что гарантирует работу на всех релизах 1.21.x.

---

⚙️ Конфигурация

StatsPlugin использует простой YAML-конфиг для настройки:

• HTTP-порта
• включения / отключения веб-сервера
• пути к миру, из которого читается статистика

Изменения конфигурации не требуют пересборки плагина.

---

🌐 API Endpoints

Пример базового URL: http://localhost:8080

🔹 Получить список всех игроков

GET /players

Возвращает список игроков с базовой ✨дкой статистики.

---

🔹 Получить ✨дку игрока по имени

GET /players/{playerName}

Пример:

GET /players/Notch

---

🔹 Получить ✨дку игрока по UUID

GET /players/uuid/{uuid}

Пример:

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

---

🔹 Получить полную ванильную статистику

GET /players/{playerName}/stats

Возвращает полный набор статистики, распарсенный из JSON-файлов Minecraft.

---

⚠️ Пути эндпоинтов могут незначительно отличаться в зависимости от версии и конфигурации. Актуальный список всегда следует проверять в README проекта.

---

📦 Установка

1. Скачайте JAR-файл плагина
2. Поместите его в папку plugins/
3. Запустите сервер
4. При необходимости настройте config.yml

---

🔐 Стабильность и безопасность

• Отсутствует использование NMS или CraftBukkit
• Безопасен для обновлений внутри линейки 1.21.x
• Paper API не встраивается в итоговый JAR
• Корректное о✨бождение ресурсов при остановке сервера

---

🧩 Для каких задач подходит

StatsPlugin подойдёт, если вы:

• разрабатываете веб-интерфейс статистики игроков
• собираете и визуализируете аналитику сервера
• хотите получить программный доступ к ванильной статистике
• строите внешний backend вокруг Minecraft-сервера

---

🖼️ Скриншоты и примеры

TODO

---

📘 Примечание

PlayerStats API не создавался для мониторинга статистики примеком на сервере в игре. Он нужен, чтобы без лишних ресурсов и плагинов выводить статистику на веб-сайты. Все данные берутся напрямую из ванильной системы статистики Minecraft.