PVP Toggle

A Paper 1.21 PVP toggle plugin: players choose whether to participate in PVP; admins can manage others’ state. Supports Folia, LuckPerms, PlaceholderAPI, and per-world PVP state.

---

Features

• Players: /pvp or /pvp on / off / toggle to change your own PVP
• Admins: /pvp on|off|toggle <player> to manage someone else’s PVP
• Status: /pvp status for yourself, /pvp status <player> for others (with permission)
• Reload: /pvp reload to reload config (with permission)
• Per-world: Optional separate PVP state per world
• Debounced save: Fewer disk writes
• Cooldown: Configurable cooldown after toggling your own PVP
• Feedback: Configurable sound, ActionBar, and Title on toggle
• PlaceholderAPI: Placeholders like %pvptoggle_status%
• Folia: Region-aware scheduling; async save so it doesn’t block
• LuckPerms: Permissions handled by LuckPerms when installed

---

Commands

Command	Description	Permission
/pvp	Same as /pvp toggle; toggles your PVP	pvptoggle.use
/pvp on	Enable PVP for yourself	pvptoggle.use
/pvp off	Disable PVP for yourself	pvptoggle.use
/pvp toggle	Toggle your PVP	pvptoggle.use
/pvp status	View your own PVP status	pvptoggle.use
/pvp status <player>	View another player’s PVP status	pvptoggle.status.other
/pvp on|off|toggle <player>	Set PVP for another player	pvptoggle.admin
/pvp reload	Reload config.yml	pvptoggle.reload

---

Permissions

Permission	Description	Default
pvptoggle.use	Use /pvp, on/off/toggle, and /pvp status (self)	true
pvptoggle.admin	Use /pvp on|off|toggle	op
pvptoggle.reload	Use /pvp reload	op
pvptoggle.status.other	Use /pvp status	op

---

config.yml

• default-pvp: Default PVP state for new or unknown players (true/false)
• persist-on-rejoin: Whether to keep each player’s choice when they rejoin
• per-world: Whether to store PVP state per world (separate per world)
• save-debounce-seconds: Debounce time in seconds before writing to disk; 0 = save every time
• command-cooldown-seconds: Cooldown in seconds after toggling your own PVP; 0 = no cooldown
• toggle-feedback: Feedback when toggling
  • play-sound: Play a sound
  • sound: Sound name (e.g. ENTITY_EXPERIENCE_ORB_PICKUP)
  • sound-volume / sound-pitch: Volume and pitch
  • use-actionbar: Show message in ActionBar
  • actionbar-message: ActionBar text; %status% = on/off
  • use-title: Show title
  • title / subtitle: Title and subtitle; %status% = on/off
• placeholder-on / placeholder-off: Values returned by PlaceholderAPI placeholders
• messages.*: All messages; supports & color codes and %player%, %seconds%, %status%

---

PlaceholderAPI

With PlaceholderAPI installed, these placeholders are registered (return values are configurable):

Placeholder	Description
%pvptoggle_status%	Current player’s PVP status (in that player’s context)
%pvptoggle_status_<player>%	A specific player’s PVP status (e.g. %pvptoggle_status_Steve%)

Default return values are on / off; change them with placeholder-on and placeholder-off in config.

---

Compatibility

• Server: Paper 1.21+ (or compatible forks)
• Folia: Supported (folia-supported: true); uses AsyncScheduler for saves
• LuckPerms: Soft dependency; permissions are managed by LuckPerms when present
• PlaceholderAPI: Soft dependency; placeholders are registered when present

---