# 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/`.