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!)