BloodTop — PvP Event Economy & Leaderboard Plugin
Track kills. Tax deaths. Hunt bounties. Crown champions.BloodTop is a self-contained PvP event plugin built for Lifesteal, KitPvP, Factions, and any server where player-versus-player combat is the heartbeat of your community. It runs a parallel event economy — completely independent from your main server balance — so you can host time-limited competitive seasons without touching your permanent economy.
No databases to configure. No external dependencies to install. Drop the JAR, start the event, and let your players fight for the top spot. This includes a GUI leaderboard that tracks Kills, deaths, KDR, currency, and the same statistics for Teams.
Why BloodTop?
Most servers run /baltop from Essentials and call it a day. The problem? Baltop tracks total wealth, not PvP skill. The richest player is usually the one who mined the longest or got the best trade — not the one who dominated in combat.BloodTop fixes that.
Every dollar on the BloodTop leaderboard is earned through blood. Kill a player, earn event money. Die, and you lose a percentage to death tax — and your killer takes a cut. Place bounties on top players using real Vault money, and the hunter who takes them down claims the reward. The leaderboard tells the real story of who runs your server.
BloodTop was designed for small-to-mid PvP communities (20–500 players) that want event seasons to feel competitive, rewarding, and abuse-proof — without spending hours configuring a heavyweight plugin.
Features at a Glance
Event Economy Run a fully independent event currency alongside your existing server economy. Optionally sync with Vault to add or remove real money on kills and deaths. Start, stop, pause, and resume the event at any time.Kill Rewards Players earn configurable event money for every PvP kill. Same-victim cooldowns, minimum session time requirements, and IP-matching prevent kill farming before it starts.
Death Tax When a player dies in PvP, a configurable percentage of their event balance is destroyed — and their killer receives a cut. High-balance players become high-risk targets. Large tax events are broadcast server-wide.
Bounty System Players spend real Vault money to place bounties on other players. When the target is killed, the bounty is paid out to the killer in event currency (and optionally in real money). Bounties stack — multiple players can pile onto the same target.
Automatic Bounties Every configurable interval, the plugin automatically places bounties on the top-ranked players. The #1 player wakes up with a target on their back. Fully configurable: interval, number of players, and bounty amounts per rank.
Practice Server Rewards A simple command-based reward system (/bloodtop reward <player> <amount> <reason>) lets you pipe rewards in from a Practice server, KOTH plugin, or any external source. Daily caps per reason type prevent abuse.
Anti-Abuse Engine Same-IP kill blocking, same-victim cooldowns, minimum victim session time, excessive kill pattern detection, suspicious activity logging to file, and real-time staff alerts. Players with bloodtop.bypass can be exempted.
GUI Menus Clean chest-based GUIs for the leaderboard, bounty board, player stats, and team rankings. Player heads with full stat breakdowns, color-coded bounty tiers, pagination for large player counts, and cross-linked navigation between every screen. Console commands fall back to chat output automatically.
BetterTeams Integration If BetterTeams is installed, BloodTop automatically hooks in: same-team kills are blocked from earning rewards, each event kill adds score to the killer's team, and a full team leaderboard aggregates member balances for team-vs-team competition. Works without BetterTeams — no config changes needed.
PlaceholderAPI Support 22 placeholders covering individual stats, leaderboard positions, and team data. Drop them into your scoreboard, TAB plugin, or hologram setup.
YAML Storage All player data is stored in a single data.yml file. No database setup, no SQL configuration, no external services. Auto-saves on a configurable interval and on shutdown. Designed for reliability on day one.
Full Command Reference
Player Commands
| Command | Description | Permission |
|---|---|---|
| /bloodtop | Open the leaderboard GUI | bloodtop.use |
| /bloodtop top | Open the leaderboard GUI | bloodtop.use |
| /bloodtop stats | View your own stats GUI | bloodtop.use |
| /bloodtop stats <player> | View another player's stats GUI | bloodtop.use |
| /bloodtop bounty | View your own bounty info | bloodtop.use |
| /bloodtop bounty <player> | View a player's bounty info | bloodtop.use |
| /bloodtop teamtop | Open the team leaderboard GUI | bloodtop.use |
| /bloodtop teamstats | View your team's aggregated stats | bloodtop.use |
| /bloodtop help | Show all available commands | bloodtop.use |
| /bounty add <player> <amount> | Place a bounty on a player (costs Vault money) | bloodtop.bounty |
| /bounty view | View your own bounty status | bloodtop.use |
| /bounty view <player> | View a player's bounty and stats | bloodtop.use |
| /bounty top | Open the bounty board GUI | bloodtop.use |
Admin Commands
| Command | Description | Permission |
|---|---|---|
| /bloodtop start | Start the BloodTop event (broadcasts to server) | bloodtop.admin |
| /bloodtop stop | Stop the event and save all data | bloodtop.admin |
| /bloodtop pause | Pause the event (no rewards, data still tracked) | bloodtop.admin |
| /bloodtop resume | Resume a paused event | bloodtop.admin |
| /bloodtop status | View plugin status, hook info, and player count | bloodtop.admin |
| /bloodtop reload | Reload all configuration files | bloodtop.admin |
| /bloodtop reset confirm | Permanently wipe all event data | bloodtop.admin |
| /bloodtop give <player> <amount> <reason> | Give event money to a player | bloodtop.admin |
| /bloodtop giveall <amount> <reason> | Give event money to all online players | bloodtop.admin |
| /bloodtop reward <player> <amount> <reason> | Reward a player (respects daily caps) | bloodtop.admin |
| /bloodtop bounty set <player> <amount> | Set a player's bounty to an exact amount | bloodtop.admin |
| /bloodtop bounty add <player> <amount> | Add to a player's existing bounty | bloodtop.admin |
| /bloodtop bounty clear <player> | Remove all bounty from a player | bloodtop.admin |
Console Support: All admin commands can be run from the server console. GUI commands fall back to chat-based output when run from console.
Permissions
| Permission | Default | Description |
|---|---|---|
| bloodtop.use | All players | Basic commands: leaderboard, stats, bounty viewing, help |
| bloodtop.bounty | All players | Place bounties on other players with /bounty add |
| bloodtop.admin | OP only | All admin commands: start, stop, give, reward, reset, etc. |
| bloodtop.alerts | OP only | Receive in-game anti-abuse notifications |
| bloodtop.bypass | OP only | Bypass all anti-abuse checks (cooldowns, IP blocking, etc.) |
/lp group default permission set bloodtop.use true
/lp group default permission set bloodtop.bounty true
For staff who should see abuse alerts but not have full admin:
/lp group moderator permission set bloodtop.alerts true
PlaceholderAPI Placeholders
All placeholders are registered automatically when PlaceholderAPI is installed. No ecloud download required.Player Placeholders
| Placeholder | Returns |
|---|---|
| %bloodtop_balance% | Player's event balance |
| %bloodtop_kills% | Player's event kill count |
| %bloodtop_deaths% | Player's event death count |
| %bloodtop_rank% | Player's leaderboard position |
| %bloodtop_bounty% | Bounty value on the player's head |
Leaderboard Placeholders
| Placeholder | Returns |
|---|---|
| %bloodtop_top_1_name% | Name of the #1 ranked player |
| %bloodtop_top_1_balance% | Balance of the #1 ranked player |
| %bloodtop_top_2_name% | Name of the #2 ranked player |
| %bloodtop_top_2_balance% | Balance of the #2 ranked player |
| %bloodtop_top_3_name% | Name of the #3 ranked player |
| %bloodtop_top_3_balance% | Balance of the #3 ranked player |
Team Placeholders (requires BetterTeams)
| Placeholder | Returns |
|---|---|
| %bloodtop_team_name% | Player's team name |
| %bloodtop_team_displayname% | Team name with color formatting |
| %bloodtop_team_balance% | Team's combined event balance |
| %bloodtop_team_kills% | Team's combined kill count |
| %bloodtop_team_deaths% | Team's combined death count |
| %bloodtop_team_rank% | Team's leaderboard position |
| %bloodtop_team_score% | Team's BetterTeams score |
| %bloodtop_team_top_1_name% | Name of the #1 ranked team |
| %bloodtop_team_top_1_balance% | Combined balance of the #1 team |
| %bloodtop_team_top_1_kills% | Combined kills of the #1 team |
Configuration
BloodTop generates three configuration files on first run. All values have sensible defaults — you can start the event immediately and tune later.config.yml — Core Settings
# Event stateevent:
enabled: false # Controlled via /bloodtop start|stop
paused: false # Controlled via /bloodtop pause|resume
name: "&4&lBloodTop&c: Season Zero"
# Economy integration
economy:
use-vault-money: false # Master toggle for Vault integration
add-real-money: false # Deposit real money on kill rewards
remove-real-money-on-tax: false # Withdraw real money on death tax
# Kill rewards
kill-rewards:
enabled: true
base-amount: 500 # Event money per kill
same-victim-cooldown-minutes: 10 # Cooldown before earning from same victim
minimum-victim-session-minutes: 5 # Victim must be online this long
broadcast-kills: true # Announce kills server-wide
# Death tax
death-tax:
enabled: true
percent: 5.0 # Percentage of victim's balance lost
max: 5000 # Maximum tax per death
killer-cut-percent: 50.0 # How much of the tax the killer receives
broadcast-threshold: 1000 # Broadcast when tax exceeds this amount
# Bounties
bounties:
enabled: true
min: 100 # Minimum bounty amount
max: 50000 # Maximum bounty amount
# Automatic bounties on top players
auto-bounties:
enabled: true
interval-hours: 24 # How often auto-bounties are placed
top-amount: 3 # Number of top players targeted
rewards:
1: 5000 # Bounty on #1 player
2: 3000 # Bounty on #2 player
3: 1500 # Bounty on #3 player
# Practice/external reward system
practice-rewards:
enabled: true
daily-caps:
practice_win: 2500 # Max earnable per day from practice wins
duel_win: 1500 # Max earnable per day from duel wins
default: 5000 # Default cap for unspecified reasons
# Anti-abuse
anti-abuse:
enabled: true
same-ip-block: true # Block rewards when killer/victim share IP
notify-staff: true # Send alerts to players with bloodtop.alerts
max-same-victim-per-hour: 5 # Flag after this many kills on same victim
log-to-file: true # Write suspicious activity to logs/suspicious.log
# BetterTeams integration
betterteams:
block-same-team-kills: true # No rewards for killing teammates
block-ally-kills: false # No rewards for killing allied teams
add-team-score-on-kill: true # Add BetterTeams score per event kill
score-per-kill: 1 # BetterTeams score per kill
# Data
data:
auto-save-minutes: 5 # Auto-save interval
leaderboard-size: 10 # Players shown per page in chat output
messages.yml — All Player-Facing Text
Every message the plugin sends is configurable. Supports & color codes. Key messages include kill notifications, death tax alerts, bounty placement/claim broadcasts, stat displays, error messages, and help text.data.yml — Player Data (Auto-Generated)
Stores all player records: UUID, name, event balance, kills, deaths, bounties placed/claimed, bounty value, tax lost/gained, and suspicious flags. This file is managed entirely by the plugin — don't edit it while the server is running.Anti-Abuse System
BloodTop includes a multi-layer anti-abuse system designed for small communities where players know each other and creative exploits are inevitable.Same-IP Detection If two players connect from the same IP address, kills between them yield no rewards. Logged and staff-alerted.
Same-Victim Cooldown After killing a specific player, the killer cannot earn from that same victim again for a configurable duration (default: 10 minutes). The cooldown is per killer-victim pair.
Minimum Session Time Victims must have been online for a configurable minimum duration (default: 5 minutes) before kills against them yield rewards. Prevents logout-login farming.
Excessive Kill Detection If a player kills the same victim more than a configurable number of times within one hour (default: 5), it's flagged as suspicious. The kill is blocked, the player's suspicious flag counter increments, and staff with bloodtop.alerts are notified in real time.
Logging All suspicious activity is written to plugins/BloodTop/logs/suspicious.log with timestamps, player names, UUIDs, and the reason for the flag.
Bypass Permission Staff and trusted players can be given bloodtop.bypass to skip all anti-abuse checks.
GUI System
BloodTop includes four interlinked chest-based GUI menus. All GUIs use player heads with real skin textures and provide click-to-navigate between screens.Leaderboard GUI (/bloodtop or /bloodtop top) 6-row chest showing up to 21 players per page. Each entry is a player head displaying rank (with gold/silver/bronze icons for top 3), event balance, kills, deaths, K/D ratio, bounties claimed, tax lost/gained, and active bounty value. Bottom navigation bar includes buttons for your personal stats, the bounty board, and the team leaderboard. Supports pagination.
Bounty Board GUI (/bounty top or /bounty) Same layout as the leaderboard, but filtered to players with active bounties and sorted by bounty value. Bounties are color-coded by tier: legendary ($10,000+), high ($5,000+), standard ($1,000+), and normal. Displays the total bounty pool across all active bounties. Your own bounty status is shown in the bottom bar.
Player Stats GUI (/bloodtop stats [player] or /bounty view [player]) 5-row detailed view of an individual player. Dedicated item slots for balance (gold ingot), kills (diamond sword), deaths (bone), K/D ratio (emerald or redstone), active bounty (skull), bounties claimed (experience bottle), bounties placed (book), death tax lost (barrier), and death tax gained (golden apple). Admins see a suspicious flags indicator. Team affiliation shown if BetterTeams is installed.
Team Leaderboard GUI (/bloodtop teamtop) Teams ranked by combined member event balance. Uses tiered armor icons (gold, iron, chainmail, leather chestplates) for rank. Shows combined balance, total kills, total deaths, member count, average balance per member, and team K/D ratio. Gracefully shows "not available" if BetterTeams isn't installed.
Dependencies
| Plugin | Required? | Purpose |
|---|---|---|
| Vault + economy provider | Recommended | Bounty placement costs real money. Optional real-money sync on kills/deaths. Plugin works without it — economy features are disabled with a console warning. |
| PlaceholderAPI | Optional | Registers 22 placeholders for scoreboards, TAB, holograms. Auto-detected on startup. |
| BetterTeams | Optional | Team kill blocking, team leaderboard, team score sync, team placeholders. Auto-detected on startup. |
Installation
- Build the plugin with mvn clean package or use the pre-built JAR.
- Place BloodTop.jar in your server's plugins/ folder.
- Install Vault and an economy provider (EssentialsX recommended) if you want bounty costs and optional real-money sync.
- Start the server. The plugin generates config.yml, messages.yml, and data.yml automatically.
- Configure config.yml to your liking. All defaults are playable out of the box.
- Run /bloodtop start to begin the event.
Use Cases
Lifesteal Seasons Run timed BloodTop seasons alongside your Lifesteal server. Players earn event currency through PvP, and the top earner at season's end wins a prize. Reset data between seasons with /bloodtop reset confirm.KitPvP Events Enable BloodTop during weekend events or scheduled PvP tournaments. Use /bloodtop giveall for participation rewards and /bloodtop give for KOTH or supply drop payouts.
Factions Wars With BetterTeams integration, entire factions compete for the top team spot. Automatic bounties on leading factions keep the competition dynamic.
Practice Server Integration Pipe rewards from a connected Practice server using /bloodtop reward <player> <amount> practice_win from console. Daily caps prevent players from grinding practice wins all day.
Staff-Run Mini Events Use /bloodtop give and /bloodtop giveall to reward players for attending hosted events, winning drop parties, or completing challenges. Every reward feeds into the same leaderboard.
Troubleshooting
| Problem | Solution |
|---|---|
| "Vault not found" on startup | Install Vault and an economy provider (EssentialsX). Bounties require Vault. |
| No rewards on kills | Run /bloodtop status — the event must be started and not paused. |
| Bounties not deducting money | Vault must be installed with a working economy provider. |
| Data missing after restart | Check that plugins/BloodTop/data.yml exists and is writable. Check file permissions. |
| PlaceholderAPI placeholders not working | Reload PlaceholderAPI after installing BloodTop. No ecloud download needed — it auto-registers. |
| Config changes not taking effect | Run /bloodtop reload. |
| Anti-abuse false positives | Adjust thresholds in config.yml under anti-abuse. Give trusted staff bloodtop.bypass. |
| BetterTeams features not appearing | Ensure BetterTeams is installed and loaded before BloodTop. Check /bloodtop status for hook status. |
| Plugin fails to load | Confirm Java 17+ and Paper/Spigot 1.20.1+. Check the full console stack trace. |
Technical Notes
- All data is stored in data.yml using Bukkit's YAML configuration API. For servers with 500+ tracked players, consider migrating to SQLite in a future version.
- Auto-save runs asynchronously on a configurable interval (default: 5 minutes). Data is also saved synchronously on server shutdown.
- Kill history for anti-abuse tracking is held in memory and cleaned up every 2 hours. It does not persist across restarts.
- Daily reward caps reset at midnight server time.
- The event state (enabled/paused) is persisted to config.yml so it survives restarts.
- Automatic bounties are placed on a repeating timer. The timer restarts from zero on plugin load — it does not track time across restarts.
- Player heads in GUIs are loaded via Bukkit's SkullMeta.setOwningPlayer(), which may cause brief lag on first load for uncached skins. Subsequent opens are instant.
Version: 1.3.0 API: Paper/Spigot 1.20.1+ Java: 17+
