CombatMetrics

**## Overview **CombatMetrics** is a lightweight, high-performance combat tracking plugin for Paper 1.21+ servers. It accurately detects and displays **Critical Hits** and **Sprint Combo Hits** in real-time using the player's Action Bar. The plugin faithfully replicates vanilla Minecraft's exact combat mechanics, ensuring that every tracked hit matches what would trigger the corresponding subtitle/particle effect in the base game. ## Core Concept ``` ┌─────────────────────────────────────────────────────────────────────┐ │ COMBATMETRICS FLOW │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ PLAYER ATTACKS ENTITY │ │ │ │ │ ▼ │ │ ┌────────────────────┐ ┌────────────────────┐ │ │ │ Check Critical │ │ Check Combo │ │ │ │ Hit Conditions │ │ Hit Conditions │ │ │ │ (11 Checks) │ │ (3 Checks) │ │ │ └─────────┬──────────┘ └─────────┬──────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌────────────────────┐ ┌────────────────────┐ │ │ │ Increment Crit │ │ Increment Combo │ │ │ │ Counter │ │ Counter │ │ │ └─────────┬──────────┘ └─────────┬──────────┘ │ │ │ │ │ │ └───────────┬───────────────┘ │ │ ▼ │ │ ┌────────────────────────┐ │ │ │ UPDATE ACTION BAR │ │ │ │ │ │ └────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────┐ │ │ │ No hit for 2 seconds? │ │ │ │ → Reset counters to 0 │ │ │ └────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## ✨ Features ### Core Features | Feature | Description | |---------|-------------| | **Critical Hit Tracking** | Detects vanilla-accurate critical hits using 11 strict conditions | | **Combo Hit Tracking** | Detects sprint knockback hits for combo counting | | **Real-Time Display** | Shows live counters in the Action Bar | | **Auto Reset** | Counters automatically reset after 2 seconds of inactivity | | **Left-Aligned Display** | Text positioned on left side of screen for better visibility | | **Hit Highlighting** | Brief green flash when a hit is registered | ### Persistence Features | Feature | Description | |---------|-------------| | **Per-Player Toggle** | Each player can enable/disable their display | | **Survives Relog** | Preference saved using PersistentDataContainer | | **Survives Restart** | Settings persist across server restarts | | **No External Storage** | Data stored directly on player entity | ### ⚡ Performance Features | Feature | Description | |---------|-------------| | **Async Timer Checks** | Reset detection runs on async thread | | **Efficient Data Storage** | ConcurrentHashMap for thread-safe access | | **Minimal Overhead** | Early-return conditions prevent unnecessary processing | | **Lazy Initialization** | Data created only when player attacks | | **Lightweight Task** | Timer runs every 5 ticks (0.25 seconds) | --- ## ☠️ Critical Hit Detection CombatMetrics uses **vanilla-accurate** detection that matches Minecraft's exact critical hit requirements. A hit is only counted as critical if **ALL** conditions are met: ### Condition Checklist | # | Condition | Method Used | Explanation | |---|-----------|-------------|-------------| | 1 | **Falling** | `fallDistance > 0.0` | Player must have positive fall distance | | 2 | **Airborne** | `!isOnGround()` | Player cannot be touching the ground | | 3 | **Not Climbing** | `!isClimbing()` | Cannot be on ladder, vine, or scaffolding | | 4 | **Not In Water** | `!isInWater()` | Cannot be submerged in water | | 5 | **Not In Lava** | `!isInLava()` | Cannot be submerged in lava | | 6 | **Not Swimming** | `!isSwimming()` | Cannot be using swimming animation | | 7 | **Not Gliding** | `!isGliding()` | Cannot be flying with Elytra | | 8 | **No Blindness** | `!hasPotionEffect(BLINDNESS)` | Blindness effect blocks crits | | 9 | **No Slow Falling** | `!hasPotionEffect(SLOW_FALLING)` | Slow falling prevents crits | | 10 | **Not Mounted** | `!isInsideVehicle()` | Cannot be riding any entity | | 11 | **Charged Attack** | `getAttackCooldown() > 0.9` | Attack must be 90%+ charged | ### Visual Representation ``` CRITICAL HIT VALIDATION Player State Check Result ══════════════════════════════════════════ fallDistance > 0 ? ───────────→ ✓ PASS │ ▼ !isOnGround() ? ───────────→ ✓ PASS │ ▼ !isClimbing() ? ───────────→ ✓ PASS │ ▼ !isInWater() ? ───────────→ ✓ PASS │ ▼ !isInLava() ? ───────────→ ✓ PASS │ ▼ !isSwimming() ? ───────────→ ✓ PASS │ ▼ !isGliding() ? ───────────→ ✓ PASS │ ▼ No BLINDNESS ? ───────────→ ✓ PASS │ ▼ No SLOW_FALLING ? ───────────→ ✓ PASS │ ▼ !isInsideVehicle()? ───────────→ ✓ PASS │ ▼ attackCooldown > 0.9? ─────────→ ✓ PASS │ ▼ ══════════════════════════════════════════ │ ▼ ★ CRITICAL HIT REGISTERED ★ ``` --- ## ⚔️ Combo Hit Detection Combo hits detect **sprint knockback attacks** - the enhanced knockback applied when a player hits an enemy while sprinting. ### Condition Checklist | # | Condition | Method Used | Explanation | |---|-----------|-------------|-------------| | 1 | **Sprinting** |