AirdropPlugin Documentation
️ System Requirements
Minecraft Server

• Version: Paper/Spigot 1.20.1 or higher
• Java: JDK 17 or higher
• RAM: Minimum 2GB allocated to server
• Players: Optimized for 5-100+ concurrent players

Optional Dependencies

• DecentHolograms (v2.8.6+): Enhanced visual effects
• PlaceholderAPI (v2.11.5+): Advanced integration support
• NBT-API (v2.12.2+): Required by DecentHolograms

Installation Guide
Step 1: Download & Install

1. Download AirdropPlugin-1.0.0.jar
2. Place in your server's plugins/ folder
3. Restart your server (not reload!)

Step 2: Initial Configuration
# First run generates default files:
plugins/AirdropPlugin/
├── config.yml # Main configuration
├── messages.yml # All text messages
└── data/ # Local storage folder
├── data.json
├── unlocked_airdrops.json
└── backups/

Step 3: Database Setup (Optional)
For MySQL storage, create a database:

CREATE DATABASE airdrop_plugin;
CREATE USER 'airdrop_user'@'%' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON airdrop_plugin.* TO 'airdrop_user'@'%';
FLUSH PRIVILEGES;

Step 4: Configure Settings
Edit plugins/AirdropPlugin/config.yml:

system:
enabled: true
language: "en"
storage:
type: "local" # or "mysql"

airdrop:
spawn-interval-minutes: 60
world: "world"
min-players-required: 5 # Adjust for your server

Step 5: Verify Installation

1. Start server and check console for success messages
2. Run /airdrop info in-game
3. Test admin commands: /airdropadmin

⚙️ Configuration
Main Config (config.yml)
System Settings
system:
enabled: true # Master switch
language: "en" # Message language
storage:
type: "local" # "local" or "mysql"
mysql: # MySQL settings
host: "localhost"
port: 3306
database: "airdrop_plugin"
username: "root"
password: "password"
max-connections: 10
local: # Local storage settings
data-directory: "data"
auto-save-interval: 5
keep-backups: true
max-backup-files: 5

Airdrop Settings
airdrop:
spawn-interval-minutes: 60 # Auto-spawn frequency
lifetime-minutes: 40 # How long airdrops last
world: "world" # Target world
announce-before-minutes: 60 # Announcement timing
drop-height: 300 # Drop altitude
max-active: 3 # Concurrent limit
min-players-required: 5 # Minimum online players

notifications: # Player notification types
titles: true
chat: true
actionbar: true
bossbar: true

War Zone Settings
warzone:
radius: 35 # Zone size in blocks
mobs-can-exit: false # Containment setting
warning-interval-seconds: 30 # Warning frequency

effects:
border-particles: true # Visual borders
warning-sounds: true # Audio warnings

Mob Configuration
mobs:
base-count-single-player: 5 # Base mob count
count-two-players: 8 # For 2 players
additional-per-player-after-two: 2 # Scaling factor
max-count: 25 # Hard limit

types: # Mob spawn chances (%)
ZOMBIE: 25
VINDICATOR: 30
SKELETON: 20
CREEPER: 1 # Low chance - dangerous
SPIDER: 10
WITCH: 8
PILLAGER: 15
ZOMBIE_VILLAGER: 3

boss-chance: 60 # Boss spawn probability
boss-type: "WITHER_SKELETON" # Boss mob type

Loot System
loot:
items: # Item spawn chances (%)
DIAMOND: 30
EMERALD: 25
IRON_INGOT: 40
GOLD_INGOT: 35
ENCHANTED_GOLDEN_APPLE: 8
NETHERITE_SCRAP: 5
NETHERITE_INGOT: 2
TOTEM_OF_UNDYING: 3
DIAMOND_SWORD: 15
DIAMOND_PICKAXE: 12
DIAMOND_ARMOR: 10
ENCHANTED_BOOK: 20
ENDER_PEARL: 25
BLAZE_ROD: 18
GHAST_TEAR: 8
NETHER_STAR: 1

min-items: 8 # Minimum loot count
max-items: 18 # Maximum loot count
enchant-chance: 60 # Enchantment probability

Messages (messages.yml)
All user-facing text is customizable:

