PvPIndex Battles connects your Paper or Velocity server to pvpindex.com, an open, tamper-proof ELO ranking platform for competitive Minecraft PvP. Every duel gets recorded, signed, and submitted to the API; your players earn verified ratings they can compare against the rest of the network.

We have a forum post: https://www.spigotmc.org/threads/pvpindex-battles.719810/
Join our Discord and talk directly with our team: https://discord.gg/AGBUWhb6JQ

Features

• 10 ranked game modes - Crystal, Sword, Pot, NoDebuff, Soup, Axe, Mace, Boxing, Sumo, UHC each with independent ELO ladders and separate leaderboards
• 1v1 matchmaking queue - fully configurable 54-slot GUI (gui.yml) with per-mode ELO, countdowns, and automatic arena teleportation
• Cross-server duels - /battle challenge <player> [mode] works standalone or routes through a Velocity or BungeeCord proxy
• Network-wide tab completion - proxy broadcasts all online players so /battle challenge <TAB> shows names from every backend server
• Battle replay system - frame-by-frame recording, reviewable in-game with /pvpmod replay <id>
• Arena pool - procedural, schematic, and world-copy generation strategies; four bundled schematics included
• Moderation suite - player reports, local bans, federated network-wide bans, real-time spectating
• PlaceholderAPI integration - ELO, rank, win/loss, queue state, and active mode placeholders for scoreboards and tab lists
• Fully configurable messages via messages.yml
• HMAC-signed payloads - battles are cryptographically signed before submission; the API rejects anything tampered with
• Open ELO formula - K=32, trust-weighted implementation published under MIT at github.com/PVP-Index/battle-validator
• Folia compatible - runs on Folia, Paper, Purpur, Spigot, and Bukkit (1.21+)

Requirements

Requirement	Version
Java	21+ (25+ for Paper 26.1.x servers)
Paper / Folia / Purpur / Spigot	1.21.x or 1.21.4+ (API 26.1.x)
Velocity or BungeeCord (optional)	Velocity 3.x / BungeeCord 1.21+
PlaceholderAPI (optional)	2.11+
PvPIndex API key	Free at pvpindex.com

Installation

Paper

1. Drop PvPIndexBattles-<version>.jar into your server's plugins/ folder.
2. Start the server (config files are generated automatically)
3. Stop the server and set your API key in plugins/PvPIndexBattles/config.yml:
   
   Code (YAML):

   api:
     api_key : "your-api-key-here"
   
   server:
     id : "my-server"
4. Restart and run /pvpindex to confirm the plugin loaded correctly.

Velocity (optional)

Drop PvPIndexBattles-velocity-<version>.jar into your Velocity plugins/ folder and configure plugins/pvpindex-battles/config.properties with the same API key and shared secret used on your Paper backends.

→ See docs.pvpindex.com/server_owner/proxy-setup for the full proxy setup guide.

Commands

/battle - Player commands

Command	Description
/battle	Open the matchmaking mode selection GUI
/battle challenge <player> [mode]	Challenge another player to a duel
/battle accept <id>	Accept an incoming challenge
/battle decline <id>	Decline an incoming challenge
/battle leave	Leave the queue or forfeit an active battle

/pvpindex - Admin commands

Command	Permission	Description
/pvpindex reload	pvpindex.reload	Reload plugin configuration
/pvpindex submissions	pvpindex.admin	List pending battle submissions
/pvpindex sync	pvpindex.admin	Retry unsubmitted battles
/pvpindex retryfailed	pvpindex.admin	Retry failed API submissions

/pvpmod - Moderation commands

Command	Permission	Description
/pvpmod watch <player>	pvpindex.mod	Spectate a live battle
/pvpmod replay <id>	pvpindex.mod	Play back a recorded battle
/pvpmod report <player> <reason>	pvpindex.mod.report	Report a player
/pvpmod ban <player> <duration> <reason>	pvpindex.mod.ban	Ban a player from PvPIndex battles
/pvpmod unban <player>	pvpindex.mod.ban	Unban a player

PlaceholderAPI Placeholders

Placeholder	Description
%pvpindex_elo%	Overall ELO rating
%pvpindex_elo_<mode>%	ELO for a specific game mode
%pvpindex_rank%	Overall ladder rank position
%pvpindex_wins%	Session win count
%pvpindex_losses%	Session loss count
%pvpindex_kd%	Win/loss ratio
%pvpindex_in_battle%	true / false
%pvpindex_queued%	true / false
%pvpindex_queued_mode%	Mode ID or none
%pvpindex_battle_type%	Display name of the active game mode

Configuration Snapshot

→ Full reference: docs.pvpindex.com/server_owner/configuration

Links

• Website & leaderboards - pvpindex.com
• Documentation - docs.pvpindex.com
• Source (plugin) - github.com/PVP-Index/pvpindex-battles
• Source (ELO formula / anti-cheat) - github.com/PVP-Index/battle-validator
• Issue tracker - github.com/PVP-Index/pvpindex-battles/issues