Skip to content

Statistics.md

Jump to bottom
Fragmer2 edited this page Feb 3, 2026 · 3 revisions

Statistics & Achievements System

Overview

The plugin tracks detailed statistics for each player and includes an achievement system with XP rewards.

Player Statistics

Tracked Stats

Chests Opened

chests-opened:
  total: 47
  common: 25
  rare: 18
  legendary: 4

How it works:

  • Increments when player opens chest
  • Separated by tier
  • Persistent across sessions

Legendary Items Found

legendary-items-found: 3

Counts:

  • Dragon Slayer Sword
  • Master Pickaxe
  • Titan Axe
  • Void Shovel
  • Storm Hammer
  • Guardian Bow
  • Wisdom Book
  • Phoenix Feather
  • Poseidon's Trident

Does NOT count:

  • Items from /getlegendaryitems
  • Summoner Apples

Guardians Killed

guardians-killed: 12

Counts:

  • Any mob spawned as chest guardian
  • Must be killed by player (direct damage)

Summoner Apples Used

summoner-apples-used: 2

Increments when:

  • Player consumes Summoner Apple
  • Chest spawns successfully

Current XP

current-xp: 5500

Gained from:

  • Opening chests (100-500 XP per tier)
  • Unlocking achievements
  • Killing guardians (50 XP each)
  • Using abilities

Viewing Statistics

Command: /mystats

Permission: None (all players)

Output:

━━━━━━━ Your Statistics ━━━━━━━
 Chests Opened: 47
  ├─ Common: 25
  ├─ Rare: 18
  └─ Legendary: 4

 Legendary Items Found: 3
 Guardians Killed: 12
 Summoner Apples Used: 2

 Total XP: 5,500
 Achievements: 8/15 unlocked

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Leaderboard System

Command: /leaderboard

Aliases: /chesttop, /chesttop10
Permission: None

Output:

 Top 10 Chest Hunters 

1.     Player1 - 156 chests
2.    Player2 - 142 chests
3.   Player3 - 98 chests
4.  Player4 - 87 chests
5.  Player5 - 76 chests
6.  Player6 - 65 chests
7.  Player7 - 54 chests
8.  Player8 - 43 chests
9.  Player9 - 32 chests
10. Player10 - 28 chests

Your rank: #4 (87 chests)

Ranking based on: Total chests opened

Achievement System

Overview

Players unlock achievements by completing specific tasks. Each achievement grants XP.

Achievement List

First Chest

Task: Open your first chest
XP Reward: 100
Unlocks: Automatically when opening any chest

achievements:
  first-chest:
    unlocked: true
    unlocked-at: "2026-02-03T15:30:00Z"
    xp-reward: 100

Treasure Hunter

Task: Open 10 chests (any tier)
XP Reward: 500
Requirement: 10 total chests

Rare Collector

Task: Open 5 Rare chests
XP Reward: 300
Requirement: 5 rare chests

Chest Master

Task: Open 50 chests (any tier)
XP Reward: 1000
Requirement: 50 total chests

Legendary Finder

Task: Open your first Legendary chest
XP Reward: 2000
Requirement: 1 legendary chest

Legendary Collector

Task: Find 5 different legendary items
XP Reward: 3000
Requirement: 5 unique legendary items

Guardian Slayer

Task: Kill 10 guardians
XP Reward: 1500
Requirement: 10 guardian kills

Guardian Destroyer

Task: Kill 50 guardians
XP Reward: 5000
Requirement: 50 guardian kills

Apple Enthusiast

Task: Use 3 Summoner Apples
XP Reward: 800
Requirement: 3 apples consumed

Century Club

Task: Open 100 chests
XP Reward: 10000
Requirement: 100 total chests

Legendary Hunter

Task: Open 10 Legendary chests
XP Reward: 15000
Requirement: 10 legendary chests

Item Collector

Task: Find all 9 legendary items
XP Reward: 20000
Requirement: All legendary items found

Speed Runner

Task: Open a chest within 30 seconds of spawn
XP Reward: 5000
Special: Requires being online when chest spawns

Completionist

Task: Unlock all other achievements
XP Reward: 50000
Special: Meta-achievement

Perfect Week

Task: Open at least 1 chest every day for 7 days
XP Reward: 10000
Special: Streak-based

Achievement Notifications

When unlocking achievement:

Chat message:

━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Achievement Unlocked! 🎉
⭐ Chest Master
Open 50 chests
+1000 XP
━━━━━━━━━━━━━━━━━━━━━━━━━

Title notification:

🎉 Achievement!
⭐ Chest Master

Broadcast (if enabled):

🎉 Player1 unlocked achievement: Chest Master!

Sound: Level up sound + firework effects

XP System

XP Sources

Action XP Reward
Open Common Chest 100 XP
Open Rare Chest 300 XP
Open Legendary Chest 500 XP
Kill Guardian 50 XP
Use Summoner Apple 200 XP
Unlock Achievement Varies

XP Calculation

Example progression:

