pvp.yml¶

Combat: deathbans and their rank tiers, the combat tag, the strength nerf, knockback, attack speed, safe zones, loot protection and friendly fire.

How it plays: Combat · Deathbans and lives

Every example on this page is taken from the shipped pvp.yml. Changes apply with /hcf reload.

Switch¶

pvp.yml

# Turning this off disables the whole module: no deathbans, no combat tags, no
# combat tweaks.
enabled: true

enabled: false turns the whole module off: no deathbans, no combat tags, no combat tuning. SOTW's no-PvP rule still holds.

Deathban¶

pvp.yml

deathban:
  # Keep a player out of the server for a while after they die.
  enabled: true
  # Ban length for a player with no matching tier below.
  duration-seconds: 3600
  # Shorter bans for ranks. The SHORTEST matching tier wins, so granting a rank
  # is always a reduction and never accidentally a penalty. Only the nodes listed
  # here are checked, so an unrelated wildcard grant cannot silently shorten
  # somebody's ban.
  permission-tiers:
    hcfcore.deathban.tier.short: 900
  # Staff with hcfcore.deathban.bypass are never banned in the first place: the
  # permission is read at the death, where the player is still on the server. It
  # cannot be read at the login - the connection carries a profile, not a player -
  # so granting it to somebody who is already banned does not let them back in.
  # Clear that ban with /pvp lift <player>, which works from the console.

Key	As shipped	What it does
`enabled`	`true`	Deathbans at all
`duration-seconds`	`3600`	The ban for a player with no matching tier
`permission-tiers`	`hcfcore.deathban.tier.short: 900`	Permission node to ban length. The shortest tier a player holds wins; only the nodes listed are checked. Add your own

Combat tag¶

pvp.yml

combat-tag:
  enabled: true
  # How long a hit keeps a player in combat.
  duration-seconds: 30
  # Tag the attacker as well as the victim, so hitting someone commits you too.
  tag-attacker: true
  # What a tagged player who disconnects leaves behind - the reason the tag exists
  # at all: without it, a losing fight is escaped by pulling the plug.
  #   npc  - a stand-in where they stood, at full health (logger below). Killed,
  #          their items fall and they die - deathban, DTR, points, as for a kill -
  #          and find an empty inventory when they come back. Hit, both combat tags
  #          start over. Still standing when the tag runs out, it goes and they keep
  #          everything; back before that, they take its place, with the health
  #          they left with less the damage it took.
  #   kill - their death, at once.
  #   none - nothing.
  logout: npc
  logger:
    # Any living entity; it never walks or trades, and nothing but a player hurts it.
    entity: VILLAGER
    # Its health when it appears, whatever the player had - in half hearts: 20 is
    # ten hearts.
    health: 20
    # A blow pushes it back, as it would the player. false: it does not budge.
    knockback: true
  # Refuse plugin teleports (such as /team hq) while tagged.
  block-teleport: true

Key	As shipped	What it does
`enabled`	`true`	The combat tag at all
`duration-seconds`	`30`	How long a hit keeps a player in combat
`tag-attacker`	`true`	Tag the attacker as well as the victim
`logout`	`npc`	What a tagged player who logs out leaves: `npc` a stand-in that can be killed until the tag runs out, `kill` their death at once, `none` nothing. The old `kill-on-logout: true` reads as `npc`, `false` as `none`
`logger.entity`	`VILLAGER`	The stand-in: any living entity but a player
`logger.health`	`20`	Its health when it appears, whatever the player had, in half hearts
`logger.knockback`	`true`	A blow pushes it back as it would the player; `false`, it does not budge. It never walks either way
`block-teleport`	`true`	Refuse plugin teleports (`/team hq`, `/spawn`...) while tagged

Ender pearl cooldown¶

pvp.yml

# The HCF pearl cooldown: a wait between two ender pearls, shown on the
# scoreboard (%pearl_line%) and on Lunar Client. A partner item's Fake Pearl
# has its own and never starts this one.
ender-pearl-cooldown:
  enabled: true
  seconds: 15
  # The pearls in the hotbar show the wait, greyed out as the game shows its own.
  show-on-item: true
  # A death ends it.
  clear-on-death: true
  # Refuse plugin teleports (/spawn, /team hq, /team stuck, /top, /world) until
  # it is over: a pearl out of a fight is not followed by a command out of it.
  block-teleport: true

