diff --git a/guides/PvP/hits-and-defeat.md b/guides/PvP/hits-and-defeat.md index faa14a5..e0ad67f 100644 --- a/guides/PvP/hits-and-defeat.md +++ b/guides/PvP/hits-and-defeat.md @@ -67,15 +67,48 @@ A policy that throws drops the hit. There is one policy for the whole server and A hit that would take a player's health to 0 defeats them, the way the relation's `defeat` says: - `"death"`: the game's own death. `playerDied` fires, and the player respawns as after any [death](/guides/players/join-and-spawn/#deaths-and-respawns). Once they are back up, they have spawn protection for `spawnProtectionSeconds`. -- `"kneel"`: the player drops to their knees for about four seconds, held at `kneelHp`, ignoring hits, and then gets up by themselves. `playerDowned` fires as they kneel and `playerDownedEnd` as they stand. Under a kneel relation, even the Killing Curse kneels. +- `"kneel"`: the player drops to their knees for `kneelSeconds`, held at `kneelHp`, ignoring hits, and then gets up by themselves. `playerDowned` fires as they kneel and `playerDownedEnd` as they stand. Under a kneel relation, even the Killing Curse kneels. `pvpDefeat` fires with the victim, the player who defeated them and `"death"` or `"kneel"`. It credits a player whose hit the server accepted in the last few seconds, so a defeat nobody caused raises nothing. A policy's `minHp` under a death relation keeps the victim alive without a defeat. On the client, `localDowned` fires as the local player kneels and `localDownedEnd` as they get up. +### How long a kneel lasts + +The `kneelSeconds` rule sets how long a kneel lasts, 4 seconds by default. `0` keeps the loser kneeling until a script calls `player.endKneel()`, which stands a kneeling player up at once, for example when a medic reaches them. `endKneel` returns `false` for a player who is not kneeling. + +Either way, the player stands up at full health. To give them less, set it in `playerDownedEnd`: + +```js +// server/main.js +Pvp.configure({ defeat: "kneel", kneelSeconds: 0 }); + +// A medic's /revive stands a kneeling player up. +Events.on("chatCommand", (player, message, command, args) => { + if (command !== "revive") return; + const patient = PlayerManager.getAll().find((p) => p.nickname === args[0]); + if (!patient?.endKneel()) player.sendChat(`${args[0] ?? "Nobody"} is not kneeling.`); +}); + +// Back up from a kneel or a respawn with a quarter of their health, not all of it. +Events.on("playerDownedEnd", (player) => player.setHealth(Math.round(player.maxHealth / 4))); +``` + +For about 0.6 seconds after a player stands up, the game refuses a new kneel, so a hit in that time that should kneel them is lost. + ## Health recovery -Players get their health back by themselves, and every PvP hit pauses that for 10 seconds. `player.setHealthRecovery(false)` stops it until you set it back to `true`. A respawn or any trip to another map turns recovery back on, so set it again afterwards. +Players get their health back by themselves, and every PvP hit pauses that for 10 seconds. `player.setHealthRecovery(false)` stops it until you set it back to `true`. Their game keeps it off through respawns and trips to other maps. + +A trip to another map, such as through a dungeon door, gives the player a fresh body at full health. `player.setKeepHealthOnTravel(true)` carries their health over instead, and `player.getKeepHealthOnTravel()` reads it back. A respawn after a death still starts at full health, so set it in `playerDownedEnd` as above. Together they keep a player's health in your hands, as a roleplay server may want: + +```js +// server/main.js +Events.on("playerConnect", (player) => { + player.setHealthRecovery(false); + player.setKeepHealthOnTravel(true); +}); +``` ## Spell cooldowns diff --git a/guides/PvP/rules-and-relations.md b/guides/PvP/rules-and-relations.md index 20b4c98..f1f0664 100644 --- a/guides/PvP/rules-and-relations.md +++ b/guides/PvP/rules-and-relations.md @@ -22,6 +22,7 @@ Out of the box nobody can hurt anybody. PvP starts when a script sets rules or p | `defeat` | `"death"` | What losing does: the game's own `"death"`, or a `"kneel"` that the player gets up from | | `curses` | `"on"` | `"off"` stops the Killing, Cruciatus and Imperius curses doing anything to players | | `kneelHp` | 1 | The health at which a kneel defeat starts, and the health a kneeling player is held at | +| `kneelSeconds` | 4 | How long a [kneel](/guides/pvp/hits-and-defeat/#how-long-a-kneel-lasts) lasts; `0` keeps the player kneeling until `player.endKneel()` | | `flagCombatLockSeconds` | 15 | How long after a hit, given or taken, a player who drops their flag stays flagged, and stays in a fight for [spell cooldowns](/guides/pvp/hits-and-defeat/#spell-cooldowns) | | `spawnProtectionSeconds` | 5 | How long a player killed in PvP cannot be hurt once they are back up; their own hit ends it | | `damageScale` | 1 | Multiplies every spell's [damage](/guides/pvp/hits-and-defeat/#damage) |