⬇️   DOWNLOAD THE LATEST JAR   ⬇️

A lightweight combat-tag plugin for Paper SMPs. No enderchest rearming · No combat logging · No cheap escapes.

Note

Built for SMPs where "he pearled into his enderchest and rearmoured mid-fight" is a real problem. When two players fight, CombatRestrict locks the tools that turn a losing fight into a free getaway - and kills anyone who ragequits to save their gear.

---

📖 Table of Contents

✨ Why CombatRestrict 🎯 Features ⚙️ Requirements 🚀 Installation

🔖 How the Combat Tag Works 🚫 What Gets Restricted 💻 Commands & Permissions 🛠️ Configuration

🎨 Messages & Formatting 📦 Config Recipes ❓ FAQ 🧱 Building from Source

---

✨ Why CombatRestrict

The problem Your players fight. One of them starts losing. Then they: 🎒 pop their enderchest and pull out fresh gear 🛏️ slap down a bed or respawn anchor 📦 crack open a shulker for a rearm 🔌 alt-F4 at two hearts to keep their loot Every fight becomes a stalemate no one can actually win.

The fix CombatRestrict tags both players the instant damage lands. While tagged, all of that is blocked - and combat loggers just die. ✅ Blocks placing, opening & breaking the escape blocks ✅ Kills players who disconnect mid-fight ✅ Frees you the moment your last opponent dies ✅ Every timer, block and message is configurable

---

🎯 Features

	Feature	Details
⚔️	Smart combat tagging	Melee, projectiles, TNT, harmful splash & lingering potions, and optionally pets
🧠	Opponent tracking	Knows who you're fighting - win a 1v1 and you're freed instantly, no standing around
🎒	Block restrictions	Stop placing / opening / breaking enderchests, beds, anchors, shulkers - your list
💀	Combat-log punishment	Quit while tagged and you die on the spot, with an optional server broadcast
🛡️	Bypass permission	Staff in creative or event worlds never get tagged
🎨	Full MiniMessage support	Gradients, hover text, colours - style every message
⚡	Reload on the fly	/combatrestrict reload - no restart needed
🪶	Featherweight	Concurrent tag map, early-exit listeners, zero measurable TPS cost

---

⚙️ Requirements

• 🧩 Paper 1.20.5+ (or a fork like Purpur / Pufferfish)
• ☕ Java 17 or newer

Warning

Spigot is not supported - CombatRestrict uses Paper's bundled Adventure/MiniMessage for messages.

---

🚀 Installation

1.  Download CombatRestrict.jar from the Releases page
2.  Drop it into your server's  /plugins  folder
3.  Restart the server
4.  Edit  /plugins/CombatRestrict/config.yml
5.  Run  /combatrestrict reload   - no restart needed

On startup the console confirms what loaded:

[CombatRestrict] Enabled. Combat duration: 15.0s, 4 blocked place material(s), 12 blocked interact material(s).

Typo a block name? It warns and skips instead of breaking:

[CombatRestrict] config.yml restrictions.blocked-place: 'ENDR_CHEST' - unknown material, skipping.

---

🔖 How the Combat Tag Works

Getting tagged

A player is tagged when they deal damage to another player. What counts is up to you:

Source	Config option	Default
Melee / direct hits	always on	✅
Arrows, tridents, snowballs, eggs	tag-on-projectile	✅
Harmful splash potions	tag-on-splash-potion	✅
Harmful lingering clouds	tag-on-splash-potion	✅
Player-primed TNT	always on	✅
Tamed pets (wolves, etc.)	tag-on-pet-damage	❌

Harmful effects (Poison, Wither, Slowness, Instant Damage, and the newer 1.21 ones) are detected properly - throwing a healing potion at a teammate never tags you. Hits that deal 0 final damage (shield blocks, invuln frames) are ignored by default.

Staying tagged

The tag lasts combat.duration seconds. With refresh-on-hit: true every new hit resets the timer to full, so a long brawl keeps both players locked the whole time. Set it false for a hard cap from the first hit.

Getting untagged

The tag ends when:

• ⏱️ the timer runs out
• 💀 the player dies (clear-on-death)
• 🏆 their last opponent dies - win your fight, walk away free (end-combat-when-opponent-dies)
• 🔌 they disconnect - but see combat logging below
• 🛠️ an admin runs /combatrestrict clear <player>

Combat logging

With punish-combat-log.enabled on, quitting while tagged sets the player's health to 0 - they die, drop their gear, and the fight is settled. With broadcast: true the whole server sees it:

Steve logged out while in combat and died.

---

🚫 What Gets Restricted

While a player is restricted, these are blocked:

Action	Controlled by
Placing a block from blocked-place	always active
Right-clicking / opening a block from blocked-interact	always active
Opening an inventory type in blocked-inventory-types (reliable enderchest catch)	always active
Breaking a blocked-interact block	block-breaking (off by default)
Dispensers firing a blocked item near a tagged player	block-dispensers + dispenser-radius

Denied actions send a rate-limited chat message naming the block - "You can't open Ender Chest for 8s" - so spam-clicking never floods chat.

✍️ Writing block lists

All list options accept three formats, mixed freely:

restrictions:
  blocked-place:
    - RESPAWN_ANCHOR          # 1) exact material name
    - "*_BED"                 # 2) wildcard - every bed colour
    - "#minecraft:beds"       # 3) vanilla block/item tag

Unknown entries are logged and skipped, so one bad line never breaks the rest of your config.

---

💻 Commands & Permissions

Base command: /combatrestrict  ·  everything has tab completion.

Command	Description
/combatrestrict reload	Reload config.yml and report what loaded
/combatrestrict check [player]	Show combat status, time left & who they're fighting
/combatrestrict clear <player>	Remove one player's tag
/combatrestrict clear *	Remove every active tag

Steve is in combat - combat: 9s, restricted for 9s, fighting: Alex, Herobrine

Permission	Meaning
combatrestrict.bypass	Never tagged, never restricted. Give it to staff or creative/event worlds.

---

🛠️ Configuration

📄 Click to expand the full config.yml

combat:
  # How long the combat tag lasts, in seconds. Decimals allowed.
  duration: 15

  # Keep restrictions active this many extra seconds AFTER the tag expires.
  extra-restriction-seconds: 0

  # true  = every new hit resets the timer to full (recommended)
  # false = timer starts on the first hit and never extends
  refresh-on-hit: true

  # Who gets tagged when damage happens
  tag-attacker: true
  tag-victim: true

  # What counts as combat
  tag-on-projectile: true      # arrows, tridents, snowballs...
  tag-on-splash-potion: true   # harmful splash + lingering potions only
  tag-on-pet-damage: false     # tamed wolves etc. tag their owner

  # Ignore hits that deal no real damage (shield blocks, invulnerability frames)
  ignore-zero-damage: true

  punish-combat-log:
    enabled: true      # kill players who quit while tagged
    broadcast: true    # announce it to the server

  clear-on-death: true                 # wipe a player's tag when they die
  end-combat-when-opponent-dies: true  # free a player when their last opponent dies

restrictions:
  # Blocks/items that cannot be PLACED while restricted
  blocked-place:
    - RESPAWN_ANCHOR
    - "#minecraft:beds"
    - ENDER_CHEST
    - "*_SHULKER_BOX"
    - SHULKER_BOX

  # Blocks that cannot be RIGHT-CLICKED or OPENED while restricted
  blocked-interact:
    - ENDER_CHEST
    - CRAFTING_TABLE
    - ANVIL
    - ENCHANTING_TABLE
    - GRINDSTONE
    - SMITHING_TABLE
    - "#minecraft:beds"
    - RESPAWN_ANCHOR
    - "*_SHULKER_BOX"
    - SHULKER_BOX

  # Inventory types to block by type (best way to catch ender chests)
  blocked-inventory-types:
    - ENDER_CHEST

  block-breaking: false      # also block breaking the blocked-interact blocks?
  block-dispensers: true     # stop dispensers placing blocked items near tagged players
  dispenser-radius: 6.0

messages:
  prefix: "<dark_gray>[<red>Combat</red>]</dark_gray> "
  cooldown-seconds: 1.5      # min seconds between denial messages

  tagged: "<red>You are now in combat with <white><opponent></white> for <white><seconds>s</white>."
  untagged: "<green>You are no longer in combat."
  deny-place: "<red>You can't place <white><block></white> for another <white><seconds>s</white>."
  deny-interact: "<red>You can't use <white><block></white> for another <white><seconds>s</white>."
  deny-break: "<red>You can't break <white><block></white> for another <white><seconds>s</white>."
  combat-log-self: "<red>You logged out while in combat and died."
  combat-log-broadcast: "<red><player> logged out while in combat and died."

debug: false

📋 Config reference tables

combat

