PlayerStats/README.md

RosePlayerStats

RosePlayerStats is a Paper 26.2 player-statistics plugin for The Rose Garden. It records broad player activity using both Minecraft/Paper statistics and additional RosePlayerStats counters, and can optionally maintain a detailed timestamped event journal.

Every stored player record uses the player's UUID as the permanent identity and also stores the player's current/last known player name. If a player changes their Minecraft name, the UUID remains the same and the stored name is updated.

Requirements

• Paper 26.2
• Java 25
• MySQL/MariaDB is optional; the MariaDB JDBC driver is bundled in the plugin JAR.

What is tracked

RosePlayerStats captures Minecraft/Paper statistic increments and adds counters for activity not represented cleanly by vanilla statistics.

Examples include:

• Player name and UUID
• First seen / last seen
• Join count, kicks, session duration, tracked play time
• Total movement distance
• Walking, sprinting, sneaking, swimming, flying, gliding, and vehicle distance
• Estimated number of steps
• Blocks broken, total and by material
• Blocks placed, total and by material
• Bucket fills/empties
• Deaths and death causes
• Kills, total and by entity type
• Damage dealt/taken
• Items picked up, dropped, consumed, broken, damaged, and mended
• Crafting and enchanting
• Inventory opens/closes/clicks
• Block and entity interactions
• Commands, total and by command
• Chat message and character counts
• Advancements
• Teleports and teleport causes
• World changes
• Respawns
• Game-mode changes
• Experience and level changes
• Fishing
• Bed interactions
• Sneak, sprint, flight, and hand-swap controls
• Every additional statistic exposed through PlayerStatisticIncrementEvent

Movement statistics are accumulated in memory because Paper intentionally does not fire PlayerStatisticIncrementEvent for some high-frequency movement statistics. The plugin records movement distance itself and derives an estimated step count from configurable average step length.

Detailed event journal

When journal.enabled: true, meaningful actions are also recorded as timestamped events.

Flat-file mode writes JSON Lines files to:

plugins/RosePlayerStats/events/YYYY-MM-DD.jsonl

SQL mode writes rows to rose_player_events.

Commands can contain passwords or authentication tokens. RosePlayerStats therefore supports a configurable command-redaction list. Matching commands are counted normally, but their arguments are stored as <redacted> in the journal.

Storage

Flat file

Default configuration:

storage:
  type: flatfile

Player counters are stored under:

plugins/RosePlayerStats/players/<uuid>.properties

Each file includes both:

meta.uuid=<uuid>
meta.last_name=<player name>

MySQL / MariaDB

Set:

storage:
  type: mariadb
  sql:
    host: 127.0.0.1
    port: 3306
    database: minecraft
    username: playerstats
    password: change-me
    parameters: 'useUnicode=true&characterEncoding=utf8&useSSL=false'

type: mysql is also accepted. The bundled MariaDB JDBC driver supports both MariaDB and MySQL servers.

RosePlayerStats automatically creates:

• rose_players — UUID, current player name, first seen, last seen
• rose_player_stats — UUID, current player name, stat key, stat value
• rose_player_events — timestamp, UUID, player name, event type, event detail

The counter table is key/value based, so new statistics can be added without a database migration for each new counter.

Commands

/playerstats
/playerstats <player|uuid>
/playerstats save
/playerstats reload

Aliases:

/pstats
/stats

The stats display always includes both the player's current/last known name and UUID.

Permissions

roseplayerstats.view
roseplayerstats.view.others
roseplayerstats.admin

roseplayerstats.view defaults to everyone. The others default to operators.

Build

The Gradle wrapper is included.

Windows:

gradlew.bat clean build

Linux/macOS:

./gradlew clean build

The output JAR is written to build/libs/.