MobSkulls v1.8

HeadHunting -- Progression Head Hunting for Factions & Skyblock & Survival
Hunt • Collect • Level Up

ABOUT
MobSkulls is a comprehensive progression plugin designed for any type of server. It rewards players for hunting and farming mobs, offering a deep leveling system, mask crafting, automated farming tools, and server-wide booster events. Packed with features out of the box and fully configurable.

Head Hunting & Progression
- Leveling System: Earn XP by redeeming heads. Progress from Level 0 to Level 15 (configurable), unlocking new mobs, perks, and rewards as you level up.
- Mob Unlocking: Mobs are locked by default. Players must reach specific levels to unlock the ability to collect, sell, and redeem heads for that mob type.
- Spawner Unlocking: Each mob's spawner is also level-gated. Players must reach the required level before they can purchase that entity's spawner from the shop.
- Perks: As you progress through levels, higher-tier mobs sell for more in-game money and give more XP per head redeemed.
- Right-Click Redeem: Right-click a skull to redeem it for XP. Shift+Right-Click redeems all skulls of that type from your entire inventory at once.

Rare Skulls & Mask System
- Rare Skull Drops: Every mob has a configurable chance to drop a rare variant of its skull. Rare skulls have a purple glow and are used to craft powerful masks.
- Mask Crafting: Use /ms mask to open a crafting GUI. Combine rare skulls (default 128) to craft a mask for that mob type.
- Mask Application: Drag and drop a mask onto any helmet in your inventory to apply it. Right-click a masked helmet to remove the mask and get it back.
- 11 Unique Mask Abilities:
  - Chicken Mask: No fall damage.
  - Horse Mask: Permanent speed boost (configurable amplifier).
  - Blaze Mask: Fire aspect hands — enemies burn on hit (configurable duration).
  - Rabbit Mask: Jump boost and speed combined (both configurable).
  - Wither Mask: Aura that strips positive effects from nearby players and applies Wither (configurable range, duration, amplifier).
  - Zombie Mask: Poisonous hands with configurable chance, duration, and amplifier.
  - Skeleton Mask: Steal hearts on hit, healing yourself (configurable max steal).
  - Creeper Mask: Chance to deal double damage (configurable percentage).
  - Pig Mask: Infinite hunger — never starve.
  - Cow Mask: Permanent Resistance I.
  - Iron Golem Mask: Gain 2 extra regenerable hearts (configurable).

Spawner System
- Spawner Shop: Purchase mob spawners from the /ms shop GUI. Each spawner is level-gated so players must progress to unlock higher-tier spawners.
- Spawner Stacking: Shift+right-click a placed spawner while holding the same type to stack them together. A 5x stacked spawner spawns 5x the mobs without needing 5 separate blocks.
- Mob Stacking: Entities from spawners automatically stack into one entity with a nametag showing the count (e.g. "5x Zombie"). Killing one reduces the stack by 1. Nearby same-type mobs merge together automatically.

Hopper System
- Head Hopper: Purchase from /ms shop. Place near your farm and any skull that drops within its configurable range gets collected into the hopper's inventory instead of falling on the ground. Pipe into chests for fully automated skull collection.
- Kill Hopper: Purchase from /ms shop. Pulls nearby mobs onto the hopper and auto-kills them one at a time on a configurable timer. Skulls and drops go straight into the hopper's inventory. Kills count for the player who placed the hopper, including leaderboard tracking. Works with stacked mobs and booster multipliers.

Booster System
- Staff Boosters: Admins can start global drop multiplier events with /ms boost (e.g. /ms boost 2 30m for 2x drops for 30 minutes).
- Scheduled Events: Configure recurring booster events in boosters.yml that auto-start on specific days and times (e.g. 2x drops every Saturday at 6pm for 2 hours).
- Only the highest active booster applies — boosters do not stack.
- Server-wide title, chat, and sound announcements when boosters start and end.
- Any player can check active boosters with /ms boost.

