# XiyusLootBox


## Project Overview

**XiyusLootBox** is an advanced lottery system plugin developed for Minecraft Spigot servers. It provides a CSGO-style loot box experience with animated lottery features, supporting custom loot pools, item wear levels, probability weighting systems, and many other advanced functionalities.


## ⭐ Core Highlights

### Immersive Loot Experience
- **Smooth Animations**: Simulates a real spinning wheel, from fast scrolling to slow stopping
- **9-Slot Interface Design**: Clean and intuitive lottery interface
- **Instant Feedback**: Displays results immediately after the animation ends

### CSGO-Style System
- **5 Wear Levels**: Factory New → Battle-Scarred
- **Dynamic Durability**: Automatically adjusts item durability based on wear levels
- **Rarity Colors**: Different colors for different rarity tiers

### Flexible Probability System
- **Weighted Distribution**: Supports precise decimal probability control
- **JSON Configuration**: Easy to edit and manage
- **Real-Time Calculation**: Dynamic probability wheel selection algorithm

### ️ Admin-Friendly Tools
- **Visual Editor**: GUI interface for managing loot pools
- **Drag-and-Drop**: Intuitive item addition/removal
- **Real-Time Preview**: View loot pool statistics


## ️ Technical Architecture

### Modular Design
```
Core Modules
├── Loot System (loot)
├── Animation Engine (animations)
├── ️ GUI Interface (gui)
├── ⚙️ Configuration Manager (config)
├── Utilities (utils)
├── Item Management (items)
├── Command System (commands)
└── Event Handling (events)
```

### Key Technical Features
- **NBT Data Storage**: Identifies loot bag items via NBT tags
- **Asynchronous Task Handling**: Animations run without blocking the main thread
- **Memory Optimization**: Smart animation task management
- **Type Safety**: Full generic type support
- **Exception Handling**: Comprehensive error management


## Features

### Player Functions
- ✅ Right-click loot bags to start looting
- ✅ Watch beautiful scrolling animations
- ✅ Obtain items with wear-level attributes
- ✅ View loot history

### Admin Functions
- ✅ Create/delete loot pools
- ✅ Visual editing of loot pool contents
- ✅ Adjust item probability weights
- ✅ Batch distribute loot bags
- ✅ Monitor loot statistics

### Advanced Configuration
- ✅ Customizable animation duration
- ✅ Adjust rarity thresholds
- ✅ Configure broadcast rules
- ✅ Set permission levels
- ✅ Multi-language localization


## Performance Data

### Optimization Features
- **Memory Usage**: < 5MB runtime memory
- **CPU Usage**: < 1% during animations
- **Response Time**: < 50ms operation response
- **Concurrency Support**: Handles multiple players looting simultaneously

### Compatibility
- **Minecraft Versions**: 1.13 - 1.20+
- **Server Types**: Spigot/Paper/Purpur
- **Java Version**: 8+ (Recommended 11+)
- **Dependencies**: No mandatory dependencies


## Use Cases

### Server Events
- Festival celebration lotteries
- Sign-in reward systems
- Quest completion rewards
- Leaderboard prizes

### ⚔️ Gameplay
- PVP loot crates
- Dungeon clearance rewards
- Store lottery items
- VIP exclusive packages

### Economy System
- Paid loot boxes
- Point redemption rewards
- Limited-time promotions
- Membership福利系统 (Membership benefit system)


## ️ Security Features

### Data Security
- **Configuration Backup**: Automatic backups of critical configs
- **Data Validation**: Input integrity checks
- **Permission Control**: Fine-grained permission management
- **Logging**: Detailed operation logs

### Anti-Cheat Mechanisms
- **NBT Validation**: Prevents forged loot bags
- **Probability Verification**: Ensures fairness
- **Cooldown System**: Prevents spam operations
- **Permission Checks**: Rigorous access validation


## Statistics Functions

### Data Collection
- Loot count statistics
- Item drop records
- Player usage analysis
- Probability distribution verification

### Report Generation
- Daily loot reports
- Popular item statistics
- Player activity analysis
- Revenue data tracking


## Technical Highlights

### Code Quality
- **Design Patterns**: Singleton, Factory, Observer patterns
- **Code Standards**: Complete JavaDoc documentation
- **Error Handling**: Robust exception management
- **Performance Optimization**: Efficient algorithm implementations

### Extensibility
- **Modular Architecture**: Loosely coupled module design
- **Plugin Compatibility**: Supports integration with other plugins
- **Open API**: Provides developer APIs
- **Flexible Configuration**: Highly customizable settings


---

## Quick Start

### One-Click Installation
1. Download `xiyusLootBox-1.0.jar`
2. Place in `plugins/` directory
3. Restart the server
4. Run `/lootbag give <player> default 1`
5. Right-click the loot bag to start looting!

### Configuration Example
```bash
# Create a new loot pool
/lootpool create epic_weapons

# Edit a loot pool
/lootpool edit epic_weapons

# Give to all online players
/lootbag give @a epic_weapons 1
```

**Experience XiyusLootBox today and bring new loot fun to your server!**