xBounties

xBounty
A modular, configurable bounty plugin for PaperMC 1.21+. Players can place bounties on each other, track targets in real-time, and compete for the top hunter spot on a live leaderboard.

Requirements
Requirement Version
Server software PaperMC (or any Paper fork)
Minecraft version 1.21+
Java 17+
Installation

1. Drop xBounty.jar into your server's plugins/ folder.
2. Restart or reload your server.
3. All config files are generated automatically inside plugins/xBounty/.
4. Install ExcellentEconomy if you want real economy integration (optional - see Soft Dependencies).

Updating the plugin? All config files are automatically updated with any new keys added in the new version. Your existing values are never overwritten.

Commands
Command Description
/bounty Opens the Bounty Board GUI
/bounty top Opens the Top Hunters GUI
/bounty add <player> <amount> [currency] Places or increases a bounty on a player, optionally specifying a currency
/bounty <player> Shows a player's active bounty (all currencies)
/bounty reset <player> (Admin) Resets a player's bounty and hunter stats
/bounty reload (Admin) Reloads all config files
The [currency] argument is optional. If omitted, economy.default-currency is used. Tab-completion will suggest all currencies listed in economy.allowed-currencies.

Permissions
Permission Description Default
xbounty.admin Access to /bounty reset and /bounty reload op
All other commands are available to all players by default.

How It Works
Placing a Bounty
Use /bounty add <player> <amount> [currency] to place a bounty on another player. The specified amount is immediately withdrawn from your balance in the given currency. If the target already has an active bounty, your contribution is added on top — multiple players can contribute to the same bounty, and all contributors are tracked individually.
Multi-currency bounties: With ExcellentEconomy, players can contribute in different currencies to the same bounty. For example, one player might add 500 money and another might add 200 tokens. The bounty board will show all currencies separately. Tracking costs are always charged in economy.default-currency.

Rules (configurable):

• A minimum amount is required per contribution (default: 100).
• Players cannot place a bounty on themselves (can be disabled).
• The target must be online unless offline targeting is enabled.
• Only currencies listed in economy.allowed-currencies are accepted.

Claiming a Bounty
Bounties are claimed automatically. When a player with an active bounty is killed by another player, the full bounty amount is deposited into the killer's balance, the bounty is removed, and a server-wide broadcast is sent.
Multi-currency note: When a bounty has contributions in multiple currencies, each currency total is paid out separately to the hunter.

Illegal Kills
If a player kills another player who has no active bounty, they are penalised with a bounty placed on themselves. This discourages random PvP and creates a risk/reward dynamic for hunters.
Two penalty modes are available:

• Flat — every illegal kill adds a fixed amount to the killer's bounty.
• Scaling — the penalty grows with each illegal kill the player accumulates, starting from a base amount and increasing by a set amount per prior offence.

The illegal kill system can be disabled entirely in config.yml.

Tracking
From the Bounty Board GUI, clicking a player's head purchases a temporary tracking ping on that target. The cost is calculated as a percentage of the target's bounty, clamped between a configurable minimum and maximum, and rounded according to your rounding setting.
While tracking is active:

• The tracker's compass is pointed at the target's live location (can be disabled).
• A burst of End Rod particles is spawned around the target's position periodically as a visual beacon (can be disabled).
• The target's coordinates are shown in the tracker's action bar on every update tick.

Tracking ends automatically when the duration expires, the target logs out, the tracker logs out, or either player changes world.

GUIs
Bounty Board
Opened with /bounty. Shows all active bounties as player heads sorted by your chosen sort mode. Click any head to purchase a tracking ping on that player.
Bottom row layout:

[ ← ] [ ] [ ⌄ ] [ ] [ ] [ ] [ ⚔ ] [ ] [ → ]
0 1 2 3 4 5 6 7 8
Prev Sort Your Stats Hunters Next

Button Slot Function
← Previous 0 Go to the previous page (does nothing on page 1)
Sort 2 Cycle through sort modes
Your Stats Head 4 Displays your own bounty and hunter stats as lore — not clickable
Top Hunters 6 Opens the Top Hunters GUI
→ Next 8 Go to the next page (does nothing on the last page)
Bounty Sort Modes (cycles on each click of the Sort button):

Mode Description
Highest Bounty Largest total bounty value first (default)
Most Contributors Bounties with the most individual contributors first
Username A-Z Alphabetical by target name
Username Z-A Reverse alphabetical by target name
Most Recent Most recently created bounties first
Top Hunters
Opened with /bounty top or via the Top Hunters button in the Bounty Board. Shows all hunters ranked by your chosen sort mode. Each entry is a player head with their stats in the lore.
Bottom row layout:

[ ← ] [ ] [ ⌄ ] [ ] [ ] [ ] [ ⚔ ] [ ] [ → ]
0 1 2 3 4 5 6 7 8
Prev Sort Your Stats Bounties Next

Button Slot Function
← Previous 0 Go to the previous page
Sort 2 Cycle through sort modes
Your Stats Head 4 Displays your own hunter stats as lore — not clickable
Bounties 6 Opens the Bounty Board GUI
→ Next 8 Go to the next page
Hunter Sort Modes (cycles on each click of the Sort button):

Mode Description
Most Bounties Claimed Most individual bounty claims first
Highest Amount Claimed Largest total currency earned from bounties first (default)
Hunter Level Sorted by hunter level (system coming in a future update)
Last Seen Most recently seen online first
Username A-Z Alphabetical by hunter name
Username Z-A Reverse alphabetical by hunter name
PlaceholderAPI
xBounty integrates with PlaceholderAPI in two ways:

xBounty placeholders (for use in other plugins)
xBounty registers the %xbounty_<placeholder>% expansion automatically if PlaceholderAPI is installed.

Placeholder Description
%xbounty_amount% The total active bounty currently placed on this player. Returns 0 if none.
%xbounty_kills% Number of bounty targets this player has killed and claimed.
%xbounty_claimed% Total currency this player has earned from claiming bounties.
%xbounty_illegal_kills% Number of illegal kills (killing players with no bounty) this player has committed.
%xbounty_successful_bounties% Alias for %xbounty_kills%.
PAPI placeholders in messages.yml
All messages in messages.yml support PlaceholderAPI %placeholder% tags from any installed expansion. This means you can include things like %player_name%, %vault_eco_balance%, or any other expansion directly in your message templates. xBounty's own {token} substitutions are applied first, then PAPI tags are resolved, so you can safely mix both in the same message.
Storage
SQLite
The default backend. No setup required — a data.db file is created automatically inside plugins/xBounty/. Suitable for single-server setups.

MySQL
For networks or servers that want data shared across instances.
storage:
```type: mysql
mysql:
host: localhost
port: 3306
database: xbounty
username: root
password: "yourpassword"
use-ssl: false
pool-size: 5```
The required tables are created automatically on first start. The connection pool is managed by HikariCP.

Soft Dependencies
Plugin Effect
ExcellentEconomy Enables named custom currencies and multi-currency bounties. Without it, xBounty falls back to Vault.
PlaceholderAPI Registers %xbounty_*% placeholders for use in other plugins, AND enables PAPI tags inside messages.yml.
LuckPerms Listed as a soft-depend for future permission node support. No effect currently.
Config Auto-Update
Every time the server starts, xBounty compares each config file on disk against the version bundled inside the JAR. Any keys that exist in the bundle but are missing from the file on disk are automatically added with their default values. Keys you have already set are never changed.

Color Codes
All text fields support & colour codes (e.g. &6 for gold, &c for red). Standard Minecraft formatting codes (&l, &o, &n, &m, &k, &r) are also supported.