docs: describe CoreProtect PvP logging

projects/CoreProtect/docs/api/version/v13.md

@@ -26,3 +26,12 @@ Command filters present boats and minecarts as block changes: `a:+block` include
 Entity-container location filters match either the transaction's immutable original location or the entity's persisted current/final location, and typed results expose the persisted current/final location. The persisted position is checkpointed when a transaction is logged and during relevant entity lifecycle changes; the synchronous typed APIs do not schedule blocking live-entity scans.
 
 API rollback and restore methods return an empty result without performing any changes while a database purge is in progress.
+
+## Player versus player logging (v25.5+)
+
+- Added `CoreProtectAction.PVP_HIT` (`14`), `CoreProtectAction.PVP_KNOCKOUT` (`15`) and `CoreProtectAction.PVP_KILL` (`16`), and `CoreProtectPreLogEvent.Action.PLAYER_PVP`.
+- The legacy lookup methods accept these ids. Rollback and restore never select them.
+- `boolean logPvpKnockout(Player attacker, Player victim)` logs a nonlethal knockout at the victim's position, with the attacker's held item as the weapon. Use it when your plugin cancels a knockout blow instead of letting the victim die, because CoreProtect does not log cancelled hits.
+- `boolean logPvpKnockout(String attacker, String victim, Location location, String weapon)` does the same from names. `weapon` may be `null` for an empty hand.
+
+Both methods return `false` when the API is disabled, `player-pvp` is off in that world, or the attacker and victim are the same player.

projects/CoreProtect/docs/commands.md

@@ -211,7 +211,11 @@ ___
 | `a:item` | items dropped, thrown, picked up, deposited, or withdrawn by players |
 | `a:+item` | items picked up or withdrawn by players |
 | `a:-item` | items dropped, thrown, or deposited by players |
-| `a:kill` | mobs/animals killed |
+| `a:kill` | mobs, animals and players killed |
+| `a:pvp` | hits, knockouts and kills between players (see `player-pvp`) |
+| `a:hit` | hits one player landed on another, with the weapon and damage |
+| `a:knockout` | nonlethal knockouts reported by RPCharacters |
+| `a:pvp-kill` | players killed by another player, with the weapon |
 | `a:spawn` | entities placed or spawned by players |
 | `a:session` | player logins/logouts |
 | `a:+session` | player logins |
@@ -312,6 +316,10 @@ Lookup commands are generally the same as rollback commands. The primary differe
   *(lookup where Notch was each minute over the last 2 hours)*
 * `/co lookup u:Notch t:1d a:session,ping`  
   *(lookup Notch's logins, logouts and positions over the last day)*
+* `/co lookup u:Notch t:1h a:pvp`  
+  *(lookup every hit, knockout and kill Notch dealt in the last hour)*
+* `/co lookup r:30 t:30m a:hit`  
+  *(lookup who hit whom within 30 blocks in the last 30 minutes, to see who attacked first)*
 * `/co lookup u:Notch a:username`  
   *(lookup previous usernames used by Notch)*
 

projects/CoreProtect/docs/config.md

@@ -63,6 +63,18 @@ Each ping is stored in the session table alongside logins and logouts, with the
 
 Search pings with `/co lookup u:<player> a:ping`; `a:session` lists only logins and logouts. Purges remove old pings with the rest of the session history. One row per online player per minute is small: about 0.5 GB a year in SQLite for an average of 15 players online.
 
+## Player Versus Player Logging
+
+`player-pvp` logs fights between players:
+
+```yaml
+player-pvp: true
+```
+
+Every damaging hit one player lands on another is logged, including arrows, tridents, potions and other damage a player causes, with the weapon and the damage dealt. A player killed by another player gets a kill row with the killing blow's weapon, and RPCharacters reports nonlethal knockouts through the API. Cancelled hits, such as hits in a protected region, are not logged.
+
+Each row is stored at the victim's position with the attacker as the user. Search them with `/co lookup a:pvp`, or narrow to `a:hit`, `a:knockout` or `a:pvp-kill`. Rows within one second appear in the order the hits happened. Rollbacks and restores never change these rows, and block filters skip them. Set the value to `false` to stop logging, or disable it in one world with a per-world config.
+
 ## Per-World Configuration
 
 If you'd like to modify the logging settings for a specific world, simply do the following:

projects/CoreProtect/docs/permissions.md

@@ -73,6 +73,9 @@ The following permissions can be used to restrict functionality within the plugi
 * **coreprotect.lookup.kill** *(default: op)*  
   Can be optionally used as a negative permission to prevent entity kill lookups.  
    
+* **coreprotect.lookup.pvp** *(default: op)*  
+  Can be optionally used as a negative permission to prevent lookups of hits, knockouts and kills between players (`a:pvp`). Without it, fights are also left out of lookups that name no action.  
+   
 * **coreprotect.lookup.spawn** *(default: op)*  
   Can be optionally used as a negative permission to prevent entity spawn lookups.