Key	As shipped	What it does
`enabled`	`true`	The pearl cooldown at all
`seconds`	`15`	The wait between two pearls
`show-on-item`	`true`	The pearls in the hotbar are greyed out for the wait, as the game shows its own
`clear-on-death`	`true`	A death ends it
`block-teleport`	`true`	Refuse plugin teleports (`/spawn`, `/team hq`, `/team stuck`, `/top`, `/world`) until it is over

Item cooldowns¶

pvp.yml

# A wait between two uses of an item: eaten (a golden apple, a chorus fruit) or,
# for a totem, saving its holder. Used again meanwhile, it is refused - a totem
# on cooldown saves nobody. The wait is kept on the player: an hour's Gapple
# survives logouts and restarts.
#
# Each item has an id - its scoreboard rows are %cooldown_<id>% (the time) and
# %cooldown_<id>_line% (a whole row, from lang/en.yml) - and:
#   material        the item
#   seconds         the wait
#   name            how the scoreboard and the messages call it
#   show-on-item    the items in the hotbar show the wait, greyed out as the
#                   game shows its own
#   clear-on-death  a death ends it
# Partner items (abilities.yml) are never counted: a Golden Head has its own.
item-cooldowns:
  enabled: true
  items:
    notch-apple:
      material: ENCHANTED_GOLDEN_APPLE
      seconds: 3600
      name: "{primary}Gapple"
      show-on-item: true
      clear-on-death: false
    golden-apple:
      material: GOLDEN_APPLE
      seconds: 10
      name: "{primary}Crapple"
      show-on-item: true
      clear-on-death: true
    chorus-fruit:
      material: CHORUS_FRUIT
      seconds: 15
      name: "{primary}Chorus"
      show-on-item: true
      clear-on-death: true
    totem:
      material: TOTEM_OF_UNDYING
      seconds: 120
      name: "{primary}Totem"
      show-on-item: true
      clear-on-death: false

Key	As shipped	What it does
`enabled`	`true`	Item cooldowns at all
`items.<id>`	Gapple, Crapple, chorus fruit, totem	One item. The id names it in `%cooldown_<id>%`, `%cooldown_<id>_line%` and `/cooldown reset`
`items.<id>.material`		The item; one cooldown per item
`items.<id>.seconds`	`3600` · `10` · `15` · `120`	The wait
`items.<id>.name`	`&6Gapple`…	How the scoreboard and the messages call it
`items.<id>.show-on-item`	`true`	The items in the hotbar are greyed out for the wait
`items.<id>.clear-on-death`	Gapple and totem `false`, others `true`	A death ends it

An item is used when it is eaten, or — a totem — when it saves its holder. The wait is kept on the player: it survives logouts and restarts.

Strength nerf¶

pvp.yml

strength-nerf:
  # The historic HCF nerf of Strength potions.
  enabled: true
  # ⚠️ Damage vanilla adds PER STRENGTH LEVEL. This module subtracts it and adds
  # its own figure instead.
  #
  # This is a config value on purpose. Mojang has changed the formula before (a
  # damage multiplier before 1.9, a flat bonus after), and the value for the
  # targeted version could not be confirmed against the official documentation
  # when this module was written, and a guess is not presented as fact here.
  # VERIFY IT for your server version and correct it here; no recompilation is
  # needed.
  vanilla-bonus-per-level: 3.0
  # Damage this module adds per level instead.
  nerfed-bonus-per-level: 1.5
  # (An "effect-names" list used to follow here, for servers whose API spelled
  # the Strength effect differently. It is read through Paper's STRENGTH constant
  # now, verified in the 26.2 sources, and the list is ignored if still present.)

Key	As shipped	What it does
`enabled`	`true`	The nerf at all
`vanilla-bonus-per-level`	`3.0`	The damage vanilla adds per Strength level, subtracted. Check it for your version
`nerfed-bonus-per-level`	`1.5`	The damage added per level instead

