🗡️ Dcombat — Complete Wiki

A powerful combat plugin for Paper and Folia servers. Combat tag players, punish loggers, control drops, restrict abilities, render visual borders, and integrate with your existing server stack — all from a single config file.

---

📋 Table of Contents

• Requirements & Installation
• Commands & Permissions
• Configuration Reference
  • Settings
  • Pearl Settings
  • Trident Settings
  • Effect Settings
  • Death Settings
  • Drop Settings
  • Knockback Settings
  • Border Settings
  • Block Placement Settings
  • Crystal PvP Settings
  • Command Settings
  • Admin Settings
  • Region Settings
  • Combat Settings
  • Inventory Settings
  • Placeholder Settings
  • Messages Settings
  • Lifesteal Settings
• PlaceholderAPI
• Developer API
• Plugin Integrations
• License

---

📦 Requirements & Installation

Requirements

Requirement	Details
Java	21 or newer
Server	Paper or Folia — API 1.19+
PacketEvents	⚠️ Required — must be installed

Optional integrations (the plugin loads fine without these):

Plugin	Purpose
PlaceholderAPI	Enables %dcombat_*% placeholders
WorldGuard	Region-based combat blocking
Lands	Claim-based safe zone support
Vault	Economy integration hook
LifestealCore	Heart-stealing on combat kills

Installation

1. Download Dcombat and drop the jar into your plugins/ folder.
2. Install PacketEvents and any optional plugins you want.
3. Start the server — plugins/Dcombat/config.yml and a wiki.txt reference will be generated automatically.
4. Edit config.yml to your liking.
5. Run /dcombat reload to apply changes without a restart.

---

⌨️ Commands & Permissions

All commands use the root label /combatlog (alias: /combat).

Admin Commands

Command	Permission	Description
/combatlog reload	dcombat.reload	Reload the configuration
/combatlog status <player>	dcombat.status	Check if a player is combat-tagged
/combatlog tag <player>	dcombat.tag	Manually tag a player
/combatlog tag <player1> <player2>	dcombat.tag	Mutually tag two players against each other
/combatlog untag <player>	dcombat.untag	Remove a player's combat tag
/combatlog untagall	dcombat.untagall	Remove all active combat tags
/combatlog stats	dcombat.stats	Show how many players are currently in combat

Tag-Out Commands

Tag-out grants a player temporary immunity from being combat-tagged.

Command	Permission	Description
/tagout <duration>	dcombat.tagout	Grant yourself tag-out immunity
/tagout <player> <duration>	dcombat.tagout	Grant another player tag-out immunity
/tagout remove	dcombat.tagout	Remove your own tag-out immunity
/tagout remove <player>	dcombat.tagout	Remove another player's tag-out immunity

Alias: /tagout can also be used as /tagimmunity

Bypass Permission

Permission	Effect
dcombat.bypass.admin	Player can never be combat-tagged (requires excludeAdminsFromCombat: true in config)

---

⚙️ Configuration Reference

After making changes, run /combatlog reload. A wiki.txt quick-reference is also written to the plugin's data folder automatically.

---

1️⃣ Settings

settings:
  notifyAboutUpdates: true
  combatTimerDuration: 20s
  ignoredWorlds:
    - your_world

Key	Type	Default	Description
notifyAboutUpdates	boolean	true	Notify server operators when a new version is available
combatTimerDuration	Duration	20s	How long a player stays tagged after their last PvP interaction. Format: 15s, 1m, 1h
ignoredWorlds	list	[your_world]	Worlds where combat tagging is completely disabled

---

2️⃣ Pearl Settings

pearl:
  pearlThrowDamageEnabled: true
  pearlThrowDisabledDuringCombat: true
  pearlCooldownEnabled: false
  pearlExtendsCombatTag: false
  pearlThrowDelay: 3s

Key	Type	Default	Description
pearlThrowDamageEnabled	boolean	true	Ender pearl landing deals damage to the thrower
pearlThrowDisabledDuringCombat	boolean	true	Block pearl throws while in combat
pearlCooldownEnabled	boolean	false	Enable a cooldown between pearl throws
pearlExtendsCombatTag	boolean	false	Throwing a pearl during combat resets the timer
pearlThrowDelay	Duration	3s	Cooldown length between throws (when pearlCooldownEnabled: true)

---

3️⃣ Trident Settings

trident:
  tridentRiptideDisabledDuringCombat: false
  tridentRiptideExtendsCombatTag: false
  tridentRiptideDelay: 10s

Key	Type	Default	Description
tridentRiptideDisabledDuringCombat	boolean	false	Block riptide while in combat
tridentRiptideExtendsCombatTag	boolean	false	Using riptide during combat resets the timer
tridentRiptideDelay	Duration	10s	Cooldown between riptide uses

