# Statistics Export

# Statistics Export

The plugin can export achievement statistics for use with external tools, websites, and analytics systems.

## Overview

When enabled, the plugin periodically exports:
- Global statistics
- Player leaderboards
- Recent achievement unlocks

## Configuration

Enable export in `config.json`:

```json
"export": {
  "enabled": true,
  "intervalSeconds": 300,
  "exportGlobalStats": true,
  "exportLeaderboards": true,
  "exportRecentUnlocks": true,
  "leaderboardSize": 100,
  "recentUnlocksSize": 50,
  "includePlayerTotals": true
}
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable export |
| `intervalSeconds` | number | `300` | Export frequency (5 minutes default; a change applies without restart) |
| `exportGlobalStats` | boolean | `true` | Include global statistics |
| `exportLeaderboards` | boolean | `true` | Include player rankings |
| `exportRecentUnlocks` | boolean | `true` | Include recent unlock history |
| `leaderboardSize` | number | `100` | Number of top players |
| `recentUnlocksSize` | number | `50` | Number of recent unlocks |
| `includePlayerTotals` | boolean | `true` | Include per-player totals |

## Export Location

Statistics are exported to:

```
mods/kyuubisoft_achievements/stats/
├── global_stats.json
├── leaderboards.json
├── recent_unlocks.json
└── server_records.json   (rarity and server firsts used by the book)
```

Since 3.0.0 `recent_unlocks.json` is written in the export run (not on every unlock) and only while `export.enabled` is true. Every run reads each player file once. `activePlayers24h` counts players seen in the last 24 hours, and `includePlayerTotals` is honoured.

## Export Formats

### Global Statistics

`global_stats.json`:

```json
{
  "exportTime": "2024-01-15T10:30:00Z",
  "totalAchievements": 487,
  "totalPlayers": 1250,
  "totalUnlocks": 15847,
  "categoryStats": {
    "combat": {
      "total": 49,
      "unlocked": 3521
    },
    "progression": {
      "total": 102,
      "unlocked": 8234
    },
    "exploration": {
      "total": 32,
      "unlocked": 1892
    },
    "social": {
      "total": 20,
      "unlocked": 1456
    },
    "husbandry": {
      "total": 29,
      "unlocked": 512
    },
    "secret": {
      "total": 37,
      "unlocked": 232
    }
  },
  "popularAchievements": [
    {
      "id": "first_blood",
      "name": "First Blood",
      "unlockCount": 1187
    },
    {
      "id": "miner_1",
      "name": "Novice Miner",
      "unlockCount": 1052
    }
  ],
  "rareAchievements": [
    {
      "id": "playtime_1000h",
      "name": "Millennium Player",
      "unlockCount": 3
    },
    {
      "id": "monster_hunter_5",
      "name": "Monster Slayer",
      "unlockCount": 12
    }
  ]
}
```

### Leaderboard

`leaderboards.json`:

```json
{
  "exportTime": "2024-01-15T10:30:00Z",
  "leaderboard": [
    {
      "rank": 1,
      "playerUuid": "550e8400-e29b-41d4-a716-446655440000",
      "playerName": "TopPlayer",
      "achievementCount": 412,
      "percentage": 84.6,
      "recentUnlock": "monster_hunter_5",
      "titles": ["Monster Slayer", "Veteran", "Explorer"]
    },
    {
      "rank": 2,
      "playerUuid": "550e8400-e29b-41d4-a716-446655440001",
      "playerName": "SecondPlace",
      "achievementCount": 387,
      "percentage": 79.5,
      "recentUnlock": "playtime_500h",
      "titles": ["Time Lord", "Master Miner"]
    }
  ]
}
```

### Recent Unlocks

`recent_unlocks.json`:

```json
{
  "exportTime": "2024-01-15T10:30:00Z",
  "recentUnlocks": [
    {
      "playerUuid": "550e8400-e29b-41d4-a716-446655440000",
      "playerName": "Steve",
      "achievementId": "spider_hunter_3",
      "achievementName": "Spider Hunter III",
      "category": "combat",
      "unlockTime": "2024-01-15T10:28:45Z"
    },
    {
      "playerUuid": "550e8400-e29b-41d4-a716-446655440002",
      "playerName": "Alex",
      "achievementId": "first_blood",
      "achievementName": "First Blood",
      "category": "combat",
      "unlockTime": "2024-01-15T10:27:12Z"
    }
  ]
}
```

## Use Cases

### Website Integration

Display achievement statistics on your server website:

```javascript
// Fetch and display leaderboard
fetch('/api/achievements/leaderboards.json')
  .then(response => response.json())
  .then(data => {
    const leaderboard = data.leaderboard;
    leaderboard.forEach(player => {
      console.log(`#${player.rank} ${player.playerName}: ${player.achievementCount}`);
    });
  });
```

### Discord Bot

Post achievement notifications to Discord:

```javascript
// Watch for new unlocks
const previousUnlocks = loadPreviousUnlocks();
const currentUnlocks = loadCurrentUnlocks();

const newUnlocks = currentUnlocks.filter(u =>
  !previousUnlocks.some(p =>
    p.playerUuid === u.playerUuid && p.achievementId === u.achievementId
  )
);

newUnlocks.forEach(unlock => {
  sendDiscordMessage(`🏆 ${unlock.playerName} unlocked: ${unlock.achievementName}!`);
});
```

### Analytics Dashboard

Track achievement trends over time:

```javascript
// Store daily snapshots
const today = new Date().toISOString().split('T')[0];
const stats = loadGlobalStats();

database.insert({
  date: today,
  totalUnlocks: stats.totalUnlocks,
  totalPlayers: stats.totalPlayers,
  categoryBreakdown: stats.categoryStats
});
```

### Competitive Events

Track event achievement progress:

```javascript
// Filter leaderboard for event achievements
const eventAchievements = ['summer_event_1', 'summer_event_2', 'summer_event_3'];

const eventLeaderboard = players.map(player => ({
  name: player.playerName,
  eventScore: player.achievements.filter(a =>
    eventAchievements.includes(a)
  ).length
})).sort((a, b) => b.eventScore - a.eventScore);
```

## Performance Considerations

### Export Frequency

- Default: 5 minutes (300 seconds)
- Minimum recommended: 60 seconds
- For high-traffic servers: 10+ minutes

### File Size

Approximate sizes:
- `global_stats.json`: ~5-10 KB
- `leaderboards.json` (100 players): ~20-50 KB
- `recent_unlocks.json` (50 unlocks): ~10-20 KB

### Disk I/O

- Files are written atomically (temp file → rename)
- No data loss during crashes
- Consider SSD for frequent exports

## Customization

### Filtering Leaderboard

To exclude certain players (staff, test accounts), implement server-side filtering when reading the export.

### Combining with Other Data

Join achievement data with other server statistics:

```javascript
const achievements = loadLeaderboard();
const playtime = loadPlaytimeStats();
const economy = loadEconomyStats();

const combinedStats = achievements.map(player => ({
  ...player,
  playtime: playtime.find(p => p.uuid === player.playerUuid)?.hours || 0,
  balance: economy.find(p => p.uuid === player.playerUuid)?.balance || 0
}));
```

## Troubleshooting

### Export Not Working

1. Check `export.enabled` is `true`
2. Verify write permissions on export directory
3. Check server logs for errors

### Missing Players

- Only players with at least 1 achievement appear
- Players must have logged in since plugin installation

### Stale Data

- Check `intervalSeconds` setting
- Verify server isn't paused/stopped
- Ensure adequate server resources