Knockback and attack speed¶

pvp.yml

knockback:
  # Scale knockback. Off by default: this changes the feel of combat, so it
  # should be a deliberate choice rather than something a server inherits.
  #
  # Only knockback from one player hitting another - with a weapon, a fist or a
  # projectile - is scaled, through Paper's own knockback event: the knockback
  # itself is scaled, not whatever else is moving the victim at that moment.
  enabled: false
  # 1.0 is vanilla.
  horizontal: 1.0
  vertical: 1.0

pvp.yml

attack-speed:
  # Every player's attack-speed attribute. Off by default: like knockback, this
  # changes how combat feels, so it should be a deliberate choice.
  #
  # The value replaces the player's base; the weapon in hand still adds its own
  # modifier on top (a sword lowers it). The higher the value, the shorter the
  # recharge between full-strength hits. Vanilla's base is 4 (the Minecraft Wiki's
  # figure - Paper does not document it; the plugin reads the real base at runtime
  # and only adds the difference). Servers after a pre-1.9 feel set a large value;
  # how large removes the recharge entirely is Mojang's formula, so try it.
  #
  # Given as a modifier that is never saved to player data: turning this off, or
  # removing the plugin, leaves nobody with a changed attribute.
  enabled: false
  value: 4.0

Key	As shipped	What it does
`knockback.enabled`	`false`	Scale the knockback of a player hitting a player
`knockback.horizontal`, `vertical`	`1.0`, `1.0`	Multipliers; `1.0` is vanilla
`attack-speed.enabled`	`false`	Replace every player's base attack speed
`attack-speed.value`	`4.0`	The base; vanilla's is 4. Higher recharges faster

Safe zones¶

pvp.yml

safe-zones:
  # Disable PvP on the land of server teams created as SAFE zones - spawn,
  # typically. Server teams created as COMBAT zones (warzone, roads, event
  # grounds) are fought on like anywhere else. Both are made the same way:
  #   /team createsystem <name> <safe|combat>, which hands over the claiming
  #   wand to draw its land (again later: /team forceclaim <name>),
  # and /team setzone <name> <safe|combat> switches one later. An event's
  # territory is a combat zone made by /events create or /events claim.
  # Turning this off makes every server team fightable, whatever its kind - and
  # takes the two rules below with it.
  enabled: true
  # No damage of any kind on safe-zone land: a fall, fire, drowning, suffocation,
  # a mob, a cactus. Spawn is where players sort themselves out between fights.
  # The void and /kill still land: a player fallen below spawn must not fall for ever.
  no-damage: true
  # Hunger never drops there, and is filled back up when a player walks, teleports
  # or logs in on safe-zone land. "heal" does the same with health.
  keep-fed: true
  heal: true
  # A player in combat cannot enter a safe zone until their tag runs out - the
  # classic HCF rule, so a fight is not ended by running home to spawn.
  block-combat-tagged: true
  # What they see of the border they may not cross: a wall, drawn like the
  # claiming wand's columns - sent to that player alone, never placed. Only the
  # part of the border within radius-blocks of them is drawn, all round: a ball of
  # wall where they stand, not a sheet up to the sky.
  wall:
    enabled: true
    material: RED_STAINED_GLASS
    radius-blocks: 15

Key	As shipped	What it does
`enabled`	`true`	No PvP on the land of a safe server team. `false` makes every server team fightable, whatever its kind — and takes the two below with it
`no-damage`	`true`	No damage of any kind there: a fall, fire, drowning, suffocation, a mob, a cactus. The void and `/kill` still land
`keep-fed`	`true`	Hunger never drops there, and is filled back up when a player walks, teleports or logs in on safe-zone land
`heal`	`true`	Health is filled back up there the same way
`block-combat-tagged`	`true`	A player in combat cannot enter a safe zone until their tag runs out
`wall.enabled`	`true`	Whether they see the border they may not cross, drawn like the claiming wand's columns — sent to that player alone, never placed
`wall.material`	`RED_STAINED_GLASS`	The block it is drawn in
`wall.radius-blocks`	`15`	The border's air blocks within this distance of the player are drawn, all round — a ball of wall where they stand. The older `width-blocks`, `top-y` and `minimum-height` are no longer read.