---

4️⃣ Effect Settings

effect:
  customEffectsEnabled: false
  customEffects:
    SPEED: 1
    RESISTANCE: 0

Key	Type	Default	Description
customEffectsEnabled	boolean	false	Apply potion effects to players while they are in combat
customEffects	map	SPEED:1, RESISTANCE:0	PotionEffectType → amplifier. Amplifier 0 = Level I, 1 = Level II, etc.

---

5️⃣ Death Settings

Controls visual effects triggered on player death.

death:
  lightning:
    afterEveryDeath: false
    inCombat: true
  firework:
    afterEveryDeath: false
    inCombat: false
    power: 2
    fireworkType: BALL
    primaryColor: "#a80022"
    fadeColor: "#0a0a0a"
    particlesEnabled: true
    mainParticle: CAMPFIRE_COSY_SMOKE
    mainParticleCount: 3
    secondaryParticle: SMALL_FLAME
    secondaryParticleCount: 3

⚡ Lightning

Key	Type	Default	Description
lightning.afterEveryDeath	boolean	false	Strike lightning on every player death
lightning.inCombat	boolean	true	Strike lightning only on combat deaths

🎆 Firework

Key	Type	Default	Description
firework.afterEveryDeath	boolean	false	Spawn a firework on every player death
firework.inCombat	boolean	false	Spawn a firework only on combat deaths
firework.power	int	2	Firework flight power / duration
firework.fireworkType	FireworkEffect.Type	BALL	Shape: BALL, BALL_LARGE, STAR, CREEPER, BURST
firework.primaryColor	hex	#a80022	Primary explosion color
firework.fadeColor	hex	#0a0a0a	Fade-out color
firework.particlesEnabled	boolean	true	Emit ambient particles alongside the firework
firework.mainParticle	XParticle	CAMPFIRE_COSY_SMOKE	Primary particle type
firework.mainParticleCount	int	3	Primary particles per tick
firework.secondaryParticle	XParticle	SMALL_FLAME	Secondary particle type
firework.secondaryParticleCount	int	3	Secondary particles per tick

---

6️⃣ Drop Settings

Controls how a player's inventory is handled when they die during combat.

drop:
  dropEventPriority: NORMAL
  dropType: UNCHANGED
  dropItemPercent: 100
  playersHealthPercentClamp: 20
  affectExperience: false

Key	Type	Default	Description
dropEventPriority	EventPriority	NORMAL	Bukkit priority for the drop handler
dropType	enum	UNCHANGED	Drop behavior mode (see table below)
dropItemPercent	int	100	% of items the victim keeps when dropType: PERCENT. Lower = more items dropped
playersHealthPercentClamp	int	20	Minimum % of items always kept in PLAYERS_HEALTH mode — prevents full inventory loss
affectExperience	boolean	false	Apply the drop modifier to experience orbs as well

dropType options:

Value	Behavior
UNCHANGED	Vanilla drop behavior — no changes
PERCENT	A fixed % of items are dropped, set by dropItemPercent
PLAYERS_HEALTH	Drop % scales with the victim's remaining health, clamped by playersHealthPercentClamp

---

7️⃣ Knockback Settings

knockback:
  multiplier: 1.0
  vertical: 0.2
  forceTeleport:
    delay: 1s
    unsafeGroundBlocks: []
    airBlocks: []

Key	Type	Default	Description
multiplier	double	1.0	Global knockback strength multiplier
vertical	double	0.2	Vertical knockback component
forceTeleport.delay	Duration	1s	Delay before a safe-teleport check fires after knocking a player near an unsafe area
forceTeleport.unsafeGroundBlocks	list of XMaterial	[]	Block types considered unsafe to land on
forceTeleport.airBlocks	list of XMaterial	[]	Block types treated as air (also triggers safe-teleport)

---

8️⃣ Border Settings

A visual border rendered around the player while they are in combat.

border:
  distance: 6.5
  block:
    # block-based border animation options
  particle:
    # particle-based border animation options

Key	Type	Default	Description
distance	double	6.5	Distance from the player where the border is rendered
block	section	—	Configuration for the block-based border animation
particle	section	—	Configuration for the particle-based border animation

---

9️⃣ Block Placement Settings

blockPlacement:
  disableBlockPlacing: true
  blockPlacementMode: ABOVE
  blockPlacementModeDisplayName: "above"
  blockPlacementYCoordinate: 40
  restrictedBlockTypes: []

