PerfSkullHunt - Event plugin v1.1.3

PerfSkullHunt
Collect themed player heads placed in your worlds, earn event points, spend them in the event shop, claim milestone rewards, and compete on leaderboards—all with MiniMessage GUIs and optional Discord webhooks. Paper and Folia 1.21 - 26.x

Support
Report bugs and get support here: https://discord.gg/VvM6k2eBDa

Features
• Folia support – Runs on region-threaded servers without unsafe main-thread blocking for core flows.
• Seasonal head categories – Configure textures per category (e.g. christmas, easter), particle/sound on find, and active-category or all.
• World skulls – Admins register placed skulls; per-player progress (found vs not), optional hide found skulls, holograms and distance-limited particles, optional skull trails.
• Economy & points – Vault-backed money; event points from finds for the event shop and milestone claims (event-rewards mode: shop, claim, or both).
• Player hub GUI – Hint shop, event shop, milestone claim GUI, leaderboard, progress, and timed-event info; each entry can be toggled under features.hub.
• Hint shop – Pay in-game currency for a random unfound skull hint with optional action-bar arrow; separate cooldown and pricing.
• Timed events – Start/end windows per timezone with optional broadcasts and hub “event info” display.
• Leaderboard GUI – Top hunters with paging and sign-based name search (configurable sign lines).
• Feature toggles – Independently enable hub slots and /skullhunt subcommands (open-hub, top, hints) via features.commands.
• Discord webhooks – Optional embeds for shop purchases, event start/end, first completion, skull finds (configurable).
• IP restriction – Optional cap on accounts per IP with a database-backed whitelist for households.
• Admin workflow – List/teleport to skulls, give category head kits, reset players or everyone, stats, creative+sneak break rules for removing hunt skulls, decoration-head protection.

Placeholders
%perfskullhunt_found% – Skulls this player has found
%perfskullhunt_total% – Total registered skulls
%perfskullhunt_remaining% – Skulls not yet found by this player
%perfskullhunt_progress% – Completion percent
%perfskullhunt_points% – Cached event points balance
%perfskullhunt_event% – Active/upcoming timed event category display name or None
%perfskullhunt_event_remaining% – Human-readable time until start/end when relevant, else N/A

Commands
/skullhunt – Open the event hub GUI (perfskullhunt.use; respects features.commands.open-hub)
/skullhunt top – Open the leaderboard GUI (perfskullhunt.use; respects features.commands.top)
/skullhunt hints – Open the hint shop GUI (perfskullhunt.use, perfskullhunt.hints; respects features.commands.hints)
/event and /hunt – Aliases for /skullhunt (same permissions) when configured in command-aliases
/perfskullhunt reload – Reload configs and GUIs (perfskullhunt.admin)
/perfskullhunt list – List all hunt skulls with locations; clickable TP for players (perfskullhunt.admin)
/perfskullhunt tp (skull-id) – Teleport to a skull (perfskullhunt.admin, players only)
/perfskullhunt sethead (skull-id) (texture) – Set a skull’s texture value (perfskullhunt.admin)
/perfskullhunt reset (player) – Clear hunt progress for a player (perfskullhunt.admin)
/perfskullhunt resetall confirm – Wipe all players’ hunt data after confirmation (perfskullhunt.admin)
/perfskullhunt stats (player) – Show found/total for a player (perfskullhunt.admin)
/perfskullhunt give (player) (category) – Give all placeable heads for a category (perfskullhunt.admin)
/perfskullhunt event – Show timed event status (perfskullhunt.admin)
/perfskullhunt confirmbreak – In-game reminder for creative+sneak skull removal (perfskullhunt.admin)
/perfskullhunt ipwhitelist add (player) – Whitelist a player for relaxed IP limits (perfskullhunt.admin)
/perfskullhunt ipwhitelist remove (player) – Remove from IP whitelist (perfskullhunt.admin)
/perfskullhunt ipwhitelist list – List whitelisted UUIDs (perfskullhunt.admin)

Database
• SQLite (perfskullhunt.db by default)
• MySQL (optional, configured under database.mysql)