MetaStats - Documentation

1. Installation

Requirements:
• Minecraft 1.17 - 1.21
• Spigot/Paper/Purpur
• Java 8 or higher

Steps:
1. Download MetaStats.jar
2. Place in folder
3. Restart server
4. Plugin generates default configuration

2. Configuration

File Location: 3. Language Files

Available Languages:
• - English
• - Portuguese (Brazil)
• - Spanish
• - Italian
• - Russian
• - Chinese

Customization:
Edit language files in to customize all messages, lore formats, and notifications.

4. Commands

Code (Text):

/metastats reload

• Permission: • Description: Reloads configuration and language files
• Usage: Type command in-game or console

5. Permissions

• Description: Access to /metastats reload command
• Default: OP

6. Statistics Tracked

Tools (Pickaxe, Axe, Shovel, Hoe):
• Blocks Mined - Total blocks broken
• Crafter - Player who crafted the item
• Date - When item was created/received

Weapons (Sword, Axe, Trident):
• Damage Dealt - Total damage to entities
• Kills - Total entities killed
• Critical Hits - Number of critical strikes
• Smith - Player who crafted the item
• Date - When item was forged/received

Armor (Helmet, Chestplate, Leggings, Boots):
• Damage Absorbed - Total damage blocked
• Hits Taken - Number of times hit while wearing
• Armorer - Player who crafted the armor
• Date - When armor was crafted/received

Elytra:
• Flight Time - Total time spent flying
• Distance Flown - Total distance in meters
• Crafter - Player who obtained the elytra
• Date - When elytra was received

7. Rarity System

Items automatically upgrade rarity based on usage:

Common (White)
• Starting rarity for all items
• No requirements

Uncommon (Green)
• Requirements vary by item type:
- Tools: 50 blocks mined
- Weapons: 50 damage dealt
- Armor: 50 damage absorbed
- Elytra: 50 seconds flight

Rare (Blue)
• Tools: 200 blocks mined
• Weapons: 200 damage dealt
• Armor: 200 damage absorbed
• Elytra: 200 seconds flight

Epic (Purple)
• Tools: 500 blocks mined
• Weapons: 500 damage dealt
• Armor: 500 damage absorbed
• Elytra: 500 seconds flight

Legendary (Gold)
• Tools: 1000 blocks mined
• Weapons: 1000 damage dealt
• Armor: 1000 damage absorbed
• Elytra: 1000 seconds flight
• Special: Particle effects displayed

8. NBT Data Storage

MetaStats stores all data directly in items using NBT (Named Binary Tag) technology:

Advantages:
• No external database required
• Data travels with the item
• Works with item frames, chests, etc.
• Automatic backup with world save
• No performance impact on large servers

Keys Used:
• • • • • • Plus individual stat keys per item type

9. Notifications

Players receive notifications when items reach new rarity levels:

Notification Types:
• Title message on screen
• Sound effect (configurable)
• Rarity name and color displayed

Example:
When a pickaxe reaches Legendary, player sees:
10. Auto-Save System

Automatic periodic saving ensures no data loss:

How it works:
• Runs every X seconds (configurable)
• Saves all tracked item data
• Updates NBT on held items
• Lightweight async processing

Configuration:
Adjust value based on server needs (higher = less frequent saves).

11. Troubleshooting

Stats not tracking:
• Ensure item was obtained AFTER plugin installation
• Check if item has MetaStats lore
• Verify no conflicting plugins

Language not changing:
• Check in config.yml
• Use correct language code (en, pt_BR, es, it, ru, zh)
• Run Particles not showing:
• Verify in config
• Check client particle settings
• Ensure item reached Legendary rarity

Plugin not loading:
• Check server version (1.17-1.21)
• Verify Java 8+ installed
• Check console for error messages

12. Performance

MetaStats is optimized for performance:

Features:
• Async particle rendering
• Efficient NBT operations
• Minimal event listeners
• No database queries
• Lightweight memory usage

Tested on:
• Servers with 100+ players
• High-rate mining operations
• PvP-heavy environments

13. Compatibility

Works with:
• Custom enchantments
• Item renaming
• Anvil repairs
• Mending enchantment
• Item frames
• Shulker boxes
• Ender chests

Data persists through:
• Player trades
• Item drops
• Chest storage
• Death and respawn
• Server restarts

End of Documentation