Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!

TrueCombatManager

Lightweight PvP combat system with timers, combat tags, escape blocking, alerts, and full customization for fair fights.

True Combat Manager

The Ultimate PvP Combat Management Plugin - Zero Lag, Maximum Features

🎯 Overview

A comprehensive, high-performance PvP combat plugin featuring real-time combat tracking, newbie protection, smart restrictions, visual feedback, statistics tracking, and combat replay system. Optimized for zero lag with intelligent logging system and async operations.

Perfect for practice servers, factions, KitPvP, or any PvP-focused gameplay.

✨ Complete Feature List

⚔️ Combat Management

Real-time combat detection and tracking
Configurable combat duration (default: 30s)
Automatic timer reset on damage
Lag compensation system (TPS monitoring)
Combat logging protection (instant death on logout)
Automatic combat end on death
Concurrent session management (unlimited fights)
Thread-safe architecture
Minimum damage threshold (0.5 hearts)

🛡️ Newbie Protection System

Protects players without armor from PvP
XP level threshold (configurable, default: 3)
Prevents damage dealing by newbies
Prevents damage receiving by newbies
Requires at least 1 armor piece (configurable)
Bypass permission support
Custom messages for attackers and defenders
Detailed logging for debugging

🚫 Smart Restrictions (All Configurable)

Tridents - Block throwing & riptide enchantment
Ender Pearls - Block usage & safezone teleportation (10s cooldown, 20s in combat)
Respawn Anchors - Block usage during combat
Elytra - Block gliding & firework boosts
End Crystals - Block placement/breaking
Golden Apples - Configurable cooldowns (3s base, 4.5s combat)
Enchanted Golden Apples - Separate cooldowns (4s base, 8s combat)
Commands - Block teleport commands (/tp, /home, /spawn, /warp)
Safezones - Prevent entry with visual glass barriers
Creative Mode - Auto-switch to survival during combat
Block Breaking/Placing - Optional restrictions

🎨 Visual System

6 Built-in Themes:
- Default - Classic red/yellow theme
- Minimal - Clean gray theme
- Intense - Bold red/orange theme
- Elegant - Sophisticated purple theme
- Neon - Bright cyan/pink theme
- Retro - Vintage green/yellow theme
BossBar display with countdown timer
Color-coded urgency (green → yellow → red)
ActionBar notifications with opponent info
Sound effects (5 profiles: default, subtle, intense, calm, electronic)
Client-side glass barriers (ProtocolLib)
Per-player style preferences
HEX color support for full RGB customization

📊 Statistics & Tracking

Wins/Losses tracking
K/D ratio calculation
Win rate percentage
Damage dealt/received (precise to 0.1 hearts)
Hits landed vs total hits
Accuracy percentage
Combat duration tracking
Knockback exchanges
Total combat time
Last combat timestamp
PlaceholderAPI integration (15+ placeholders)

🎬 Combat Replay System

Timeline recording of all combat events
Hybrid storage (memory + compressed files)
Replay playback with admin commands
Event filtering and search
Configurable retention (default: 30 days)
Memory-efficient with auto cleanup
Player names in replay filenames

🛡️ Safezone Protection

WorldGuard integration
Prevent entry during combat
Visual glass barriers at boundaries
Barriers persist until player moves away (>10 blocks)
Barriers only render on AIR blocks (no griefing)
Client-side rendering (no world modification)
Configurable barrier material (GLASS, RED_STAINED_GLASS, etc.)
Prevent attacking from/into safezones
Sound and visual feedback

⚡ Performance Optimized

Zero lag - Optimized for high-performance servers
Intelligent logging system (disable for best performance)
Async operations (combat logging, stats calculation)
Efficient caching (player data, restrictions, combat state)
Minimal memory footprint
Configurable thread pool (default: 4 threads)
Automatic cache cleanup
No string creation when logging disabled

🔒 Anti-Abuse Features

Combat logging protection (instant death)
Anti-interference system (third-party damage detection)
Thread-safe operations
Input validation on all commands
Permission checks on sensitive operations
Server switch prevention during combat

🌐 Cross-Server Support (Experimental)