airdrop:
announcement:
title: "§6§l✈ AIRDROP INCOMING ✈"
subtitle: "§e{time} minutes until drop!"
chat:
- "§6§l ✈ AIRDROP INCOMING ✈"
- "§e§l⏰ Time: §f{time} minutes until drop!"
- "§e§l Coordinates: §fX: §a{x} §f, Z: §a{z}"

warzone:
enter:
title: "§c§l⚠ WAR ZONE ⚠"
subtitle: "§eYou entered a dangerous area!"
bossbar: "§c§l⚠ WAR ZONE ⚠"

Commands & Permissions
Player Commands
# Basic Information
/airdrop info # Show plugin info
/airdrop list # List active airdrops
/airdrop nearest # Find nearest airdrop
/airdrop help # Show help menu

# Aliases: /ad, /drop

Admin Commands
# Airdrop Management
/airdropadmin spawn [x z y] # Force spawn airdrop
/airdropadmin tp [number] # Teleport to airdrop
/airdropadmin stop [number] # Stop specific/all airdrops
/airdropadmin reload # Reload configuration
/airdropadmin gui # Open admin GUI
/airdropadmin info [detail] # System information

# Debug & AI
/airdropadmin debug <on|off|info> # Toggle debug mode
/airdropadmin ai <debug|info> [nr] # AI system control

# Aliases: /ada, /dropadmin

System Control Commands
# System Management
/airdropsystem enable # Enable airdrop system
/airdropsystem disable # Disable airdrop system
/airdropsystem status # Show system status

# Storage Management
/airdropsystem storage info # Storage information
/airdropsystem storage switch <type> # Switch storage type
/airdropsystem storage test # Test connection
/airdropsystem storage backup # Create backup

# Settings Management
/airdropsystem settings view # View current settings
/airdropsystem settings set <key> <value> # Change setting
/airdropsystem settings reset <key> # Reset to default

# Aliases: /adsystem, /dropsystem

Permission Nodes
# Basic Permissions
airdrop.use: true # Basic plugin usage
airdrop.admin: op # Admin commands
airdrop.system: op # System control

# Specific Admin Permissions
airdrop.spawn: op # Force spawn airdrops
airdrop.teleport: op # Teleport to airdrops
airdrop.stop: op # Stop airdrops
airdrop.reload: op # Reload plugin
airdrop.gui: op # Use admin GUI

# System Control Permissions
airdrop.system.enable: op # Enable/disable system
airdrop.system.storage: op # Storage management
airdrop.system.settings: op # Settings management

# Master Permission
airdrop.*: false # All permissions

Storage Systems
Local File Storage
Advantages:

• No external dependencies
• Fast read/write operations
• Automatic JSON formatting
• Built-in backup system

Configuration:

system:
storage:
type: "local"
local:
data-directory: "data"
auto-save-interval: 5 # Minutes
keep-backups: true
max-backup-files: 5

File Structure:

plugins/AirdropPlugin/data/
├── data.json # General plugin data
├── unlocked_airdrops.json # Unlocked airdrop IDs
└── backups/ # Automatic backups
├── backup_2024-01-01_12-00-00/
│ ├── data.json
│ ├── unlocked_airdrops.json
│ └── backup_info.json
└── backup_2024-01-01_18-00-00/

MySQL Database Storage
Advantages:

• Centralized data management
• Better for multi-server setups
• Professional backup solutions
• Query capabilities

Configuration:

system:
storage:
type: "mysql"
mysql:
host: "localhost"
port: 3306
database: "airdrop_plugin"
username: "airdrop_user"
password: "secure_password"
max-connections: 10
connection-timeout: 30000

Database Schema:

