159 lines
4.1 KiB
Markdown
159 lines
4.1 KiB
Markdown
# 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/`.
|