Key	Type	Default	Description
disableBlockPlacing	boolean	true	Prevent block placement while in combat
blockPlacementMode	enum	ABOVE	ABOVE — cannot place above the Y limit. BELOW — cannot place below the Y limit
blockPlacementModeDisplayName	string	above	Display name shown in messages for the current mode
blockPlacementYCoordinate	int	40	The Y-level used as the boundary
restrictedBlockTypes	list of Material	[]	Specific materials that can never be placed during combat, regardless of Y level

---

💎 Crystal PvP Settings

crystalPvp:
  tagFromCrystals: true
  tagFromRespawnAnchor: true

Key	Type	Default	Description
tagFromCrystals	boolean	true	End crystal explosions tag the player who placed/triggered them
tagFromRespawnAnchor	boolean	true	Respawn anchor explosions tag the responsible player

---

🚫 Command Settings

command:
  commandRestrictionMode: BLACKLIST
  restrictedCommands:
    - spawn
    - home

Key	Type	Default	Description
commandRestrictionMode	enum	BLACKLIST	BLACKLIST — all commands allowed except listed. WHITELIST — only listed commands are allowed
restrictedCommands	list	[]	Commands to restrict. Do not include the leading /

---

🛡️ Admin Settings

admin:
  excludeAdminsFromCombat: false
  excludeCreativePlayersFromCombat: false

Key	Type	Default	Description
excludeAdminsFromCombat	boolean	false	Players with dcombat.bypass.admin are never tagged
excludeCreativePlayersFromCombat	boolean	false	Players in Creative mode are never tagged

---

🗺️ Region Settings

Requires WorldGuard to be installed.

region:
  blockedRegions:
    - your_region
  preventPvpInRegions: true
  restrictedRegionRadius: 10

Key	Type	Default	Description
blockedRegions	list	[your_region]	WorldGuard region names where combat tagging is disabled
preventPvpInRegions	boolean	true	Prevent PvP from starting inside blocked regions
restrictedRegionRadius	int	10	Radius (in blocks) around blocked regions where combat is also prevented

---

⚔️ Combat Settings

combat:
  releaseAttackerOnVictimDeath: true
  disableElytraUsage: true
  disableElytraOnDamage: true
  disableFlying: true
  unequipElytraOnCombat: true
  disableFireworks: true
  enableDamageCauseLogging: false
  damageCauseRestrictionMode: WHITELIST
  loggedDamageCauses: []
  ignoredProjectileTypes:
    - ENDER_PEARL
    - EGG
  quitPunishmentEventPriority: NORMAL
  whitelistedKickReasons: []

Key	Type	Default	Description
releaseAttackerOnVictimDeath	boolean	true	When the victim dies, the attacker is also untagged
disableElytraUsage	boolean	true	Prevent all elytra use while in combat
disableElytraOnDamage	boolean	true	Cancel elytra gliding when the player takes damage
disableFlying	boolean	true	Disable /fly mode while in combat
unequipElytraOnCombat	boolean	true	Force-unequip the chestplate slot on combat entry
disableFireworks	boolean	true	Block firework rocket use during combat
enableDamageCauseLogging	boolean	false	Log every damage cause to console (useful for debugging tagging triggers)
damageCauseRestrictionMode	enum	WHITELIST	WHITELIST — only listed causes tag. BLACKLIST — all causes except listed tag
loggedDamageCauses	list of DamageCause	[]	Damage causes affected by the restriction mode
ignoredProjectileTypes	list of EntityType	ENDER_PEARL, EGG	Projectiles that do not trigger a combat tag
quitPunishmentEventPriority	EventPriority	NORMAL	Event priority for the logout-punishment handler
whitelistedKickReasons	list	[]	Server kick messages that will not be treated as a combat logout

---

🎒 Inventory Settings

inventory:
  inventoryAccessMode: ALLOW_ALL
  restrictedInventoryTypes:
    - CHEST
    - ENDER_CHEST

Key	Type	Default	Description
inventoryAccessMode	enum	ALLOW_ALL	ALLOW_ALL — players can open anything. RESTRICT — certain containers are blocked
restrictedInventoryTypes	list of InventoryType	[]	Containers blocked in RESTRICT mode (e.g. CHEST, ENDER_CHEST, BARREL, SHULKER_BOX)

---

💬 Placeholder Settings

placeholders:
  isInCombatFormattedTrue: "In Combat"
  isInCombatFormattedFalse: "Not In Combat"

Key	Type	Default	Description
isInCombatFormattedTrue	string	In Combat	Text returned by %dcombat_isInCombat_formatted% when the player is tagged
isInCombatFormattedFalse	string	Not In Combat	Text returned by %dcombat_isInCombat_formatted% when the player is not tagged

---

📢 Messages Settings

All messages use MiniMessage formatting and can target chat, action bar, title, or play a sound.

Available placeholders:

Placeholder	Description
{PLAYER}	Target player's name
{TIME}	Duration value
{PERMISSION}	Missing permission node
{USAGE}	Correct command usage
{Y}	Y-level coordinate
{MODE}	Block placement mode name
{COUNT}	Number of players
{FIRST_PLAYER}	First player in a dual-tag
{SECOND_PLAYER}	Second player in a dual-tag

Message keys:

Key	When it's sent
onlyForPlayers	A console used a player-only command
adminTagPlayer	Admin tags a single player
adminTagMultiplePlayers	Admin mutually tags two players
adminUntagPlayer	Admin untags a player
adminUntagAll	Admin untags everyone
adminPlayerNotInCombat	Target wasn't combat-tagged
playerInCombat	Status check — player is tagged
playerNotInCombat	Status check — player is not tagged
adminCannotTagSelf	Admin tried to include themselves in a dual-tag
adminTagOutSelf	Admin granted themselves tag-out immunity
adminTagOut	Admin granted a player tag-out immunity
playerTagOut	Sent to the player who received immunity
adminTagOutOff	Admin removed a player's tag-out immunity
playerTagOutOff	Sent to the player whose immunity was removed
adminTagOutCanceled	Tag command blocked because the target has immunity
combatStats	Response to /combatlog stats

---

❤️ Lifesteal Settings

Requires LifestealCore to be installed.

lifesteal:
  enabled: false
  heartsToSteal: 1
  stealOnlyInCombat: true
  stealOnKill: true
  stealOnDeath: false
  eliminateOnZeroHearts: true
  notifyOnKill: true

Key	Type	Default	Description
enabled	boolean	false	Master toggle for LifestealCore integration
heartsToSteal	int	1	Hearts transferred from victim to killer on death
stealOnlyInCombat	boolean	true	Only steal hearts when at least one party is combat-tagged
stealOnKill	boolean	true	Killer gains hearts on kill
stealOnDeath	boolean	false	Victim loses hearts on death regardless of stealOnKill
eliminateOnZeroHearts	boolean	true	Victim is eliminated (banned by LifestealCore) when their hearts hit zero
notifyOnKill	boolean	true	Send a chat notification when hearts are stolen

---

📊 PlaceholderAPI

Requires PlaceholderAPI to be installed. The identifier is dcombat.

Placeholder	Returns
%dcombat_isInCombat%	true or false
%dcombat_isInCombat_formatted%	Your configured isInCombatFormattedTrue / isInCombatFormattedFalse strings
%dcombat_remaining_seconds%	Seconds left on the combat timer (empty when not tagged)
%dcombat_remaining_millis%	Milliseconds left on the combat timer (empty when not tagged)
%dcombat_opponent%	Name of the player who tagged this player (empty when not tagged)
%dcombat_opponent_health%	Opponent's current health, to 2 decimal places (empty when not tagged)

---

🔧 Developer API

Dcombat exposes a DcombatApi interface for other plugins.

DcombatApi api = DcombatProvider.get();

FightManager           fightManager  = api.getFightManager();
RegionProvider         regions       = api.getRegionProvider();
PearlService           pearls        = api.getFightPearlService();
FightTagOutService     tagOut        = api.getFightTagOutService();
FightEffectService     effects       = api.getFightEffectService();
DropService            drops         = api.getDropService();
DropKeepInventoryService keepInv     = api.getDropKeepInventoryService();

Events

FightTagEvent — fired when a player is combat-tagged (cancellable)

@EventHandler
public void onTag(FightTagEvent event) {
    UUID player = event.getPlayer();
    CauseOfTag cause = event.getCause(); // PVP, COMMAND, etc.
    event.setCancelled(true); // prevent the tag
}

FightUntagEvent — fired when a player's combat tag is removed (cancellable)

@EventHandler
public void onUntag(FightUntagEvent event) {
    UUID player = event.getPlayer();
    CauseOfUnTag cause = event.getCause(); // DEATH, TIMER, COMMAND, etc.
}

BorderShowAsyncEvent / BorderHideAsyncEvent

Fired asynchronously when the visual combat border is shown or hidden for a player.

---

🔌 Plugin Integrations

Plugin	Status	What it enables
PacketEvents	⚠️ Required	Packet-level elytra blocking, flying control, border rendering
PlaceholderAPI	Optional	%dcombat_*% placeholder expansion
WorldGuard	Optional	blockedRegions and restrictedRegionRadius functionality
Lands	Optional	Claim boundaries used as combat-safe zones
Vault	Optional	Economy integration hook
LifestealCore	Optional	Heart-stealing on combat kills

---

📄 License

Copyright (c) 2026 Devamy. All rights reserved.

This project is proprietary source code. No permission is granted to copy, modify, distribute, sell, sublicense, or claim this code as someone else's work without prior written permission from the copyright holder.