Death signs¶

pvp.yml

# A kill by a player leaves a sign: who died, to whom, and when - its four lines
# are in the language file (pvp.death-sign). The text is on the sign itself, so it
# stays when the sign is placed, and the sign is waxed: nobody rewrites it.
death-signs:
  enabled: true
  # Any standing or hanging sign.
  material: OAK_SIGN
  # false: among the dead player's drops, covered by loot protection like the rest.
  # true: straight into the killer's inventory (at their feet when it is full).
  to-killer: false
  # How %date% is written (Java DateTimeFormatter letters).
  date-format: "dd/MM/yyyy HH:mm"

Key	As shipped	What it does
`enabled`	`true`	A kill by a player leaves a sign
`material`	`OAK_SIGN`	Any standing or hanging sign
`to-killer`	`false`	`false`: among the dead player's drops, under loot protection. `true`: into the killer's inventory, at their feet when it is full
`date-format`	`dd/MM/yyyy HH:mm`	How `%date%` is written

The four lines are pvp.death-sign.line-1 to line-4 in the language file.

Loot protection¶

pvp.yml

# Anticlean - loot protection. For a few seconds after a kill, what the dead player
# drops can be picked up only by the killer (and, with team-shares, the killer's
# team): no other player, no mob, no hopper. Then it is ordinary loot. A death with
# no killer - lava, a fall - is not protected. The drops still fall where they
# always did; they only carry the claim.
loot-protection:
  enabled: true
  seconds: 10
  team-shares: true

Key	As shipped	What it does
`enabled`	`true`	Protect a kill's drops
`seconds`	`10`	How long only the killer may pick them up
`team-shares`	`true`	The killer's team may too

Friendly fire¶

pvp.yml

# Hits between players on the same side. The default rule:
# teammates never hurt each other, and allies only inside an event area - a running
# KOTH, Citadel or Conquest zone, or a hit on or by the King during Kill the King -
# since that is where allied teams compete (captures and the King are strictly per
# team). A refused hit does nothing and tags nobody.
friendly-fire:
  # Can teammates hurt each other?
  teammates: false
  # Where can allies hurt each other? ALWAYS, EVENT_AREAS or NEVER.
  allies: EVENT_AREAS

Key	As shipped	What it does
`teammates`	`false`	Whether teammates can hurt each other
`allies`	`EVENT_AREAS`	Where allies can hurt each other: `ALWAYS`, `EVENT_AREAS` (a running KOTH, Citadel or Conquest zone, and the King) or `NEVER`

The whole shipped file¶

View it on GitHub.

pvp.yml

# ---------------------------------------------------------------------------
# HCFCore - PvP / combat configuration
# ---------------------------------------------------------------------------
# Deathban, combat tag, strength nerf, safe zones, loot protection and
# anti-logout. Changes take effect on /hcf reload.
#
# Lines "# --8<-- [start:...]" and "# --8<-- [end:...]" mark the parts the online
# documentation quotes from this file. They are comments and change nothing.
# ---------------------------------------------------------------------------

# Turning this off disables the whole module: no deathbans, no combat tags, no
# combat tweaks.
enabled: true

deathban:
  # Keep a player out of the server for a while after they die.
  enabled: true
  # Ban length for a player with no matching tier below.
  duration-seconds: 3600
  # Shorter bans for ranks. The SHORTEST matching tier wins, so granting a rank
  # is always a reduction and never accidentally a penalty. Only the nodes listed
  # here are checked, so an unrelated wildcard grant cannot silently shorten
  # somebody's ban.
  permission-tiers:
    hcfcore.deathban.tier.short: 900
  # Staff with hcfcore.deathban.bypass are never banned in the first place: the
  # permission is read at the death, where the player is still on the server. It
  # cannot be read at the login - the connection carries a profile, not a player -
  # so granting it to somebody who is already banned does not let them back in.
  # Clear that ban with /pvp lift <player>, which works from the console.