Key	Type	Default	Description
duration	number	15	Tag length in seconds
extra-restriction-seconds	number	0	Restrictions persist this long after the tag ends
refresh-on-hit	bool	true	Reset the timer on every hit
tag-attacker / tag-victim	bool	true	Which side gets tagged
tag-on-projectile	bool	true	Arrows, tridents, snowballs, eggs
tag-on-splash-potion	bool	true	Harmful splash & lingering potions
tag-on-pet-damage	bool	false	Tamed pets tag their owner
ignore-zero-damage	bool	true	Skip hits with 0 final damage
punish-combat-log.enabled	bool	true	Kill players who quit while tagged
punish-combat-log.broadcast	bool	true	Announce combat logs server-wide
clear-on-death	bool	true	Wipe the dead player's own tag
end-combat-when-opponent-dies	bool	true	Free a player when their last opponent dies

restrictions

Key	Type	Default	Description
blocked-place	list	-	Materials that can't be placed
blocked-interact	list	-	Blocks that can't be opened/right-clicked
blocked-inventory-types	list	-	Bukkit InventoryType names to block
block-breaking	bool	false	Also block breaking those blocks
block-dispensers	bool	true	Block dispensers near restricted players
dispenser-radius	number	6.0	Radius in blocks for that check

---

🎨 Messages & Formatting

Every message supports MiniMessage (<red>, <gradient:red:gold>, <bold>, <hover:show_text:'...'>) and legacy codes (&c, &l). The plugin auto-detects - if a line has & or § it's parsed as legacy, otherwise MiniMessage. Don't mix both in one line. Set any message to "" to disable it.

Placeholder	Available in
<opponent>	tagged
<seconds>	tagged, deny-place, deny-interact, deny-break
<block>	deny-place, deny-interact, deny-break
<player>	deny-*, combat-log-self, combat-log-broadcast

Block names auto-prettify - ENDER_CHEST → Ender Chest.

---

📦 Config Recipes

🟢 Vanilla-ish SMP - just stop the enderchest rearm

combat: { duration: 15 }
restrictions:
  blocked-place: [ENDER_CHEST, "*_SHULKER_BOX", SHULKER_BOX]
  blocked-interact: [ENDER_CHEST, "*_SHULKER_BOX", SHULKER_BOX]
  blocked-inventory-types: [ENDER_CHEST]

🔴 Anarchy / hardcore PvP - lock everything down

combat:
  duration: 30
  tag-on-pet-damage: true
restrictions:
  block-breaking: true
  blocked-place: ["#minecraft:beds", RESPAWN_ANCHOR, ENDER_CHEST, "*_SHULKER_BOX", SHULKER_BOX, CHEST, TRAPPED_CHEST, BARREL]
  blocked-interact: [ENDER_CHEST, CHEST, TRAPPED_CHEST, BARREL, "*_SHULKER_BOX", ANVIL, CRAFTING_TABLE, ENCHANTING_TABLE, GRINDSTONE, SMITHING_TABLE]

🟡 Casual server - no combat-log kill, gentle rules

combat:
  duration: 10
  punish-combat-log: { enabled: false }
restrictions:
  blocked-place: [RESPAWN_ANCHOR, "#minecraft:beds"]
  blocked-interact: [ENDER_CHEST]
  blocked-inventory-types: [ENDER_CHEST]

🔵 Team fights - attacker only, so getting sniped doesn't lock you

combat:
  tag-attacker: true
  tag-victim: false

---

❓ FAQ

Does this stop teleporting / /home?

No - CombatRestrict handles blocks, inventories and combat logging. Pair it with your essentials plugin's combat-teleport setting for command blocking.

Will it conflict with another combat-tag plugin?

It can double up on combat-log kills. Pick one plugin to own the punishment and disable it in the other.

Does it respect claims / WorldGuard?

Yes. It listens at HIGH priority and ignores already-cancelled events, so region protection runs first. Hits cancelled by PvP-off regions never tag anyone.

Does it save tags across restarts?

No - tags live in memory and clear on join, by design. A restart is not a combat log.

A player is stuck tagged after a lag spike.

/combatrestrict clear <player>, or /combatrestrict clear * for everyone.

Does it cause lag?

No. Tags live in a concurrent map, cleanup runs twice a second, and listeners exit early when the block isn't on your lists.

---

🧱 Building from Source

git clone https://github.com/SockyWoccky7/CombatRestrict.git
cd CombatRestrict
mvn clean package

The compiled jar lands in target/.

---

📜 License

Released under the MIT License - see LICENSE.

Made for SMPs that are tired of unwinnable fights.

⭐ If CombatRestrict helps your server, drop a star! ⭐