# HeadBlocks — The Ultimate Head Hunting Experience Transform your server into an exciting treasure hunt playground `1.20 — 26.1+` | Multi-Server Ready | Fully Translatable | Free & Open Source ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ What is HeadBlocks? ⬥ HeadBlocks lets you hide custom heads across your world and turn them into collectible treasures. Players explore, discover, and compete to find them all. Think of it as easter eggs meets achievement hunting — perfect for keeping your community engaged. Place heads anywhere, organize them into hunts, set up rewards, leaderboards, and watch your players spend hours exploring every corner of your world. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ Key Features ⬥ ⛳ **Multi-Hunt System** Create unlimited independent hunts — each with its own set of heads, rules, and progression. Run a Halloween hunt, a Christmas event, and a permanent exploration challenge, all at the same time. Enable, disable, or archive hunts at any time. ⛺ **Hunt Behaviors** - **Free** — Click heads in any order. Classic treasure hunt. - **Ordered** — Players must find heads in a specific sequence you define. - **Scheduled** — Hunts that activate only during a date range. Perfect for seasonal events. - **Timed** — Speedrun mode! Players race against the clock from a pressure plate. Track best times and display timed leaderboards. ⚡ **Powerful Reward System** Reward players per head with messages, commands, or broadcasts. Set up tiered milestones (e.g. special reward at 10, 50, 100 heads found). Supports inventory slot checks and randomized command execution. ⛑️ **Hint System** Help players find nearby heads with configurable proximity hints: - **Sound hints** — A sound plays when a player is within range - **Action bar hints** — Show distance and direction with a customizable arrow indicator - Configure detection distance, cooldown, and enable/disable hints per head ✨ **Visual Effects** - Holograms above heads (found/not found text) — built-in TextDisplay or advanced mode with PacketEvents - Floating particles above unfound heads (customizable colors) - On click: fireworks, particles, sounds, titles, messages — all configurable - Spin mode — rotating heads for extra visibility - Gradient, rainbow, and solid color text formatting ⚔️ **Progression & Leaderboards** - Per-hunt and global progress tracking - Customizable progress bars - Global and hunt-specific leaderboards (`/hb top`) - Timed hunt best times and rankings - Detailed player stats: found heads, missing heads, completion percentage ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ Multi-Server & Storage ⬥ HeadBlocks is network-ready out of the box: - **SQLite** — Zero config, works instantly - **MySQL / MariaDB** — Centralized database with connection pooling & SSL - **Redis** — Real-time player data synchronization across servers Whether you run a single SMP or a multi-server network, HeadBlocks scales with you. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ Integrations ⬥ - **PlaceholderAPI** — 20+ placeholders for scoreboards, holograms, chat, and more - **HeadDatabase** — Access thousands of head textures with `hdb:` - **PacketEvents** — Advanced holograms with placeholders & client-side head hiding for found heads **Full PlaceholderAPI List** ``` %headblocks_current% — Heads found (total) %headblocks_left% — Heads remaining (total) %headblocks_max% — Total heads %headblocks_hunt__found% — Found in hunt %headblocks_hunt__total% — Total in hunt %headblocks_hunt__left% — Remaining in hunt %headblocks_hunt__progress% — Progress % in hunt %headblocks_hunt__name% — Hunt display name %headblocks_hunt__state% — Hunt state %headblocks_hunt__besttime% — Best time (timed hunts) %headblocks_hasHead_% — Check if player found a specific head %headblocks_order_previous% — Previous head in ordered hunt %headblocks_order_current% — Current target head %headblocks_order_next% — Next head in sequence %headblocks_leaderboard__name% — Leaderboard player name %headblocks_leaderboard__value% — Leaderboard score %headblocks_leaderboard_position% — Player's own rank ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ Commands ⬥ **Admin Commands** ``` /hb give <*|number> — Give head blocks /hb remove [uuid] — Remove a head /hb removeall [--confirm] — Remove all heads /hb move — Move a head to a new location /hb rename — Rename a head /hb list [hunt] [page] — List all heads /hb info [uuid] — Detailed head info /hb reset [--head ] — Reset player progress /hb resetall [--head ] — Reset all players /hb hunt create — Create a hunt /hb hunt delete — Delete a hunt /hb hunt enable/disable — Toggle hunt state /hb hunt list — List all hunts /hb hunt info — Hunt details /hb hunt select — Set active hunt for placement /hb hunt assign — Assign heads to a hunt /hb hunt transfer — Move head between hunts /hb hunt reset — Reset hunt progress /hb options rewards [head] — Configure rewards (GUI) /hb options hint — Configure hints (GUI) /hb debug resync — Resync data /hb export database — Export data to SQL ``` **Player Commands** ``` /hb progress [player] — View progress /hb top [number] — Global leaderboard /hb hunt top — Hunt leaderboard /hb hunt progress [hunt] — Hunt-specific progress /hb stats [hunt] [page] — Detailed stats ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ Permissions ⬥ ``` headblocks.admin — Access to all admin commands headblocks.use — Interact with heads (default: true) headblocks.commands.progress — Use /hb progress (default: true) headblocks.commands.top — Use /hb top (default: true) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ For Developers ⬥ HeadBlocks exposes events you can listen to from your own plugins: `HeadClickEvent` — Fired when a player clicks a head `HeadCreatedEvent` — Fired when a head is placed `HeadDeletedEvent` — Fired when a head is removed `HuntCreateEvent` — Cancellable, fired on hunt creation `HuntDeleteEvent` — Fired on hunt deletion `HuntStateChangeEvent` — Fired when a hunt is enabled/disabled ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ Languages ⬥ Fully translatable — every single message is customizable. Ships with **English** and **French**. Community translations welcome via Crowdin. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ⬥ Getting Started ⬥ 1. Drop `HeadBlocks.jar` in your `/plugins` folder 2. Restart your server 3. Use `/hb hunt create myFirstHunt` to create a hunt and select it 4. Sneak + right-click with a head to place it in the world 5. Configure rewards, hints, and behaviors to your liking 6. Let your players explore! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Links [GitHub](#) | [Wiki](#) | [Discord](#) | [bStats](#) *If you enjoy HeadBlocks, please leave a ⭐ rating — it helps a lot!*

AerWyn81

AerWyn81's Plugins

HeadBlocks by AerWyn81

AerWyn81's Organizations

Stars

Watching

HeadBlocks by