-- General data storage
CREATE TABLE airdrop_data (
data_key VARCHAR(255) PRIMARY KEY,
data_value TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Unlocked airdrops tracking
CREATE TABLE airdrop_unlocked (
airdrop_id VARCHAR(255) PRIMARY KEY,
unlocked_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
player_uuid VARCHAR(36),
player_name VARCHAR(16)
);

Storage Migration
Switch between storage types seamlessly:

# Command-based migration
/airdropsystem storage switch mysql
/airdropsystem storage switch local

# Data is automatically transferred
# Original data is preserved as backup

Developer API
Plugin Integration
// Get plugin instance
AirdropPlugin plugin = (AirdropPlugin) Bukkit.getPluginManager().getPlugin("AirdropPlugin");

// Access managers
AirdropManager airdropManager = plugin.getAirdropManager();
StorageManager storageManager = plugin.getStorageManager();

Events (Custom Events)
// Listen for airdrop events
@EventHandler
public void onAirdropDrop(AirdropDropEvent event) {
Airdrop airdrop = event.getAirdrop();
Location location = airdrop.getChestLocation();
// Custom logic here
}

@EventHandler
public void onAirdropClaim(AirdropClaimEvent event) {
Player player = event.getPlayer();
Airdrop airdrop = event.getAirdrop();
// Reward processing
}

Storage API
// Access storage system
StorageProvider storage = plugin.getStorageManager();

// Async operations
storage.saveData("custom_key", "custom_value")
.thenRun(() -> {
// Completion callback
});

storage.loadData("custom_key")
.thenAccept(value -> {
// Process loaded data
});

Configuration API
// Dynamic configuration changes
plugin.getConfig().set("airdrop.spawn-interval-minutes", 30);
plugin.saveConfig();
plugin.reloadPlugin(); // Apply changes

Troubleshooting
Common Issues
1. Airdrops Not Spawning
Symptoms: No automatic airdrops appear Solutions:

# Check system status
/airdropsystem status

# Verify configuration
/airdrop info

# Check player count requirement
# Default requires 30 players - adjust in config:
airdrop:
min-players-required: 5 # Lower for testing

2. Database Connection Issues
Symptoms: MySQL errors in console Solutions:

# Verify MySQL configuration
system:
storage:
mysql:
host: "correct_host"
port: 3306
database: "existing_database"
username: "valid_user"
password: "correct_password"

# Test connection
/airdropsystem storage test

# Switch to local storage temporarily
/airdropsystem storage switch local

3. Mob AI Problems
Symptoms: Mobs escaping war zones or not attacking Solutions:

# Enable debug mode
/airdropadmin debug on

# Check AI status
/airdropadmin ai info

# Verify mob configuration
warzone:
mobs-can-exit: false # Ensure containment

4. Permission Errors
Symptoms: "No permission" messages Solutions:

# Grant basic permissions
permissions:
airdrop.use: true # For all players
airdrop.admin: op # For administrators

# Or use permission plugin:
- airdrop.* # Full access

5. Storage Migration Issues
Symptoms: Data loss during storage switch Solutions:

# Create backup before migration
/airdropsystem storage backup

# Verify current storage type
/airdropsystem status

# Manual file backup
cp -r plugins/AirdropPlugin/data plugins/AirdropPlugin/data_backup

Debug Mode
Enable comprehensive logging:

debug:
enabled: true
show-coordinates: true
show-mob-spawning: true
show-hacking: true
show-animations: true
log-storage: true

Performance Optimization
# Reduce resource usage
airdrop:
max-active: 2 # Fewer concurrent airdrops

mobs:
max-count: 15 # Fewer mobs per airdrop

effects:
particles:
drop: "EXPLOSION_NORMAL" # Less intensive particles

holograms:
enabled: false # Disable if not needed

Log Analysis
Monitor these log patterns:

[AirdropPlugin] Plugin successfully enabled! # Successful startup
[StorageManager] Storage system initialized # Storage working
[AirdropManager] Airdrop successfully created # Normal operation
[DEBUG] Player movement detected # Debug information
ERROR: Failed to connect to database # Issues to investigate

Support & Resources
Documentation Updates

• Contact discord for help - kristalijonas
• Review changelog for new features
• Update configuration files as needed

Performance Monitoring
# Monitor server performance
/airdropadmin info detail # Detailed statistics
/airdropsystem status # System health check
/timings report # Server timing analysis

Backup Strategy
# Regular backup commands
/airdropsystem storage backup
# Automated daily backup via cron/task scheduler
# Keep multiple backup versions
# Test restore procedures regularly

This documentation covers all essential aspects of the AirdropPlugin. For additional support or feature requests, refer to the plugin's GitHub repository or contact the development team.