PlayerStats API

StatsPlugin 1.21.x - Release 1.6

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

• Paper / Minecraft: 1.21.x (1.21, 1.21.1 … 1.21.11)
• Java: 21
• API: Paper API 1.21 (no patch-specific binding / без привязки к патч-версиям)

---

✨ What’s changed / Что изменилось

• Added pagination support for /moss/players with limit and offset parameters. Добавлена поддержка пагинации для /moss/players с параметрами limit и offset.

  • Returns metadata envelope: total, limit, offset, players. Возвращает метаданные: total, limit, offset, players.
  • Deterministic UUID sorting preserved. Сохраняется детерминированная сортировка по UUID.

• Implemented safe pagination parsing: Реализована безопасная обработка пагинации:

  • limit defaults to existing behavior (maxResponsePlayers). limit по умолчанию = maxResponsePlayers.
  • Negative limit → clamped to 0; oversized limit → clamped to max. Отрицательные значения → 0; слишком большие → до максимума.
  • offset defaults to 0; negative values clamped to 0. offset по умолчанию = 0; отрицательные значения → 0.

• Extended /moss/top/<stat_key> to support explicit section selection. Добавлена поддержка явного указания секции для /moss/top/<stat_key>.

  • Query param form: /moss/top/<stat_key>?section=<section>
  • Path variant: /moss/top/<section>/<stat_key>
  • Legacy behavior preserved when section is not provided. Старое поведение сохраняется, если секция не указана.

• Implemented strict section-based lookup & validation: Реализован строгий поиск по секции и валидация:

  • Dynamic section discovery from loaded stats. Динамическое определение доступных секций.
  • 400 response for invalid section. 400 при некорректной секции.
  • 404 if stat key is absent in the specified section. 404, если stat_key отсутствует в указанной секции.
  • No fallback when section is explicitly provided. Без fallback при явном указании секции.

---

🔧 Improvements / Улучшения

• Added reusable StatsUtil helper methods:

  • getStatInSection
  • sectionHasStatKey
  • getAvailableStatSections

  Добавлены вспомогательные методы StatsUtil для устранения дублирования логики и поддержки динамического поиска по секциям.

• Improved backward compatibility - existing clients continue working without changes. Улучшена обратная совместимость - существующие клиенты работают без изменений.

• Minor internal refactoring and safety checks (no breaking API changes). Небольшой рефакторинг и дополнительные проверки безопасности (без ломающих изменений API).

---

📦 Build details / Информация о сборке

• Single universal JAR: statsplugin-1.21.x-1.6.jar Универсальный JAR: statsplugin-1.21.x-1.6.jar
• Built with Java 21 Сборка выполнена под Java 21
• Maven-based build (mvn clean package) Maven-билд (mvn clean package)

---

⚠️ Notes / Примечания

• Pagination significantly improves performance for large servers and makes the API UI-friendly for dashboards and web panels. Пагинация значительно улучшает работу на больших серверах и делает API удобным для веб-интерфейсов.

• Explicit section selection resolves stat key ambiguity (e.g., mined vs used) and enables entity kill leaderboards. Явное указание секции решает проблему неоднозначных stat_key и позволяет строить топы по убийствам мобов.

• Fully backward compatible with previous 1.21.x releases. Полностью совместим с предыдущими релизами 1.21.x.

---

📌 Upgrade / Обновление

• Replace the old JAR in your plugins/ folder and restart the server. Замените старый JAR в папке plugins/ и перезапустите сервер.