Shell Block Hunt v1.0

---

What is Shell Block Hunt?

Shell Block Hunt transforms your server into an ongoing treasure hunt. At a configurable interval (default: every hour), decorative shell blocks automatically spawn across your world. Players race to find them, collect them as stackable items, and redeem them for prizes whenever they want — just like crate keys, but earned through exploration.

Whether you run a survival server, an RPG, or an economy-driven experience, this plugin adds a layer of excitement that keeps players online and engaged.

---

Features

Core mechanics

• Automatic timed events — Shells spawn at your chosen interval (e.g. every 60 minutes) without any admin input.
• Two spawn modes — Random exploration-based spawning OR fixed coordinates for curated event locations.
• Item-based collection — Shells drop as stackable items (up to 64). Players collect now, redeem later.
• Multi-tier reward system — Define guaranteed rewards plus bonus items with custom chances. Supports items, commands, and economy (Vault/EssentialsX).
• Auto-clear system — Uncollected shells are removed before the next wave, keeping your world tidy.

Player engagement

• Leaderboards — Competitive rankings visible with /shellhunt top.
• Per-player statistics — Track how many shells each player has collected over time.
• Cooldown system — Configurable per-player cooldowns to balance gameplay and prevent farming.
• Broadcast messages — Server-wide announcements when shells spawn and when they are all collected.
• Particle & sound effects — Immersive feedback when shells are found and opened.

Customization

• Custom head textures — Use any player head texture (minecraft-heads.com compatible).
• Fully configurable lore — The shell item lore auto-generates a list of possible rewards with custom colors and symbols.
• Multi-world support — Define exactly which worlds can receive shells.
• 50+ config options — Messages, intervals, spawn radius, Y-levels, cooldowns, and more.

---

Commands & Permissions

---

Installation

1. Download the JAR and place it in your plugins/ folder.
2. Start or restart the server.
3. Edit plugins/ShellBlockHunt/config.yml to your liking.
4. Run /shellhunt reload — done!

Requirements

• Minecraft 1.21+ (compatible with earlier versions)
• Spigot, Paper, or Purpur
• Java 17+
• Optional: Vault + economy plugin for money rewards

---

Example reward config

---

FAQ

Can shells spawn in multiple worlds?
Yes — just list them in world-list inside config.yml.

Can players save shells to open later?
Absolutely. Shells are inventory items. Players can store them in chests or ender chests and open them whenever they want.

What happens to uncollected shells?
They are automatically removed before the next event spawns (toggleable with auto-clear-shells).

Does it work with my economy plugin?
Yes, as long as you have Vault installed. Command-based rewards support any economy plugin compatible with Vault.

---

Support

Open a conversation here on BuiltByBit or file an issue on GitHub. Please include your server version, plugin version, and console errors when reporting bugs.

---