⚔️ COMBATIX — COMPLETE FEATURE & SYSTEM OVERVIEW (v0.2.0)
CORE IDEA Combatix enforces fair PvP by placing players into dynamic combat sessions. Once in combat, players cannot escape unfairly (logout, commands, etc.) without consequences. Escape is only possible through gameplay skill.
━━━━━━━━━━━━━━━━━━━ 🧠 COMBAT SESSION SYSTEM (CORE ENGINE) ━━━━━━━━━━━━━━━━━━━ • Session-based combat (NOT per-player timers) • Every fight creates or joins a CombatSession • Multiple players merge into ONE session automatically • Tracks:
- Participants
- Damage dealt/taken
- Last hit timestamp
• Sessions expire automatically after inactivity • Players are removed when combat ends
━━━━━━━━━━━━━━━━━━━ ⚔️ COMBAT DETECTION ━━━━━━━━━━━━━━━━━━━ • Listens to PvP damage events • Supports:
- Melee attacks
- Projectiles (bows, etc.)
• Ignores:
- Self-damage
- Zero damage
• Respects:
- World blacklist
- Permission bypass (combatix.bypass)
• Automatically tags BOTH attacker & victim
━━━━━━━━━━━━━━━━━━━ 🔗 SESSION MERGING (ADVANCED) ━━━━━━━━━━━━━━━━━━━ • A hits B, B hits C → ALL become one session • Prevents split combat tracking • Ensures fairness in multi-player fights
━━━━━━━━━━━━━━━━━━━ ⏱ COMBAT TIMER SYSTEM ━━━━━━━━━━━━━━━━━━━ • Global timer loop (runs every second) • Each session expires after X seconds of no hits • On expiry:
- Session ends
- Players removed
- "combat.end" message sent
• Prevents infinite combat lock
━━━━━━━━━━━━━━━━━━━ 📢 PLAYER FEEDBACK ━━━━━━━━━━━━━━━━━━━ • On entering combat: → "combat.start" message • On exiting combat: → "combat.end" message • Fully configurable messages system
━━━━━━━━━━━━━━━━━━━ 🚫 COMMAND BLOCKING ━━━━━━━━━━━━━━━━━━━ • Blocks commands during combat:
- /home, /spawn, /tp, etc.
• Features:
- Configurable command list
- Case-insensitive
- Namespace protection (/essentials:home)
• Bypass permission supported
━━━━━━━━━━━━━━━━━━━ ❌ COMBAT LOG DETECTION ━━━━━━━━━━━━━━━━━━━ • Detects PlayerQuitEvent • If player is in combat:
- Marks as combat logger
- Applies punishment
• Prevents:
- Logout escaping
- Rejoin abuse (optional system)
━━━━━━━━━━━━━━━━━━━ ⚖️ PUNISHMENT SYSTEM ━━━━━━━━━━━━━━━━━━━ Modes:
- KILL
• Instantly kills player • Optional killer assignment (based on damage %)
- DROP
• Drops inventory on ground • Configurable:
- Armor - Hotbar - Main inventory
- CLEAR
• Deletes inventory (no drops)
- CUSTOM
• Executes console commands • Supports {player} placeholder
Additional: • Double punishment prevention • Rejoin punishment system (optional)
━━━━━━━━━━━━━━━━━━━ 📊 DAMAGE TRACKING SYSTEM ━━━━━━━━━━━━━━━━━━━ • Tracks per-player:
- Damage dealt
- Damage taken
• Determines:
- Top attacker
- Total session damage
• Enables fair punishment logic
━━━━━━━━━━━━━━━━━━━ 🗃 DATABASE SYSTEM (SQLite) ━━━━━━━━━━━━━━━━━━━ • Stores every combat log event • Data saved:
- Player
- Attacker
- Damage
- Mode
- World
- Coordinates
- Time
- Ping
• Features:
- Async operations (no lag)
- Query support
- Leaderboard support
━━━━━━━━━━━━━━━━━━━ 🌐 DISCORD INTEGRATION ━━━━━━━━━━━━━━━━━━━ • Webhook system (async queue) • Sends embed logs with:
- Player
- Attacker
- Damage
- Mode
- Location
- Time
- Ping
• Rate-limit safe
- Bot system asks bot token guild id and channel id better than webhook
━━━━━━━━━━━━━━━━━━━ 📈 ADMIN COMMAND SYSTEM ━━━━━━━━━━━━━━━━━━━ /combatix reload → reload configs
/combatix logs <player> → view player combat logs
/combatix status → active sessions → uptime → total logs
/combatix debug → session details → TPS → combat data
/combatix clearlogs → wipe database
/combatix top → leaderboard of combat loggers
━━━━━━━━━━━━━━━━━━━ ⚡ PERFORMANCE SYSTEM ━━━━━━━━━━━━━━━━━━━ • Uses ConcurrentHashMap (thread-safe) • Async:
- Database
- Discord
• Session cleanup system • No heavy sync operations • Scales for large servers
━━━━━━━━━━━━━━━━━━━ 🧠 TPS PROTECTION SYSTEM ━━━━━━━━━━━━━━━━━━━ • Monitors server TPS • If TPS < threshold (e.g. 8): → punishment is skipped • Prevents unfair punishments during lag
━━━━━━━━━━━━━━━━━━━ 🧩 CONFIG SYSTEM ━━━━━━━━━━━━━━━━━━━ Multi-file setup:
• main.yml → performance, timers • combat.yml → combat behavior • punishments.yml → modes & logic • discord.yml → webhook/bot config • messages.yml → all messages
Features: • Fully customizable • Placeholder support • Clean separation of concerns
━━━━━━━━━━━━━━━━━━━ 🎯 DESIGN PHILOSOPHY ━━━━━━━━━━━━━━━━━━━ • Fair PvP enforcement • No exploit-based escape • Skill-based disengagement allowed • Maximum configurability • High performance & scalability
━━━━━━━━━━━━━━━━━━━ 🚀 SUMMARY ━━━━━━━━━━━━━━━━━━━ Combatix is a session-based, intelligent combat logging prevention system that combines:
• Real-time combat tracking • Multi-player session merging • Smart punishment logic • Async database logging • Discord integration • High configurability
→ into a single scalable, performance-focused plugin.
It doesn’t just prevent combat logging — it controls the entire integrity of combat.
No files in this session