🍀 LuckBlocksPlus - Advanced Lucky Block Plugin

A lightweight, performance-optimized Lucky Block plugin for Minecraft servers running Paper 1.21+

---

✨ Key Features

🎯 Core Systems

• Weighted Reward Pool - Fully configurable, weighted-random rewards per Lucky Block break
• 14 Action Types - Chain multiple actions per reward, executed in order
• Safe Block Detection - PersistentDataContainer-tagged blocks; ordinary blocks never trigger
• Persistent Tracking - Lucky Block locations survive restarts with O(1) lookups
• Mining Spawn - Lucky Blocks can appear naturally as players mine in selected worlds
• Holograms - Floating text shows everyone what a player just won

🔧 Admin Tools

• In-Game GUI Editor - Create, edit, and delete rewards without touching configs
• Action Editor - Add, edit, reorder, and remove actions per reward
• Set Preview From Cursor - Click with an item to set a reward's preview icon
• Mining Spawn GUI - Toggle and tune natural spawns entirely in-game
• Live Reload - Update configs without restarting

⚡ Performance Optimized

• Async Save System - Non-blocking saves prevent TPS drops
• O(1) HashSet Lookups - Instant Lucky Block verification
• Zero World Scans - Locations are cached, never scanned
• Cached Settings - Hot paths read from memory, not disk
• Graceful Shutdown - Synchronous final save guarantees no data loss

🎁 Flexible Rewards

• Multiple Reward Types: Items, console/player commands, money (Vault compatible)
• Per-Reward Control: Weight, permission, cooldown, enabled state, preview item
• Effects & Spectacle: Titles, sounds, fireworks, explosions, mobs, potions, teleports
• Custom Hook: Fire a CUSTOM_EVENT for other plugins to listen to

🎨 Action Variety

✓ Give Item ✓ Console Command ✓ Player Command

✓ Message ✓ Title ✓ Sound

✓ Explosion ✓ Spawn Mob ✓ Potion Effect

✓ Firework ✓ Random Teleport ✓ Give Money

✓ Custom Event ✓ Hologram

---

📦 Installation

1. Download the latest .jar file
2. Place in your server's plugins folder
3. Restart your server
4. Configure config.yml, rewards.yml, and lang/*.yml
5. Reload with /lb reload

---

🎮 Commands

Player Commands

• /lb or /luckyblocks - Show plugin help
• Break a Lucky Block to roll a reward

Admin Commands

• /lb give <player> [amount] - Give Lucky Block items
• /lb editor - Open the GUI editor
• /lb list - List all rewards
• /lb reload - Reload all configs
• /lb debug - Toggle debug + show tracked block count

---

🔐 Permissions

• luckyblocks.use - Break Lucky Blocks for rewards (default: true)
• luckyblocks.admin - All admin features (default: op)
• luckyblocks.give - Give Lucky Block items (default: op)
• luckyblocks.editor - Open the GUI editor (default: op)
• luckyblocks.reload - Reload configs (default: op)
• luckyblocks.debug - Debug command (default: op)

---

⚙️ Configuration

Clean, documented config files:

• config.yml - Block material, holograms, mining spawn, economy, language
• rewards.yml - Reward definitions, weights, and action lists
• lang/en_US.yml, lang/id_ID.yml - Fully localized text (MiniMessage)

Example Mining Spawn Setup:

mining-spawn:
  enabled: true
  worlds: [world]
  chance: 0.01
  trigger-blocks: [STONE, DEEPSLATE]
  min-y: -64
  max-y: 320

---

🤝 Compatibility

• Minecraft Version: 1.21+ (Paper)
• Java Version: 21+
• Optional Dependencies:
  • Vault (economy / money rewards)

---

📊 Performance Stats

• ✅ Scales to thousands of Lucky Blocks with O(1) lookups
• ✅ Async, non-blocking saves — zero TPS impact
• ✅ No world scanning at any point
• ✅ Non-persistent holograms — no ghost entities after restarts
• ✅ Cached settings keep the break hot-path lightweight

---

🐛 Support & Feedback

Found a bug or have a suggestion? Please report issues with:

• Server version (e.g., Paper 1.21)
• Plugin version
• Steps to reproduce
• Console errors (if any)

---

Made with ❤️ by ResistanceCore If you enjoy this plugin, please leave a ❤️ love and share with other server owners!