BungeeCord/Velocity compatibility
Combat state synchronization
Server switch prevention
Network-wide broadcasts
Configurable sync intervals

🎮 Commands

Player Commands

/combat status - Check your current combat status and opponent
/combat summary - View your lifetime combat statistics
/combat toggle-style - Cycle through visual themes

Admin Commands

/combat inspect <player> - Real-time combat data inspection
/combat summary <player> - View any player's statistics
/combat reload - Reload configuration
/combat debug - Toggle debug mode with verbosity levels
/combat logging <enabled|disabled> - Control console logging in real-time
/replay view <session-uuid> - View combat replay timeline

Permissions

Player Permissions (default: true):

pvpcombat.command.status
pvpcombat.command.summary
pvpcombat.command.toggle-style

Admin Permissions (default: op):

pvpcombat.admin - All admin commands
pvpcombat.admin.inspect - Inspect players
pvpcombat.admin.debug - Debug mode

Bypass Permissions (default: op):

pvpcombat.bypass.combatlog - Bypass combat logging
pvpcombat.bypass.restrictions - Bypass all restrictions
pvpcombat.bypass.newbie - Bypass newbie protection
pvpcombat.bypass.server-switch - Bypass server switch prevention

📋 Requirements

Required

Minecraft 1.20.4+ (Paper/Spigot/Purpur)
Java 21+ (Java 21.0.8 tested)

Optional Integrations

Citizens (NPC combat support)
CombatLogX (integration support)
MythicMobs (mob combat support)
BungeeCord/Velocity (cross-server sync)

⚙️ Configuration Highlights

# General Settings
general:
  enabled: true
  debug-mode: false

# Combat Settings
combat:
  duration: 30              # Combat timer (seconds)
  allow-flight: false       # Allow flight during combat
  cancel-on-death: true     # End combat on death

# Newbie Protection
newbie-protection:
  enabled: true
  prevent-damage-dealing: true
  prevent-damage-receiving: true
  xp-level-threshold: 3
  require-any-armor: true   # true = need 1 piece, false = need full set

# Restrictions
restrictions:
  trident:
    enabled: true
    block-throwing: true
    block-riptide: true
  
  enderpearl:
    enabled: true
    block-usage: true
    cooldown: 10
    combat-cooldown-multiplier: 2.0
  
  respawn-anchor:
    enabled: true
  
  elytra:
    enabled: true
    block-glide: true
  
  crystal:
    enabled: true
    block-placement: true
    block-breaking: false
  
  golden-apple:
    cooldown: 3
    combat-cooldown-multiplier: 1.5
  
  enchanted-golden-apple:
    cooldown: 4
    combat-cooldown-multiplier: 2.0
  
  teleport:
    enabled: true
    blocked-commands:
      - "tp"
      - "teleport"
      - "home"
      - "spawn"
      - "warp"
  
  safezone:
    enabled: true
    block-entry: true
    protected-regions:
      - "spawn"
      - "safezone"
      - "safe"
    barrier:
      enabled: true
      material: "GLASS"      # GLASS, RED_STAINED_GLASS, etc.
      height: 4
      width: 5

# Visual System
visual:
  themes:
    default-theme: "default"
    available: ["default", "minimal", "intense", "elegant", "neon", "retro"]
  
  bossbar:
    enabled: true
    update-interval: 1
  
  actionbar:
    enabled: true
    update-interval: 20
  
  sounds:
    profile: "default"      # default, subtle, intense, calm, electronic

# Performance
performance:
  lag:
    enabled: true
    tps-threshold: 18.0
  
  async:
    enabled: true
    thread-pool-size: 4
  
  cache:
    player-data-ttl: 1800   # 30 minutes

# Logging (disable for best performance)
logging:
  console-enabled: false
  storage:
    type: "BOTH"            # FILE, MEMORY, or BOTH

# Statistics
statistics:
  enabled: true
  summary:
    delivery: "CHAT"        # CHAT, GUI, STORAGE, or NONE

# Replay System
replay:
  enabled: false            # Disabled by default
  retention-days: 30
  max-events: 1000

🔌 PlaceholderAPI Support

