🗡️ 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
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

Download Dcombat and drop the jar into your plugins/ folder.
Install PacketEvents and any optional plugins you want.
Start the server — plugins/Dcombat/config.yml and a wiki.txt reference will be generated automatically.
Edit config.yml to your liking.
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

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.

Dcombat

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details