PvPArena
Production-grade 1v1 dueling for Paper 1.21+ and 26.1+
Folia / Luminol ready ▪ Cross-version ▪ Authentic 1.8 PvP ▪ Free edition
────────────────────────────────



✦ Overview ✦
A self-contained dueling system for modern Paper servers.
1.8 legacy PvP and 1.9+ modern PvP coexist as per-mode settings.
Players queue, invite each other, or sit out as spectators —
the plugin handles arena selection, kit equip, rounds, rollback, results, and bot fallback.
Detects modern dimensions layout (Paper 1.21.7+ / 26.1+) and adapts automatically.
No config edits required when upgrading the server.
✦ Combat ✦
▪ 1.8 legacy PvP per mode — no attack-cooldown, classic knockback,
fishing-rod KB, crit / sweep visual packets filtered (ProtocolLib)
▪ 1.9+ modern PvP per mode — vanilla cooldown / sweep / shield mechanics
▪ Mixed modes coexist on the same server — pick style per match
▪ /pk 1.8 | 1.9 per-player style override for protected worlds
▪ Force-style: if either side chose 1.8, the duel uses 1.8 for both
✦ Match Flow ✦
▪ Best-of N rounds — BO1 / BO3 / BO5 / BO7, per mode
▪ Pre-round countdown with animated title frames
▪ Mid-round loser locked into spectator hide (invisible + non-collidable)
▪ Per-round arena rollback — event-based, no full chunk scans
▪ Winner loot phase with configurable timeout
▪ Time-limit draw support
▪ Crash-recovery — server crash mid-match restores pre-match state on next start
✦ Kits & Arenas ✦
▪ Per-mode kits — inventory, armor, potions, enchants, NBT
▪ /arena addkit <id> saves your current inventory as a kit
▪ GUI kit editor with potion presets — /arena kit open <id>
▪ Selection wand — left = pos1, right = pos2, then /arena create <id>
▪ Two spawn points per arena (side A / side B), custom map icons
▪ Mode-arena restriction — whitelist specific arenas per mode
▪ Built-in BigDoor-Lite — per-arena entry doors with
instant / lift / swing / bigdoor animations, evict-on-close,
smooth interpolation, auto / inward / outward swing direction
✦ GUI & HUD ✦
▪ Main queue menu, duel builder (mode / map / time cyclers), result panel
▪ Live match browser, spectator settings, bot difficulty picker
▪ Round scoreboard + BossBar with mode / round / score / opponent HP / ping
▪ Per-match TAB list isolation — only see self + opponent
▪ Countdown title with animated frames, border-loss warnings
✦ Spectator ✦
▪ Hotbar tools — switch target, browse matches, leave
▪ Live match browser GUI ( /pvp spec)
▪ Vanish / hide-from-players / collidable / can-be-targeted — all configurable
▪ Strict isolation — damage and interactions completely blocked
✦ Compatibility ✦
▪ Paper 1.21.1 ~ Paper 26.1.x — single jar, no per-version builds
▪ Folia / Luminol — full region-thread support, auto-detected
▪ Auto-migrates arenas.yml to canonical NamespacedKey form on first load
▪ Custom dimensions ( worlds:xxx, datapack dimensions) resolve automatically
▪ Compat shims for renamed Attribute / Enchantment / Potion constants (1.21 ↔ 26.1)
✦ Integrations ✦
ProtocolLib · HuskSync · PlaceholderAPI · Citizens
Addon SPI for companion plugins (e.g. PvPArenaRank)
✦ Languages ✦
Out of the box: English · 简体中文 · 繁體中文
MiniMessage formatting with full hex color support
────────────────────────────────
✦ Commands ✦
✦ Permissions ✦
Player commands ( /pvp, /duel, /pk, /qleave) are open by default.
────────────────────────────────
✦ Requirements ✦
▪ Paper 1.21.1 ~ 26.1.x (Spigot not supported)
▪ Java 21+
▪ Optional but recommended: ProtocolLib (1.8 visual packet filter)
▪ Optional: PlaceholderAPI, HuskSync, Citizens
✦ Quick Start ✦
✦ Notes ✦
▪ Use /stop + restart for jar upgrades.
/reload (global) is unsafe on modern Paper / Folia.
/arena reload is fine — it only rereads config files.
▪ On Paper 1.21.7+ / 26.1+ dimensions layout, instance-world
mode is auto-disabled. Matches run in-place with rollback.
▪ Upgrading from PvPArena-Light?
Rename plugins/PvPArena-Light/ → plugins/PvPArena/.
All your data ( arenas.yml / modes.yml / kits.yml / config.yml /
lang/ / addons/ / *.db) carries over as-is.
────────────────────────────────
Discord: ru3690
​