Leaderboards
- Per-Mob Leaderboards: Use /ms leaderboard to open a paginated mob selection GUI. Click any mob to see the top 10 players ranked by kills for that specific mob.
- Each leaderboard entry shows the player's head, rank, kill count, and level.
- Your own rank and kill count for each mob is shown in the bottom corner.
- Fully paginated for servers with many mobs configured.

Level & Stats GUI
- Use /ms level to open a clean chest GUI showing your level, XP progress bar, total kills, skulls sold, money earned, and a list of all unlocked/locked mobs.
- Shows what unlocks at your next level.
- Fully paginated for servers with many mobs.

Sell System
- Use /ms sell to open a GUI previewing all sellable skulls in your inventory with prices and totals. Click the emerald block to sell all unlocked skulls at once.
- Locked skulls (too high level) are not sold.

PlaceholderAPI Support
- Full PlaceholderAPI integration with placeholders for level, XP, progress, kills, skulls sold, money earned, booster status, and more.
- Works with scoreboards, TAB plugins, holograms, and anywhere PlaceholderAPI is supported.
- Available placeholders: %mobskulls_level%, %mobskulls_xp%, %mobskulls_xp_needed%, %mobskulls_xp_progress%, %mobskulls_xp_progressbar%, %mobskulls_max_level%, %mobskulls_kills%, %mobskulls_sold%, %mobskulls_earned%, %mobskulls_booster%, %mobskulls_booster_time%, %mobskulls_booster_active%

Database Support
- YAML: Flat file storage, works out of the box with no setup.
- MySQL/MariaDB: Full support with HikariCP connection pooling for production servers.
- MongoDB: Document-based storage with full connection URI support.
- Configurable in config.yml — automatically falls back to YAML if the database connection fails.
- Async saves during gameplay, synchronous saves on shutdown to guarantee data integrity.
- Auto-save interval configurable (default every 5 minutes).

Skull Protection
- Dropped skulls are invulnerable to fire, lava, explosions, and all other damage sources.
- Configurable despawn timer (default 5 minutes) — set to 0 for skulls that never despawn.
- Skulls stack to 64.

Configuration
- config.yml: General settings, level XP thresholds, storage/database configuration, debug toggle, skull despawn timer.
- lang.yml: All plugin messages in one place, fully customizable with color codes and placeholders.
- mobs/mobs.yml: All mob skull data — textures, sell prices, XP values, unlock levels, spawner prices, rare drop chances. Add any mob by copying an entry and changing the entity type.
- hoppers/hoppers.yml: Head hopper and kill hopper settings — prices, ranges, kill intervals, enable/disable toggles.
- masks/masks.yml: All mask configurations — enable/disable per mask, rare skull cost, ability descriptions, and all ability-specific values.
- boosters.yml: Scheduled booster event configurations — days, times, multipliers, durations.

Commands
- /ms help — Show all commands.
- /ms level — Open the level & stats GUI.
- /ms sell — Open the sell GUI.
- /ms shop — Open the spawner & hopper shop.
- /ms mask — Open the mask crafting GUI.
- /ms leaderboard — Open the per-mob kill leaderboards.
- /ms boost — View active boosters.
- /ms boost [multiplier] [duration] — Start a global booster (admin).
- /ms boost stop — Stop all active boosters (admin).
- /ms give [mob] [amount] — Give yourself skull(s) (admin).
- /ms givemask [mob] — Give yourself a mask (admin).
- /ms reload — Reload all configuration files (admin).

Permissions
- mobskulls.use — Basic plugin usage (default: true).
- mobskulls.sell — Access to the sell menu (default: true).
- mobskulls.shop — Access to the spawner shop (default: true).
- mobskulls.admin — Admin commands: reload, give, givemask, boost (default: op).

Dependencies
- Vault (https://www.spigotmc.org/resources/vault.34315/)

- Economy Plugin (https://essentialsx.net/)

Optional Dependencies
- PlaceholderAPI (https://www.spigotmc.org/resources/placeholderapi.6245/)