Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!

HeadBlocks

Hide heads in your world and let your players find them to earn rewards. Perfect for an Easter event

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:<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

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━