feat: add comprehensive player statistics logging

README.md

@@ -0,0 +1,158 @@
+# 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:
+
+```text
+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:
+
+```yaml
+storage:
+  type: flatfile
+```
+
+Player counters are stored under:
+
+```text
+plugins/RosePlayerStats/players/<uuid>.properties
+```
+
+Each file includes both:
+
+```text
+meta.uuid=<uuid>
+meta.last_name=<player name>
+```
+
+### MySQL / MariaDB
+
+Set:
+
+```yaml
+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
+
+```text
+/playerstats
+/playerstats <player|uuid>
+/playerstats save
+/playerstats reload
+```
+
+Aliases:
+
+```text
+/pstats
+/stats
+```
+
+The stats display always includes both the player's current/last known name and UUID.
+
+## Permissions
+
+```text
+roseplayerstats.view
+roseplayerstats.view.others
+roseplayerstats.admin
+```
+
+`roseplayerstats.view` defaults to everyone. The others default to operators.
+
+## Build
+
+The Gradle wrapper is included.
+
+Windows:
+
+```text
+gradlew.bat clean build
+```
+
+Linux/macOS:
+
+```text
+./gradlew clean build
+```
+
+The output JAR is written to `build/libs/`.