️ Installation

1. Download the latest goatix-treasures-X.X.X.jar from releases
2. Place the file in your server's plugins folder
3. Restart your server to generate configuration files
4. Configure settings in config.yml as needed
5. Ready! Use /treasures in-game to start

Quick Start Guide

Creating Your First Event

1. Open the GUI: /treasures gui (requires goatix.treasures.admin)
2. Create Event: Click the "Create Event" button
3. Configure:
   
   • Name: "Summer Treasure Hunt"
   • Description: "Find hidden treasures across the land!"
   • Radius: 500-2000 blocks (adjust to your world size)
   • Chests: 25 (good starting amount)
     
4. Add Loot: Click "Manage Loot Pool" and drag items into the interface
5. Activate: Click the "Activate Event" button
6. Announce: Tell your players the treasure hunt has begun!

Managing Active Events

• View Status: All active events show with green status indicators
• Statistics: Click any event to see discovery rates and player activity
• Modify: Edit settings even while events are active
• Cleanup: Deactivate events to remove all chests and holograms

Commands Reference

Command	Permission	Description
/treasures activate <eventid>	goatix.treasures.admin	Activate the event -> all chests will spawn!
/treasures addloot <eventid>	goatix.treasures.admin	Add the item in your hand to the Loot Pool of the event
/treasures deactivate <eventid>	goatix.treasures.admin	Deactivate the event -> all chests will despawn!
/treasures gui	goatix.treasures.admin	Open main management GUI
/treasures help	goatix.treasures.admin	Show command help
/treasures stats	goatix.treasures.admin	Display server-wide statistics
/treasures locations <event>	goatix.treasures.admin	List all chest coordinates for event
/treasures tp <event> <number>	goatix.treasures.admin	Teleport to specific chest
/treasures nearest	goatix.treasures.admin	Teleport to nearest active chest

Permission System

Core Permissions

• goatix.treasures.admin - Full plugin access (default: op)
• goatix.treasures.user - Basic player access (default: true)

Admin Features

• Event Management: Create, edit, delete treasure events
• Loot Configuration: Manage loot pools and item distribution
• Statistics Access: View discovery rates and player analytics
• Teleport Commands: Quick navigation to treasure locations
• System Controls: Activate/deactivate events server-wide

⚙️ Configuration

The plugin features extensive configuration options in config.yml:

Essential Settings
Performance Optimization
Security Features
Player Experience

Discovery Process

1. Exploration: Players explore the world within event radius
2. Visual Cues: Holograms float above chests showing event name and item count
3. Interaction: Right-click chests to access loot
4. Feedback: Sound effects and messages confirm discoveries
5. Statistics: Progress tracking for competitive events

Chest Mechanics

• Automatic Removal: Chests disappear after looting to prevent exploitation
• Unique Loot: Each chest contains different items from the loot pool
• Fair Distribution: Algorithm ensures balanced loot across all chests
• Persistence: Chests survive server restarts until found or event ends

Advanced Features

Multi-World Support

• Per-World Settings: Configure different rules for each world
• World Blacklisting: Disable plugin in specific dimensions
• Cross-World Events: Single events can span multiple worlds

Integration Support

• PlaceholderAPI: Custom placeholders for other plugins
• LuckPerms: Advanced permission integration
• Chat Plugins: Full compatibility with custom chat systems

Developer API

• Event Hooks: Listen for treasure discoveries and event changes
• Custom Loot: Programmatically add items to loot pools
• Statistics API: Access discovery data for external systems

Performance Benchmarks

Tested Configurations

• Small Events: 10-25 chests, 500-1000 radius ⚡ Instant spawning
• Medium Events: 25-50 chests, 1000-3000 radius ⚡ <30 seconds spawning
• Large Events: 50-100 chests, 3000-10000 radius ⚡ <2 minutes spawning

Server Impact

• TPS Protection: Automatic pausing when TPS drops below 18
• Memory Usage: <50MB additional RAM usage per 100 active chests
• CPU Impact: <1% additional CPU usage during spawning
• Network Traffic: Minimal, only hologram updates

Troubleshooting

Common Issues

Q: Chests not spawning at large distances?
A: Ensure chunk-loading is enabled and increase max-attempts in config.

Q: Holograms disappearing after restart?
A: Fixed in v1.2.1+ with entity persistence improvements.

Q: Chat input not working with custom chat plugins?
A: Fixed in v1.2.4+ with enhanced chat system compatibility.

Q: Server lag during chest spawning?
A: Increase spawn-delay-ticks and enable TPS monitoring in config.

Debug Mode
Enable debug: true in config.yml for detailed logging:

• Location finding progress
• Chunk loading status
• Hologram creation details
• Performance metrics

Performance Issues
If experiencing lag:

1. Increase spawn-delay-ticks to 20+
2. Reduce chest-count for testing
3. Enable TPS monitoring
4. Check for conflicting plugins