HeadBlocks

⭐ Why HeadBlocks?

• Everything in game, through menus. Create a hunt, place heads, set rewards and behaviors without opening a single YAML file.
• Unlimited hunts at the same time. Each one has its own heads, progression, rewards, leaderboard and rules.
• Not only heads. Hide blocks, items, floating texts, mobs, NPCs, Nexo / ItemsAdder / Oraxen furniture or ModelEngine / BetterModel 3D models.
• Built for networks. MySQL + Redis keep player progress in sync across all your servers.
• Lightweight and maintained. 17,000+ downloads (on all platforms), rated 4.7/5, active support on Discord.

🎯 What can you build with it?

• 🐣 A seasonal event: an Easter egg hunt that opens on April 1st and closes on its own two weeks later.
• ⏱️ A speedrun: players step on a pressure plate, the timer starts, the fastest run tops the leaderboard.
• 🧭 A story trail: heads must be found in order, each one giving the next clue.
• 🏆 A live race (3.6.0): heads spawn a few at a time; the first to grab one takes it, and the first to reach the goal wins.
• 💎 Hub collectibles: hidden heads all around your lobby, with a reward every 10 found.
• 🔒 A progression path: hunts unlocked by a previous hunt, a permission, playtime, a WorldGuard region or any PlaceholderAPI value.

✨ Features

Hunts & behaviors

• Free: find the heads in any order
• Ordered: the heads must be found in a set order
• Scheduled: the hunt opens and closes on its own between two dates
• Timed: race mode started by a pressure plate, with a dedicated leaderboard
• Spawning heads (3.6.0): heads appear a few at a time, at random spots or in an area, with weighted templates, points, random rewards and traps
• Requirements: area (cuboid or WorldGuard, with optional confinement), previous hunt, permission, playtime, PlaceholderAPI comparison, combined with ALL / ANY

Rewards

• Messages, titles, broadcasts and commands for each head found
• Milestone rewards (every X heads, or on hunt completion)
• Random commands, inventory space check before giving items

Visuals & feedback

• Holograms above the heads, showing found / not found
• Particles above the heads not found yet
• Fireworks, sounds, titles and particles on click
• Spinning heads, gradient and rainbow texts
• Hints: a sound when close, a distance and an arrow in the action bar

Progression & leaderboards

• Progress per hunt and global, with customizable progress bars
• Global, per-hunt, timed and points leaderboards
• Detailed player statistics

Storage & multi-server

• SQLite: works out of the box, nothing to configure
• MySQL / MariaDB: shared database, connection pool, SSL
• Redis: real-time synchronization between servers

🔌 Integrations

• PlaceholderAPI: global and per-hunt placeholders (progress, leaderboards, timers, scores…)
• HeadDatabase / HeadDB: use any head with hdb:<id>
• WorldGuard: regions as hunt areas
• Nexo, ItemsAdder, Oraxen: custom items and furniture
• ModelEngine, BetterModel: 3D models
• Citizens, FancyNpcs, ZNPCsPlus: NPCs
• PacketEvents: per-player holograms with placeholders, found heads hidden client-side

🚀 Get started in 1 minute

1. Drop the jar in /plugins and restart
2. /hb hunt create easter
3. /hb give to get the heads
4. Sneak + right-click to place them
5. /hb options and the hunt menu to set rewards and behaviors

That's it, your players can start hunting. Full guide on the wiki.

📦 Compatibility

• Minecraft 1.20 → 26.3, Java 17+
• Paper / Folia / Purpur: native build on Modrinth and Hangar
• Spigot: build on SpigotMC
• Languages: English and French included, more on Crowdin (contributions welcome!)

Main commands

• /hb progress / /hb top: player progress and leaderboard
• /hb hunt create|delete|enable|disable|list: manage hunts
• /hb hunt select <hunt>: choose the hunt where new heads go
• /hb hunt schedule: set the dates of a scheduled hunt
• /hb spawn <hunt> (3.6.0): spawn points, heads present, reroll
• /hb give, /hb options, /hb reload

All commands: wiki → Commands and Permissions

Permissions

Permission	Description	Default
headblocks.use	Interact with heads	everyone
headblocks.commands.progress	Own progress	everyone
headblocks.commands.top	Leaderboard	everyone
headblocks.commands.progress.other	Other players' progress	op
headblocks.area.bypass	Bypass hunt area confinement	op
headblocks.admin	All admin commands	op

Developer API

Events: HeadClickEvent, HeadCreatedEvent, HeadDeletedEvent, HuntCreateEvent, HuntDeleteEvent, HuntStateChangeEvent (hunt events are cancellable).
Documentation: wiki → Developers

Screenshots