HeadBlocks — The Ultimate Head Hunting Experience

Transform your server into an exciting treasure hunt playground

1.20 — 1.21+ | 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:<id>
• 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_<id>_found%      — Found in hunt
%headblocks_hunt_<id>_total%      — Total in hunt
%headblocks_hunt_<id>_left%       — Remaining in hunt
%headblocks_hunt_<id>_progress%   — Progress % in hunt
%headblocks_hunt_<id>_name%       — Hunt display name
%headblocks_hunt_<id>_state%      — Hunt state
%headblocks_hunt_<id>_besttime%   — Best time (timed hunts)
%headblocks_hasHead_<uuid|name>%  — 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_<pos>_name%   — Leaderboard player name
%headblocks_leaderboard_<pos>_value%  — Leaderboard score
%headblocks_leaderboard_position%     — Player's own rank

⬥ Commands ⬥

Admin Commands

/hb give <player> <*|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 <name>                  — Rename a head
/hb list [hunt] [page]             — List all heads
/hb info [uuid]                    — Detailed head info

/hb reset <player> [--head <id>]   — Reset player progress
/hb resetall [--head <id>]         — Reset all players
/hb hunt create <name>             — Create a hunt
/hb hunt delete <name>             — Delete a hunt
/hb hunt enable/disable <name>     — Toggle hunt state
/hb hunt list                      — List all hunts
/hb hunt info <name>               — Hunt details
/hb hunt select <name>             — Set active hunt for placement
/hb hunt assign <criteria> <hunt>  — Assign heads to a hunt
/hb hunt transfer <uuid> <hunt>    — Move head between hunts
/hb hunt reset <name> <player>     — Reset hunt progress
/hb options rewards [head]         — Configure rewards (GUI)
/hb options hint                   — Configure hints (GUI)
/hb debug resync <database|locations>  — Resync data
/hb export database                    — Export data to SQL

Player Commands

/hb progress [player]              — View progress
/hb top [number]                   — Global leaderboard
/hb hunt top <name>                — Hunt leaderboard
/hb hunt progress <player> [hunt]  — Hunt-specific progress
/hb stats <player> [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!