Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!

PvPIndex-Battles

Official open free ELO platform with advanced battle system. Includes Sword PvP, Crystal PvP, Sumo and much more

PvPIndex Battles is a competitive PvP plugin for Paper, Folia, Purpur, Spigot, BungeeCord, and Velocity servers. It adds a full 1v1 duel and ranked matchmaking system with per-mode ELO ratings, persistent global leaderboards, battle replays, and a moderation suite - all synced to pvpindex.com so your players' rankings persist across the entire network.

Supported game modes: Crystal PvP · Sword PvP · Pot PvP · NoDebuff · Soup PvP · Axe PvP · Mace PvP · Boxing · Sumo · UHC

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 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 API 26.1.x)
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 / Folia / Purpur / Spigot

Drop PvPIndexBattles-<version>.jar into plugins/.
Start the server, configs are generated automatically.
Stop the server, then add your API key to plugins/PvPIndexBattles/config.yml:

api:
  api_key: "your-api-key-here"

server:
  id: "my-server"

Restart and run /pvpindex to confirm everything loaded correctly.

Velocity / BungeeCord (optional)

Drop PvPIndexBattles-velocity-<version>.jar into your proxy plugins/ folder and configure plugins/pvpindex-battles/config.properties with the same API key and shared secret as your backend servers.

→ Full proxy setup guide: docs.pvpindex.com/server_owner/proxy-setup

Commands

`/battle` Players

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

`/pvpindex` Admins

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

`/pvpmod` Moderation

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 battles
`/pvpmod unban <player>`	`pvpindex.mod.ban`	Unban a player

PlaceholderAPI

Placeholder	Returns
`%pvpindex_elo%`	Overall ELO rating
`%pvpindex_elo_<mode>%`	ELO for a specific mode
`%pvpindex_rank%`	Global ladder position
`%pvpindex_wins%`	Session wins
`%pvpindex_losses%`	Session losses
`%pvpindex_kd%`	Win/loss ratio
`%pvpindex_in_battle%`	`true` / `false`
`%pvpindex_queued%`	`true` / `false`
`%pvpindex_queued_mode%`	Current queue mode or `none`
`%pvpindex_battle_type%`	Display name of the active mode

Configuration

# plugins/PvPIndexBattles/config.yml
api:
  api_key: ""
  base_url: "https://api.pvpindex.com/api"

server:
  id: "my-server"
  require_signature: false   # Recommended: set to true in production
  debug: false

arena:
  world_prefix: "pvpindex_arena"
  cleanup_delay_ticks: 100

queue:
  max_wait_seconds: 120

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