From 5eda106eecf8d52c06dea2378a1c150e5a630523 Mon Sep 17 00:00:00 2001 From: Ryan <7389646+ryanbarlow97@users.noreply.github.com> Date: Sat, 17 Oct 2026 10:27:17 +0000 Subject: [PATCH 1/2] docs: describe CoreProtect PvP logging Document the a:pvp, a:hit, a:knockout and a:pvp-kill lookups, the player-pvp option, the coreprotect.lookup.pvp permission and the logPvpKnockout API. Co-Authored-By: Claude Opus 5.5 --- projects/CoreProtect/docs/api/version/v13.md | 9 +++++++++ projects/CoreProtect/docs/commands.md | 8 ++++++++ projects/CoreProtect/docs/config.md | 12 ++++++++++++ projects/CoreProtect/docs/permissions.md | 3 +++ 4 files changed, 32 insertions(+) diff --git a/projects/CoreProtect/docs/api/version/v13.md b/projects/CoreProtect/docs/api/version/v13.md index 82677e7..7746875 100644 --- a/projects/CoreProtect/docs/api/version/v13.md +++ b/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. diff --git a/projects/CoreProtect/docs/commands.md b/projects/CoreProtect/docs/commands.md index bb3dff0..2825288 100644 --- a/projects/CoreProtect/docs/commands.md +++ b/projects/CoreProtect/docs/commands.md @@ -212,6 +212,10 @@ ___ | `a:+item` | items picked up or withdrawn by players | | `a:-item` | items dropped, thrown, or deposited by players | | `a:kill` | mobs/animals 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)* diff --git a/projects/CoreProtect/docs/config.md b/projects/CoreProtect/docs/config.md index aece52c..5217a2b 100644 --- a/projects/CoreProtect/docs/config.md +++ b/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: 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: diff --git a/projects/CoreProtect/docs/permissions.md b/projects/CoreProtect/docs/permissions.md index cf5785d..beb4dfa 100644 --- a/projects/CoreProtect/docs/permissions.md +++ b/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`). +   * **coreprotect.lookup.spawn** *(default: op)* Can be optionally used as a negative permission to prevent entity spawn lookups.   From 3e0ef5662b97052ab572afa547138fd8f169caf4 Mon Sep 17 00:00:00 2001 From: Ryan <7389646+ryanbarlow97@users.noreply.github.com> Date: Sat, 17 Oct 2026 11:02:13 +0000 Subject: [PATCH 2/2] docs: note the PvP permission hides fights from plain lookups Also say that a:kill lists player kills, now that it does. Co-Authored-By: Claude Opus 5.5 --- projects/CoreProtect/docs/commands.md | 2 +- projects/CoreProtect/docs/permissions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/projects/CoreProtect/docs/commands.md b/projects/CoreProtect/docs/commands.md index 2825288..08bae6e 100644 --- a/projects/CoreProtect/docs/commands.md +++ b/projects/CoreProtect/docs/commands.md @@ -211,7 +211,7 @@ ___ | `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 | diff --git a/projects/CoreProtect/docs/permissions.md b/projects/CoreProtect/docs/permissions.md index beb4dfa..40320ec 100644 --- a/projects/CoreProtect/docs/permissions.md +++ b/projects/CoreProtect/docs/permissions.md @@ -74,7 +74,7 @@ The following permissions can be used to restrict functionality within the plugi 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`). + 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.