StatsWeb

StatsWeb is a lightweight, high-performance Paper/Spigot plugin that automatically analyzes player statistics and achievements on your server and serves them via an embedded, modern web interface.

Built directly on top of JDK's lightweight HTTP server and virtual threads, StatsWeb operates without external web server dependencies or heavy database setups.

---

Features

• Embedded Web Server: Runs out of the box on its own port with zero setup required.
• Real-Time Leaderboards: Dynamic rankings for blocks mined, mob kills, play time, distance traveled, and custom stats.
• Detailed Player Profiles: Comprehensive breakdowns of individual statistics, completed advancements, global rankings, and online status.
• Automatic Data Parsing: Direct inspection of native Minecraft JSON statistics and advancement files.
• High Performance: Asynchronous background file loading and thread management to ensure zero impact on server tick rates (TPS).
• RESTful API: Easily fetch server statistics in JSON format for external dashboards or Discord bots.

---

Commands and Permissions

Commands

Command	Description	Default
/statsweb url	Displays the public web link	All Players
/statsweb refresh	Forces an immediate scan of statistic files	OP / Admin
/statsweb reload	Reloads config.yml and restarts the web server	OP / Admin

Permissions

• statsweb.use - Allows access to /statsweb url
• statsweb.admin - Allows usage of /statsweb refresh and /statsweb reload

---

REST API Endpoints

StatsWeb exposes a simple, read-only REST API for custom integrations:

• GET /api/overview - Server summary, total server-wide stats, featured leaderboards, and online players.
• GET /api/players - List of all tracked players and their key metrics.
• GET /api/player/{name|uuid} - Complete stat breakdown, advancement list, and global rank per stat for a single player.
• GET /api/leaderboard?stat={category/stat}&limit={count} - Global ranking for any specific stat key.
• GET /api/catalog - List of all existing stat categories present in world files.

---

Configuration

The default config.yml allows full customization over server branding, port bindings, scanning intervals, and featured home-page stats:

web:
  bind-address: "0.0.0.0"
  port: 8080
  public-url: "http://localhost:8080"
  cors: false
  update-default-files: true

refresh:
  interval-seconds: 60
  save-online-players: true

display:
  server-name: "Minecraft Server"
  default-leaderboard: "custom/play_time"
  featured-size: 5
  featured:
    - "custom/play_time"
    - "total/mined"
    - "custom/deaths"
    - "custom/mob_kills"

data:
  stats-dir: "auto"
  advancements-dir: "auto"
  min-playtime-minutes: 0
  hide-inactive-days: 0
  exclude-recipe-advancements: true
  ignore-uuids: []

---

Installation

1. Drop StatsWeb.jar into your server's plugins/ directory.
2. Start the server to generate default configuration and web frontend files under plugins/StatsWeb/.
3. Configure web.port and web.public-url in plugins/StatsWeb/config.yml.
4. Open the designated web port in your firewall or host settings if necessary.