Here is a comprehensive, clear, and up-to-date documentation of the BountyHunterExpress system in English. This includes all the recent updates, features, and structural enhancements.

📋 BountyHunterExpress — System Documentation This plugin allows players to place bounties on other players using a hybrid chat and Graphical User Interface (GUI) system. It supports item rewards, monetary cash prices (via Vault), custom configurations, anti-cheat logging, and expiration safeguards.

1. How a Player Creates a Bounty (Step-by-Step) Step 1: Initiation Command A player types the following command in chat to target another player:

/bounty set <target_player> 💡 Note: Thanks to the integrated Tab-Completer, pressing TAB automatically completes the names of online players. A player cannot place a bounty on themselves; doing so triggers an error message configured in the settings.

Step 2: The 2-Row Creation GUI (18 Slots) Upon executing the command, a custom screen containing 18 slots (2 rows) opens:

Slots 0 to 15 (Reward Slots): The creator can freely drag and drop up to 16 item stacks from their personal inventory into these slots. The plugin fully preserves custom names, enchants, descriptions, and item properties.

Slot 16 (Gold Ingot): Click this to specify a custom cash reward.

Slot 17 (Emerald Block): This is the Confirm Button.

Step 3: Setting a Cash Reward The player clicks the Gold Ingot (Slot 16).

The menu temporarily closes, and a chat prompt appears: Please type the money amount in chat (or type 'cancel').

The player types a positive number (e.g., 5000) and hits Enter.

The system validates the input, and the GUI re-opens automatically. The Gold Ingot's Lore updates in real-time to display the current amount.

Step 4: Launching or Cancelling To Confirm: The player must click the Emerald Block (Slot 17). The plugin checks their Vault balance. If funds are sufficient, the money and items are deducted, the bounty goes live, and a server-wide broadcast is sent.

To Cancel: If the player closes the GUI (via ESC) without clicking the Emerald Block, or types cancel in chat, the process aborts. All items currently inside the GUI are safely returned to the player's inventory or dropped at their feet if full.

1. Available Commands & GUI Interaction Command Permission Description /bounty set <player> None (Default) Opens the 18-slot creation GUI to set item and cash rewards on a target. /bounty claimexpired None (Default) Opens a safe 27-slot claim terminal to retrieve unclaimed rewards from your expired bounties. /openbounties <player> bountyhunter.admin (Admin Command) Opens the main leaderboard GUI displaying active bounties. The Main Leaderboard GUI: Displays target players as skulls. Hovering over a skull renders custom metadata containing total accumulated cash and itemized rewards, completely controlled by your configuration.

2. Claiming Bounties & Smart IP Logging When an active target is killed by another player, the rewards are processed instantly:

Payouts: The killer automatically receives the total cash reward directly deposited into their Vault economy account, and the item rewards are placed straight into their inventory (overflow items drop safely onto the ground).

Clearance: The target's listing is permanently cleared from the Active Bounties config and leaderboard GUI.

Smart IP Logging: If the system detects that the killer and the victim share the exact same IP address, it will not block the transaction. The killer gets the rewards and the bounty clears as normal, but the plugin silently flags it by printing a specialized alert line into logs/cheaters.log so staff can investigate manual boosting later.

1. Expiration Loop (The Safeguard) Every 5 minutes, an automated background task scans active listings. If a bounty crosses its set expiration threshold (Default: 24 hours) without a successful kill:

The bounty is deleted from the active list.

Cash and items are securely relocated into a structural database associated with the creator's UUID (expired.yml).

The creator can type /bounty claimexpired at any time to claim back their cash and retrieve their items via a secure storage menu.

1. Structure File Configs config.yml (Fully Customizable Layout)

YAML

BountyHunterExpress - Configuration File

GUI Settings

gui: title: "&4&lWanted List - Bounties" size: 54 head-lore-format: - "&8-------------------" - "&6Money Reward: &a$%money%" - "&bItem Rewards:" - "%items%" - "&8-------------------" item-list-format: "&f- %item_name% &7x%amount%" expired-title: "&4&lYour Expired Rewards"

New Creation GUI Settings (Now 18 slots - 2 rows)

creation-title: "&0Set Bounty Rewards" creation-gold-name: "&6&lAdd Money Reward" creation-gold-lore: - "&7Current Money: &a$%money%" - "" - "&eClick here to type a money" - "&eamount in chat!"

Confirm Button Settings

creation-confirm-name: "&a&lCONFIRM BOUNTY" creation-confirm-lore: - "&7Click here to officially launch" - "&7the bounty on this target!"

Expiration Settings

expiration: time-hours: 24

Messages (Supports Color Codes with &)

messages: no-permission: "&cYou do not have permission to use this command." player-not-found: "&cPlayer not found or offline." usage-openbounties: "&cUsage: /openbounties <player>" usage-bounty: "&cUsage: /bounty set <player> OR /bounty claimexpired" not-enough-money: "&cYou do not have enough money to set this bounty!" expired-claimed-money: "&aReturned $%amount% to your balance from an expired bounty!" expired-gui-open: "&eOpening your expired rewards inventory..." cannot-bounty-self: "&cYou cannot place a bounty on yourself!"

Chat Money Input Messages

type-money-prompt: "&e&lPlease type the money amount in chat (or type 'cancel'):" invalid-money-amount: "&cInvalid number amount or less than 0." money-added-success: "&aSuccessfully added $%amount% to the bounty setup!" bounty-creation-cancelled: "&cBounty creation cancelled and items returned."

Broadcasts

bounty-set-broadcast: "&c&lA new bounty has been placed on %target%!" bounty-claimed-broadcast: "&6&l%killer% has killed %target% and claimed all their bounties!"

🛑 Requirements ⚠️ IMPORTANT NOTICE: This plugin requires the following dependency to be installed on your server, otherwise it will safely disable itself upon startup:

Vault (Along with a compatible Economy plugin like EssentialsX, EconomyShopGUI, etc.)