pvpOption

A Minecraft mod/plugin that adds opt-in PvP flagging. Players must explicitly enable PvP before they can deal or receive damage from other players. Unflagged players are fully protected.

---

Branches

Branch	Platform	MC Version
multi_1.21.11	Fabric + NeoForge (Architectury)	1.21.11
plugin_1.21.11	Spigot, Paper, Purpur, Pufferfish	1.21.11
multi_26.x (upcoming)	Fabric + NeoForge (Architectury)	26.x
plugin_26.x (upcoming)	Spigot, Paper, Purpur, Pufferfish	26.x

---

Features

• Opt-in PvP flagging — players choose when to engage
• Configurable warmup period before PvP activates
• Combat cooldown — prevents toggling off mid-fight
• Action bar HUD showing PvP and combat status
• Auto-unflag after configurable idle time
• Broadcast toggle announcements to the server
• Admin commands to force-set, lock, and unlock player flags
• Config hot-reload without restarting the server

Note: The mod syncs the pvp= value in server.properties to match its own pvpEnabled setting on startup. The mod's config is the source of truth — editing server.properties directly has no effect.

---

Commands

All commands use /pvpoption (alias /pvp).

Command	Description
/pvp	Toggle your PvP flag
/pvp on	Enable your PvP flag
/pvp off	Disable your PvP flag
/pvp status	Show your current PvP status
/pvp list	List all flagged players

Admin (pvpoption.admin permission)

Command	Description
/pvp admin	Show current config values
/pvp admin enable|disable	Enable or disable PvP system-wide
/pvp admin warmup <seconds>	Set warmup duration (0 to disable)
/pvp admin cooldown <seconds>	Set combat cooldown duration (0 to disable)
/pvp admin autounflag <minutes>	Set idle auto-unflag time (0 to disable)
/pvp admin broadcast on|off	Toggle flag change broadcasts
/pvp admin set <player> on|off	Force-set a player's flag
/pvp admin status <player>	View a player's PvP status
/pvp admin lock <player>	Unflag and block a player from enabling PvP
/pvp admin unlock <player>	Restore a player's ability to use PvP
/pvp admin reload [silent]	Reload config from disk

---

Configuration

Config is written on first launch. All values can also be changed live via admin commands.

Multi-loader — config/pvpoption.json Paper plugin — plugins/pvpOption/config.json

{
  "pvpEnabled": true,
  "cooldownSeconds": 30,
  "warmupSeconds": 5,
  "broadcastToggle": true,
  "autoUnflagMinutes": 0
}

Field	Default	Description
pvpEnabled	true	Master switch for the PvP system
cooldownSeconds	30	Seconds after combat before PvP can be disabled
warmupSeconds	5	Seconds before PvP activates after opting in
broadcastToggle	true	Announce flag changes to all players
autoUnflagMinutes	0	Minutes of idle time before auto-disabling PvP (0 = off)

---

Requirements

Multi-loader: Architectury API
Paper: Paper 1.21.11+