combat-tag:
  enabled: true
  # How long a hit keeps a player in combat.
  duration-seconds: 30
  # Tag the attacker as well as the victim, so hitting someone commits you too.
  tag-attacker: true
  # What a tagged player who disconnects leaves behind - the reason the tag exists
  # at all: without it, a losing fight is escaped by pulling the plug.
  #   npc  - a stand-in where they stood, at full health (logger below). Killed,
  #          their items fall and they die - deathban, DTR, points, as for a kill -
  #          and find an empty inventory when they come back. Hit, both combat tags
  #          start over. Still standing when the tag runs out, it goes and they keep
  #          everything; back before that, they take its place, with the health
  #          they left with less the damage it took.
  #   kill - their death, at once.
  #   none - nothing.
  logout: npc
  logger:
    # Any living entity; it never walks or trades, and nothing but a player hurts it.
    entity: VILLAGER
    # Its health when it appears, whatever the player had - in half hearts: 20 is
    # ten hearts.
    health: 20
    # A blow pushes it back, as it would the player. false: it does not budge.
    knockback: true
  # Refuse plugin teleports (such as /team hq) while tagged.
  block-teleport: true

# The HCF pearl cooldown: a wait between two ender pearls, shown on the
# scoreboard (%pearl_line%) and on Lunar Client. A partner item's Fake Pearl
# has its own and never starts this one.
ender-pearl-cooldown:
  enabled: true
  seconds: 15
  # The pearls in the hotbar show the wait, greyed out as the game shows its own.
  show-on-item: true
  # A death ends it.
  clear-on-death: true
  # Refuse plugin teleports (/spawn, /team hq, /team stuck, /top, /world) until
  # it is over: a pearl out of a fight is not followed by a command out of it.
  block-teleport: true

# A wait between two uses of an item: eaten (a golden apple, a chorus fruit) or,
# for a totem, saving its holder. Used again meanwhile, it is refused - a totem
# on cooldown saves nobody. The wait is kept on the player: an hour's Gapple
# survives logouts and restarts.
#
# Each item has an id - its scoreboard rows are %cooldown_<id>% (the time) and
# %cooldown_<id>_line% (a whole row, from lang/en.yml) - and:
#   material        the item
#   seconds         the wait
#   name            how the scoreboard and the messages call it
#   show-on-item    the items in the hotbar show the wait, greyed out as the
#                   game shows its own
#   clear-on-death  a death ends it
# Partner items (abilities.yml) are never counted: a Golden Head has its own.
item-cooldowns:
  enabled: true
  items:
    notch-apple:
      material: ENCHANTED_GOLDEN_APPLE
      seconds: 3600
      name: "{primary}Gapple"
      show-on-item: true
      clear-on-death: false
    golden-apple:
      material: GOLDEN_APPLE
      seconds: 10
      name: "{primary}Crapple"
      show-on-item: true
      clear-on-death: true
    chorus-fruit:
      material: CHORUS_FRUIT
      seconds: 15
      name: "{primary}Chorus"
      show-on-item: true
      clear-on-death: true
    totem:
      material: TOTEM_OF_UNDYING
      seconds: 120
      name: "{primary}Totem"
      show-on-item: true
      clear-on-death: false

strength-nerf:
  # The historic HCF nerf of Strength potions.
  enabled: true
  # ⚠️ Damage vanilla adds PER STRENGTH LEVEL. This module subtracts it and adds
  # its own figure instead.
  #
  # This is a config value on purpose. Mojang has changed the formula before (a
  # damage multiplier before 1.9, a flat bonus after), and the value for the
  # targeted version could not be confirmed against the official documentation
  # when this module was written, and a guess is not presented as fact here.
  # VERIFY IT for your server version and correct it here; no recompilation is
  # needed.
  vanilla-bonus-per-level: 3.0
  # Damage this module adds per level instead.
  nerfed-bonus-per-level: 1.5
  # (An "effect-names" list used to follow here, for servers whose API spelled
  # the Strength effect differently. It is read through Paper's STRENGTH constant
  # now, verified in the 26.2 sources, and the list is ignored if still present.)

