Happy Filter: The Anti-Bot Captcha Add-On for Minecraft Servers
Server owners know the pain: you build a thriving community, then a wave of automated bots floods your login queue, spams chat, and ruins the experience for everyone. Happy Filter is a Bukkit-based add-on that turns that problem on its head. Instead of a flimsy click-the-checkbox captcha, it drops every joining player into a short, real gameplay challenge that bots simply cannot solve.
What Is Happy Filter for Minecraft?
Happy Filter (internally known as HappyFilterCaptcha) is an anti-bot captcha system built entirely on the Bukkit API, with no NMS dependencies. That design choice means it runs cleanly across Spigot, Paper, and Purpur from version 1.14 all the way up to 1.21. It also works behind both BungeeCord and Velocity proxies, with ViaVersion recommended on the proxy for cross-version support.
The concept is refreshingly simple. When a player connects, they are teleported to a void captcha world, their inventory is cleared, and they receive a session-tagged pickaxe. A chest spawns containing food and junk items in random slots. The player must move all the food into a shulker box, break the shulker with the pickaxe, and drop it into a hopper. Bots fail this sequence; real players complete it in roughly 20 seconds.
How the Captcha Challenge Works
Step-by-Step Player Flow
- The player joins and is teleported to the void captcha world with a cleared inventory.
- A session-tagged pickaxe is placed in their main hand.
- A chest generates with food (3 types, 1 to 4 each) plus 8 to 12 junk items in random slots.
- The player moves every food item into the shulker box.
- The player breaks the shulker with the pickaxe and drops it into the hopper.
- On pickup, the plugin checks the PersistentDataContainer tag and verifies an exact 1:1 match of type and count.
If everything checks out, the player is connected to the lobby through a BungeeCord channel. Any failure results in a kick. Quitting mid-captcha does not trigger a kick; the player simply retries fresh on their next join. Only one room is active at a time, so other players wait frozen in a queue.
Key Features of Happy Filter
Beyond the core captcha mechanic, Happy Filter packs a solid feature set for administrators:
- Bukkit API only, no NMS, for broad compatibility.
- Self-copying world: it pulls from plugins/HappyFilterCaptcha/World to ./captcha and never overwrites your existing world.
- World set to PEACEFUL with doMobSpawning disabled and chunks always loaded.
- All text configurable in messages.yml with ampersand color codes, plus a title and 30-second actionbar timer.
- Kicks logged to console, exceptions written to errors.log.
- Commands: /happycaptcha reload, test, and status, with happyfilter.bypass and happyfilter.admin permissions.
If you want a smoother setup experience, the foxygame.net launcher includes Happy Filter in its curated add-on catalog, letting you add it to a compatible profile without manually juggling jar files or matching loader versions.
Requirements and Installation
What You Need Before You Start
Happy Filter requires a captcha backend server, a lobby backend, and a proxy, with the mode set to PROXY. You also need to configure the chest, hopper, and shulker coordinates from your own World inside config.yml. Note that this is a BETA release, and you must download the captcha world itself separately and place it in plugins/HappyFilterCaptcha/.
How to Install Happy Filter
To install, drop the plugin jar into your server's plugins folder, start the server once to generate the configuration files, then stop it. Place the provided captcha world into the HappyFilterCaptcha directory, edit config.yml with your coordinates and proxy mode, and restart. From there, use /happycaptcha test to verify the flow before opening your server to the public.
When you download Happy Filter, always grab the latest build and double-check that your proxy and backend versions align. Because the plugin avoids NMS, updates rarely break it, but keeping ViaVersion current on the proxy prevents version mismatch headaches for players on newer clients.
Final Thoughts
Happy Filter offers a clever, gameplay-driven answer to the bot problem that plagues so many Minecraft servers. By forcing joiners through a genuine inventory puzzle, it filters out automation while keeping the experience fast and fair for real players. If you run Spigot, Paper, or Purpur between 1.14 and 1.21 and want a captcha that actually works, Happy Filter is well worth testing on your network.