OptionalPVP

OPTIONAL PVP
============

Optional PvP is a server-side Fabric mod for Minecraft Java Edition 1.21.11 that allows every player to decide whether they want to participate in player-versus-player combat.

Players who enjoy PvP can keep it enabled and fight other participating players normally. Players who prefer building, exploring, farming, or cooperative gameplay can disable PvP and remain protected from attacks by other players.

The mod is installed only on the dedicated server. Connecting players do not need to install the mod or any additional client-side files.

HOW PVP PROTECTION WORKS
------------------------

Player-versus-player damage is permitted only when both the attacker and the target have PvP enabled.

When either player has PvP disabled:

- The protected player cannot be damaged by another player.
- The protected player cannot damage other players.
- Direct melee attacks and player-owned projectile attacks are prevented.
- Damage from the environment, monsters, falls, fire, hunger, and other non-player sources continues to work normally.

Requiring both players to opt in prevents someone from attacking other players while remaining protected from retaliation.

New players begin with PvP enabled, matching normal Minecraft server behavior. They can disable it immediately with /pvp off.

COMMANDS
--------

Every player can manage their own PvP setting without operator permissions.

- /pvp - Displays the player's current PvP status.
- /pvp status - Displays whether PvP is enabled and any remaining lock time.
- /pvp on - Enables PvP.
- /pvp off - Disables PvP if the player is not currently locked in PvP.

Players can only change their own setting. The mod does not provide commands for changing another player's PvP preference.

ENABLE COOLDOWN
---------------

After using /pvp on, the player cannot disable PvP for five minutes.

This prevents players from enabling PvP, attacking someone, and immediately disabling PvP to avoid retaliation. Running /pvp on while PvP is already enabled does not restart this timer.

The status command shows how much time remains before PvP can be disabled.

COMBAT LOCK
-----------

When a player takes actual damage from another PvP-enabled player, a three-minute combat lock starts. Receiving additional player damage resets that lock to three minutes.

While the combat lock is active, the damaged player cannot use /pvp off.

Blocked attacks that deal no damage do not reset the combat lock. If the five-minute enable lock and three-minute combat lock overlap, the player must wait until both have expired before disabling PvP.

DEATH BEHAVIOR
--------------

Whenever a player dies, from PvP or any other cause, their PvP setting is automatically switched off.

Both cooldown timers are cleared upon death. After respawning, the player remains protected until they deliberately use /pvp on again. Enabling it starts a new five-minute disable lock.

PERSISTENT PLAYER SETTINGS
--------------------------

PvP preferences and active cooldown timestamps are saved on the server. Settings remain in effect across:

- Player disconnects and reconnects
- Server restarts
- Player deaths
- World sessions

The state file is stored at:

config/optional_pvp/players.json

No database or external service is required.

SERVER REQUIREMENTS
-------------------

- Minecraft Java Edition 1.21.11
- Fabric Loader 0.19.3 or a newer compatible release
- Fabric API 0.141.4+1.21.11
- Java 21 or newer
- A dedicated Fabric server

Only the server needs the mod and Fabric API. Vanilla and Fabric clients can join without installing Optional PvP.

INSTALLATION
------------

1. Install Fabric Loader for Minecraft 1.21.11 on the server.
2. Place Fabric API 0.141.4+1.21.11 in the server's mods directory.
3. Place optional-pvp-1.0.0.jar in the same directory.
4. Restart the server.
5. Players can then use /pvp, /pvp on, and /pvp off.

Optional PvP is designed for survival, SMP, community, family, and mixed-playstyle servers where competitive and noncompetitive players share the same world.