knockback:
  # Scale knockback. Off by default: this changes the feel of combat, so it
  # should be a deliberate choice rather than something a server inherits.
  #
  # Only knockback from one player hitting another - with a weapon, a fist or a
  # projectile - is scaled, through Paper's own knockback event: the knockback
  # itself is scaled, not whatever else is moving the victim at that moment.
  enabled: false
  # 1.0 is vanilla.
  horizontal: 1.0
  vertical: 1.0

attack-speed:
  # Every player's attack-speed attribute. Off by default: like knockback, this
  # changes how combat feels, so it should be a deliberate choice.
  #
  # The value replaces the player's base; the weapon in hand still adds its own
  # modifier on top (a sword lowers it). The higher the value, the shorter the
  # recharge between full-strength hits. Vanilla's base is 4 (the Minecraft Wiki's
  # figure - Paper does not document it; the plugin reads the real base at runtime
  # and only adds the difference). Servers after a pre-1.9 feel set a large value;
  # how large removes the recharge entirely is Mojang's formula, so try it.
  #
  # Given as a modifier that is never saved to player data: turning this off, or
  # removing the plugin, leaves nobody with a changed attribute.
  enabled: false
  value: 4.0

safe-zones:
  # Disable PvP on the land of server teams created as SAFE zones - spawn,
  # typically. Server teams created as COMBAT zones (warzone, roads, event
  # grounds) are fought on like anywhere else. Both are made the same way:
  #   /team createsystem <name> <safe|combat>, which hands over the claiming
  #   wand to draw its land (again later: /team forceclaim <name>),
  # and /team setzone <name> <safe|combat> switches one later. An event's
  # territory is a combat zone made by /events create or /events claim.
  # Turning this off makes every server team fightable, whatever its kind - and
  # takes the two rules below with it.
  enabled: true
  # No damage of any kind on safe-zone land: a fall, fire, drowning, suffocation,
  # a mob, a cactus. Spawn is where players sort themselves out between fights.
  # The void and /kill still land: a player fallen below spawn must not fall for ever.
  no-damage: true
  # Hunger never drops there, and is filled back up when a player walks, teleports
  # or logs in on safe-zone land. "heal" does the same with health.
  keep-fed: true
  heal: true
  # A player in combat cannot enter a safe zone until their tag runs out - the
  # classic HCF rule, so a fight is not ended by running home to spawn.
  block-combat-tagged: true
  # What they see of the border they may not cross: a wall, drawn like the
  # claiming wand's columns - sent to that player alone, never placed. Only the
  # part of the border within radius-blocks of them is drawn, all round: a ball of
  # wall where they stand, not a sheet up to the sky.
  wall:
    enabled: true
    material: RED_STAINED_GLASS
    radius-blocks: 15

# A kill by a player leaves a sign: who died, to whom, and when - its four lines
# are in the language file (pvp.death-sign). The text is on the sign itself, so it
# stays when the sign is placed, and the sign is waxed: nobody rewrites it.
death-signs:
  enabled: true
  # Any standing or hanging sign.
  material: OAK_SIGN
  # false: among the dead player's drops, covered by loot protection like the rest.
  # true: straight into the killer's inventory (at their feet when it is full).
  to-killer: false
  # How %date% is written (Java DateTimeFormatter letters).
  date-format: "dd/MM/yyyy HH:mm"

# Anticlean - loot protection. For a few seconds after a kill, what the dead player
# drops can be picked up only by the killer (and, with team-shares, the killer's
# team): no other player, no mob, no hopper. Then it is ordinary loot. A death with
# no killer - lava, a fall - is not protected. The drops still fall where they
# always did; they only carry the claim.
loot-protection:
  enabled: true
  seconds: 10
  team-shares: true

# Hits between players on the same side. The default rule:
# teammates never hurt each other, and allies only inside an event area - a running
# KOTH, Citadel or Conquest zone, or a hit on or by the King during Kill the King -
# since that is where allied teams compete (captures and the King are strictly per
# team). A refused hit does nothing and tags nobody.
friendly-fire:
  # Can teammates hurt each other?
  teammates: false
  # Where can allies hurt each other? ALWAYS, EVENT_AREAS or NEVER.
  allies: EVENT_AREAS