Combat Status

%pvpcombat_in_combat% - true/false
%pvpcombat_time_left% - Remaining seconds
%pvpcombat_opponent% - Opponent name

Lifetime Statistics

%pvpcombat_wins% - Total wins
%pvpcombat_losses% - Total losses
%pvpcombat_total_combats% - Total combats
%pvpcombat_kd_ratio% - K/D ratio (formatted)
%pvpcombat_win_rate% - Win rate percentage
%pvpcombat_total_damage_dealt% - Total damage dealt
%pvpcombat_total_damage_received% - Total damage received
%pvpcombat_damage_ratio% - Damage ratio (dealt/received)
%pvpcombat_total_combat_time% - Total time in combat

Session Statistics

%pvpcombat_session_damage_dealt% - Damage in current fight
%pvpcombat_session_damage_received% - Damage received
%pvpcombat_session_hits_landed% - Hits landed
%pvpcombat_knockback_exchanges% - Knockback exchanges

🚀 Why Choose True Combat Manager?

✓ Zero Lag - Optimized for high-performance servers
✓ Newbie Friendly - Protects new players automatically
✓ Highly Configurable - 100+ configuration options
✓ Visual Feedback - 6 themes, BossBar, ActionBar, sounds
✓ Smart Restrictions - Block items/commands during combat
✓ Comprehensive Statistics - Detailed tracking with PlaceholderAPI
✓ Safezone Protection - Visual barriers with WorldGuard
✓ Combat Replay - Timeline recording and playback
✓ Anti-Abuse - Combat logging protection and anti-interference
✓ Cross-Server - BungeeCord/Velocity support
✓ Active Development - Regular updates and bug fixes
✓ Professional Support - Fast response to issues
✓ Well Documented - Extensive configuration comments

📦 Installation

Download the plugin
Place in plugins/ folder
Install ProtocolLib (recommended)
Install WorldGuard (recommended)
Restart server
Configure config.yml
Reload with /combat reload

🐛 Troubleshooting

Server Lag?
→ Disable console logging: /combat logging disabled
→ Check config: logging.console-enabled: false
→ This eliminates all string creation overhead

Newbie Protection Not Working?
→ Check player has NO armor equipped (all 4 slots empty)
→ Verify player XP level ≤ threshold (default: 3)
→ Check player doesn't have pvpcombat.bypass.newbie permission
→ Enable logging to see detailed checks: /combat logging enabled

Barriers Not Showing?
→ Install ProtocolLib 5.0+
→ Check config: restrictions.safezone.barrier.enabled: true
→ Verify WorldGuard regions are configured
→ Check console for ProtocolLib detection message

Tridents Still Working in Combat?
→ Check config: restrictions.trident.enabled: true
→ Verify player is actually in combat
→ Check console logs when enabled

Commands Not Blocked?
→ Check config: restrictions.teleport.enabled: true
→ Verify blocked-commands list is not empty
→ Check player doesn't have pvpcombat.bypass.restrictions permission

Placeholders Not Working?
→ Install PlaceholderAPI
→ Run /papi reload
→ Check /papi parse me %pvpcombat_in_combat%

📊 Combat Statistics Example

Players can view their statistics with /combat summary:

=== Combat Summary for PlayerName ===
Total Combats: 47
Wins: 32 | Losses: 15
Win Rate: 68.1%
K/D Ratio: 2.13
Damage Dealt: 587.5 ❤
Damage Received: 275.0 ❤
Damage Ratio: 2.14
Total Combat Time: 23m 45s
Last Combat: 2025-11-30 15:30:00

🎯 Tested Versions

✓ Minecraft 1.21.10 - Fully Tested
✓ Minecraft 1.21.x - Fully Tested
✓ Minecraft 1.20.x - Compatible
✓ Minecraft 1.19.x - Compatible
⚠ Minecraft 1.18.x - Basic Features

✓ Paper 1.20.4+ - Recommended
✓ Spigot 1.20.4+ - Supported
✓ Purpur 1.20.4+ - Supported

✓ Java 21.0.8 - Tested
✓ Java 21+ - Recommended
✓ Java 17+ - Minimum