Player opens:
- 10 Common chests = 1,000 XP
- 5 Rare chests = 1,500 XP
- 2 Legendary chests = 1,000 XP
- Kills 8 guardians = 400 XP

Unlocks:
- First Chest = 100 XP
- Treasure Hunter = 500 XP
- Rare Collector = 300 XP
- Guardian Slayer = 1,500 XP

Total XP: 6,300 XP

Statistics File Format

Location

/plugins/SpawnChestPlugin/statistics.yml

Structure

players:
  uuid-here:
    name: "Player1"
    chests-opened:
      total: 47
      common: 25
      rare: 18
      legendary: 4
    legendary-items-found: 3
    guardians-killed: 12
    summoner-apples-used: 2
    current-xp: 5500
    
    achievements:
      first-chest:
        unlocked: true
        unlocked-at: "2026-02-03T15:30:00Z"
        xp-reward: 100
      
      treasure-hunter:
        unlocked: true
        unlocked-at: "2026-02-03T16:45:00Z"
        xp-reward: 500
      
      # ... other achievements
    
    last-seen: "2026-02-03T20:00:00Z"
    
  another-uuid:
    # ... another player

Admin Commands

View Player Stats

/chestconfig get statistics.players.<uuid>

Reset Player Stats

Manual method:

  1. Stop server
  2. Edit statistics.yml
  3. Remove player entry
  4. Start server

No command yet - feature request!

Statistics Features

Auto-Save

  • Statistics save every 5 minutes
  • Save on player logout
  • Save on server shutdown

Persistence

  • UUID-based (survives name changes)
  • Cross-session tracking
  • Backup on save

Thread-Safe

  • Async database operations
  • No lag from stat updates
  • Queue system for high-load

Configuring Statistics

Enable/Disable System

statistics:
  enabled: true

Command: /togglefeature statistics

When disabled:

  • Stats don't increment
  • Achievements don't unlock
  • /mystats shows "disabled"
  • Existing stats preserved

Achievement Settings

statistics:
  achievements:
    enabled: true
    
    list:
      first-chest:
        xp-reward: 100
      
      treasure-hunter:
        xp-reward: 500
      
      # ... configure each

Modify XP rewards:

first-chest:
  xp-reward: 250  # Increased from 100

Broadcast Settings

features:
  broadcasts:
    achievement-announcement: true

When true:

  • Server sees when players unlock achievements

When false:

  • Only player sees notification

Statistics Events (For Developers)

PlayerOpenChestEvent

@EventHandler
public void onChestOpen(PlayerOpenChestEvent event) {
    Player player = event.getPlayer();
    String tier = event.getTier();
    // Custom logic here
}

AchievementUnlockEvent

@EventHandler
public void onAchievement(AchievementUnlockEvent event) {
    Player player = event.getPlayer();
    String achievement = event.getAchievementId();
    int xp = event.getXPReward();
    // Custom logic here
}

Achievement Progress Tracking

View Progress (Future Feature)

/achievements

 Achievement Progress

 First Chest complete
 Treasure Hunter - 7/10 chests
 Rare Collector complete
 Chest Master - 47/50 chests
 Legendary Finder complete
 Legendary Collector - 3/5 items
 Guardian Slayer complete
 Guardian Destroyer - 12/50 guardians
 Apple Enthusiast - 2/3 apples
 Century Club - 47/100 chests

Progress: 8/15 unlocked (53%)

Leaderboard Types (Future Features)

By Chests Opened

/leaderboard chests

By XP

/leaderboard xp

By Guardians Killed

/leaderboard guardians

By Legendary Items

/leaderboard legendary

Tips for Server Owners

Encourage Participation

  1. Announce top players weekly
  2. Give rewards for leaderboard positions
  3. Host achievement races

Balance XP Rewards

# For competitive servers (high rewards)
treasure-hunter:
  xp-reward: 1000

# For casual servers (normal rewards)
treasure-hunter:
  xp-reward: 500

Achievement Events

"First player to unlock 'Chest Master' 
gets $10,000 in-game currency!"

Privacy & GDPR

Data Stored

  • UUID (required for Minecraft)
  • Username (for display)
  • Statistics (gameplay data)
  • Timestamps

Data Deletion

Players can request deletion:

  1. Stop server
  2. Remove UUID entry from statistics.yml
  3. Start server

Export Data

Admins can export player data:

  1. Open statistics.yml
  2. Find player UUID
  3. Copy section

Troubleshooting

Stats not saving

Check:

  1. statistics.yml file permissions (read/write)
  2. Disk space available
  3. Console for errors

Achievement not unlocking

Check:

  1. Requirements met: /mystats
  2. Achievements enabled in config
  3. Statistics system enabled

Leaderboard empty

Check:

  1. At least 1 player opened chest
  2. Statistics system enabled
  3. File statistics.yml exists

XP not adding

Check:

  1. Statistics enabled
  2. Achievement XP configured
  3. Check /mystats after action

Clone this wiki locally