⚔️ ApxBounty — Next-Gen Minecraft Bounty System

ApxBounty is a clean, modern, and highly-optimized player bounty plugin built specifically for modern Paper, Purpur, and Spigot servers. It introduces an immersive target bounty hunting experience with interactive GUI menus, detailed statistics, automated leaderboards, and zero lag.

---

🌟 Key Features

💰 Economy Integration

• Full Vault support compatible with any economy plugin (EssentialsX, CMI, etc.).
• Optional placement fee when creating or increasing bounties.
• Optional tax deduction percentage on bounty claims.
• Custom currency symbol and formatting support (e.g. $1,000, 1k, 2.5m).

🖥️ Interactive GUI System

• Bounty Browser: View active bounties with target player heads, amounts, and dates.
• Smart Sorting: Instantly sort by Highest Bounty, Lowest Bounty, Newest, or Oldest.
• Search Functionality: Quickly search for any player's bounty directly inside the GUI.
• Pagination: Smooth multi-page navigation for servers with dozens of active bounties.
• Stats & History Menus: Dedicated graphical menus to inspect player hunting records.

🛡️ Exploit & Abuse Protection

• Self-Kill Prevention: Completely blocks suicide / self-damage exploits (arrows, crystals, fall tags).
• Self-Bounty Block: Players cannot place bounties on themselves.
• Safe Death Listener: Bounties are only awarded upon legitimate PvP elimination by another distinct player.
• Refund on Expiration: Optional expiration timer that safely refunds players if a bounty goes unclaimed.

🏆 Statistics, History & Leaderboards

• Local high-performance SQLite database (bounties.db) with zero external database setup required.
• Tracks:
  • Total bounties placed
  • Total bounties claimed
  • Bounty PvP kills
  • Total money spent
  • Total money earned
• Automated cached leaderboards updated periodically without impacting TPS.

🔔 Immersive Notifications & Audio

• Aesthetic Visuals: Sleek small-font typography for messages and GUI elements.
• Titles & Subtitles: Cinematic screen alerts when a bounty is placed or claimed.
• Action Bar Alerts: Clean floating messages.
• Configurable Sound Effects: Fully customizable Minecraft sounds for placement, claims, clicks, and errors.

🔄 Automatic Modrinth Update Checker

• Automatically checks the official Modrinth API on startup and every 6 hours.
• Pure asynchronous execution ensures the main server thread is never blocked.
• Dedicated admin permission (apxbounty.admin.update) to notify staff members.

---

📋 Commands & Permissions

👥 Player Commands

Command	Description	Permission	Default
/bounty	Opens the interactive bounty menu	apxbounty.use	Everyone (true)
/bounty <player> <amount>	Places a new bounty or increases an existing one	apxbounty.place	Everyone (true)
/bounty search <player>	Searches for an active bounty on a player	apxbounty.search	Everyone (true)
/bounty stats [player]	Displays bounty hunting stats for yourself or another player	apxbounty.stats	Everyone (true)
/bounty top	Opens the bounty leaderboards menu	apxbounty.top	Everyone (true)
/bounty history [player]	Views past bounty claim history	apxbounty.history	Everyone (true)

🛡️ Admin Commands

Command	Description	Permission	Default
/bountyadmin reload	Reloads config.yml, gui.yml, and messages.yml	apxbounty.admin	OP only
/bountyadmin set <player> <amount>	Sets an exact bounty amount directly	apxbounty.admin	OP only
/bountyadmin remove <player>	Removes an active bounty without refund	apxbounty.admin	OP only
/bountyadmin clearall	Removes all active bounties across the server	apxbounty.admin	OP only
/bountyadmin debug	Toggles console debug logs	apxbounty.admin	OP only

🔑 Additional Permissions

• apxbounty.admin.update — Receive in-game update notifications when a new version is released on Modrinth (Defaults to OP).

---

📊 PlaceholderAPI Support

ApxBounty includes built-in PlaceholderAPI expansion support:

• %apxbounty_bounty% — The active bounty on the player's head (formatted).
• %apxbounty_bounty_raw% — The raw numeric bounty amount.
• %apxbounty_claimed% — Number of bounties claimed by the player.
• %apxbounty_kills% — Total bounty PvP kills.
• %apxbounty_placed% — Total bounties placed by the player.
• %apxbounty_spent% — Total money spent on bounties.
• %apxbounty_earned% — Total money earned from claiming bounties.
• %apxbounty_top_target_<1-10>% — Name of player at top rank.
• %apxbounty_top_amount_<1-10>% — Bounty amount of top rank.

---

⚙️ Installation & Requirements

1. Requirements:
   • Java 17 or newer.
   • Minecraft Server: Paper, Folia or Spigot (1.20 - 1.21.11+).
   • Vault plugin + a Vault-compatible economy plugin (e.g. EssentialsX).
2. Installation:
   • Download ApxBounty-1.1.0.jar.
   • Drag and drop the JAR into your server's plugins/ directory.
   • Restart your server (or load with a plugin manager).
   • All configuration files (config.yml, gui.yml, messages.yml) and database (bounties.db) will generate automatically!

---

💡 Support & Feedback

Found an issue or have a feature suggestion? Report it on our issue tracker or Modrinth discussion page!