CombatMetrics

SpigotMCModrinth

A minecraft plugin that shows your combo nd crit counter in a row and it resets if u can't in a row

15 Downloads

neueste v1.0 SpigotMC

1.21 – 1.21

## 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 │ │ │ │ [ ☠ CRITS: X | ⚔ COMBO: Y ] │ │ └────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────┐ │ │ │ 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 | isSprinting() | Player must be actively sprinting |
| 2 | Charged Attack | getAttackCooldown() > 0.9 | Attack must be 90%+ charged |
| 3 | Living Target | instanceof LivingEntity | Target must be able to receive knockback |

### Visual Representation

 COMBO HIT VALIDATION Player State Check Result ══════════════════════════════════════════ isSprinting() ? ───────────→ ✓ PASS │ ▼ attackCooldown > 0.9? ─────────→ ✓ PASS │ ▼ Target is Living? ───────────→ ✓ PASS │ ▼ ══════════════════════════════════════════ │ ▼ ★ COMBO HIT REGISTERED ★ 

---

## ️ Visual Display System

### Action Bar Format

 ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ [ ☠ CRITS: 5 | ⚔ COMBO: 3 ] │ │ ↑ ↑ │ │ └── Left-aligned content └── Invisible spacing pushes left │ │ │ └─────────────────────────────────────────────────────────────────────┘ 

### Color Scheme

| Element | Color | Style |
|---------|-------|-------|
| [ ] | Dark Gray | Normal |
| ☠ | Dark Red | Normal |
| CRITS: | Red | Bold |
| Crit Count | White | Normal |
| \| | Dark Gray | Normal |
| ⚔ | Gold | Normal |
| COMBO: | Yellow | Bold |
| Combo Count | White | Normal |

### Hit Highlight Effect

When a hit is registered, the corresponding counter briefly highlights:

 Normal Display: [ ☠ CRITS: 5 | ⚔ COMBO: 3 ] ↑ ↑ White White After Critical Hit (3 ticks): [ ☠ CRITS: 6 | ⚔ COMBO: 3 ] ↑ GREEN + BOLD After Combo Hit (3 ticks): [ ☠ CRITS: 6 | ⚔ COMBO: 4 ] ↑ GREEN + BOLD 

### Left-Alignment Technique

Minecraft's Action Bar centers text by default. To achieve left-alignment:

java // Append invisible spacing after the content Component content = actualContent .append(Component.text(" ") // ~80 spaces .color(NamedTextColor.BLACK)); // Invisible 

This pushes the visible content to the left side of the screen, near the health/armor display.

---

## ⏱️ Reset Timer System

### How It Works

 ┌─────────────────────────────────────────────────────────────────────┐ │ RESET TIMER SYSTEM │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ TIME ──────────────────────────────────────────────────────→ │ │ │ │ HIT! RESET! │ │ │ │ │ │ ▼ ▼ │ │ ●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━● │ │ │←────────────── 2000ms (40 ticks) ──────────────→│ │ │ │ │ │ │ lastHitTime currentTime │ │ │ │ │ │ [Async Task - Every 5 ticks] │ │ │ │ │ ▼ │ │ if (currentTime - lastHitTime >= 2000ms) { │ │ resetCounter(); │ │ updateActionBar(); // Show 0 briefly │ │ } │ │ │ └─────────────────────────────────────────────────────────────────────┘ 

### Independent Timers

Critical and Combo counters have separate timers:

 SCENARIO: Player lands a crit, then keeps doing combo hits Time: 0s 1s 2s 3s 4s 5s │ │ │ │ │ │ Crits: [1]─────[1]─────[0] (reset at 2s) │ │ │ Combos: [1]────[2]────[3]────[4]─────[4]─────[0] ↑ ↑ last combo reset at 5s 

### Grace Period

After counters reset to 0, there's a brief 500ms grace period before the display clears entirely:

 HIT! → 2 seconds → RESET TO 0 → 500ms → CLEAR DISPLAY ↓ Show "[ ☠ CRITS: 0 | ⚔ COMBO: 0 ]" briefly 

---

## Commands & Permissions

### Commands

| Command | Description | Permission |
|---------|-------------|------------|
| /metrics toggle | Enable/disable action bar display | combatmetrics.use |
| /metrics status | View current stats and settings | combatmetrics.use |
| /metrics reset | Reset both counters to zero | combatmetrics.use |

### Command Aliases

- /combatmetrics
- /cm

### Permissions

| Permission | Default | Description |
|------------|---------|-------------|
| combatmetrics.use | true | Access to all player commands |
| combatmetrics.admin | op | Reserved for future admin features |

### Command Output Examples

Toggle ON:
 ✓ Combat Metrics ENABLED Your combat stats will now display in the action bar. 

Toggle OFF:
 ✗ Combat Metrics DISABLED Action bar display has been turned off. 

Status:
 ══════ Combat Metrics Status ══════ Display: ENABLED Current Session: ☠ Critical Hits: 15 ⚔ Combo Hits: 23 

Reset:
 ↺ Counters have been reset! 

---

## Data Persistence

### PersistentDataContainer (PDC) Storage

 ┌─────────────────────────────────────────────────────────────────────┐ │ PERSISTENCE SYSTEM │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Namespace: combatmetrics │ │ Key: metrics_display_enabled │ │ Type: BYTE │ │ │ │ Values: │ │ 0 = Display DISABLED │ │ 1 = Display ENABLED │ │ null = Default to ENABLED │ │ │ │ Storage Location: Player Entity NBT Data │ │ │ └─────────────────────────────────────────────────────────────────────┘ 

### Persistence Benefits

| Benefit | Description |
|---------|-------------|
| No Files | No YAML/JSON configuration files per player |
| No Database | No MySQL/SQLite required |
| Automatic | Saved with player data automatically |
| Reliable | Survives crashes, restarts, and relogs |
| Lightweight | Single byte per player |

---

## ⚡ Performance Analysis

### Memory Usage

 Per Player: ┌────────────────────────────────────┐ │ MetricData Object │ ├────────────────────────────────────┤ │ int critCount = 4 bytes │ │ int comboCount = 4 bytes │ │ long lastCritTime = 8 bytes │ │ long lastComboTime = 8 bytes │ │ boolean needsUpdate = 1 byte │ │ Object overhead ≈ 16 bytes │ ├────────────────────────────────────┤ │ TOTAL ≈ 41 bytes │ └────────────────────────────────────┘ 100 Players = ~4.1 KB memory 1000 Players = ~41 KB memory 

### CPU Usage

| Task | Frequency | Cost |
|------|-----------|------|
| Damage Event Handler | Per attack | Very Low (early returns) |
| Async Reset Checker | Every 5 ticks | Minimal (simple timestamp comparison) |
| Action Bar Update | On hit/reset | Low (Component creation) |

### Optimization Techniques Used

| Technique | Implementation |
|-----------|----------------|
| Early Returns | Check cooldown first before other conditions |
| Async Processing | Timer checks run off main thread |
| ConcurrentHashMap | Thread-safe without locks |
| Lazy Loading | MetricData created on first attack |
| Minimal Allocations | Reuse patterns where possible |
| Event Priority | MONITOR priority - runs after other plugins |

---

## Event Flow

### Complete Event Lifecycle

 ┌─────────────────────────────────────────────────────────────────────┐ │ COMPLETE EVENT FLOW │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 1. EntityDamageByEntityEvent Fired │ │ │ │ │ ▼ │ │ 2. Check: Damager is Player? │ │ │ NO → EXIT │ │ │ YES ↓ │ │ ▼ │ │ 3. Check: Target is LivingEntity? │ │ │ NO → EXIT │ │ │ YES ↓ │ │ ▼ │ │ 4. Check: Attack Cooldown > 0.9? │ │ │ NO → EXIT (weak attack) │ │ │ YES ↓ │ │ ▼ │ │ 5. Check Critical Hit Conditions (11 checks) │ │ │ PASS → Increment Crit Counter │ │ ▼ │ │ 6. Check Combo Hit Conditions (2 checks) │ │ │ PASS → Increment Combo Counter │ │ ▼ │ │ 7. Either counter incremented? │ │ │ NO → EXIT │ │ │ YES ↓ │ │ ▼ │ │ 8. Check: Display Enabled for Player? │ │ │ NO → EXIT │ │ │ YES ↓ │ │ ▼ │ │ 9. Update Action Bar with Highlight │ │ │ │ │ ▼ │ │ 10. Schedule Highlight Removal (3 ticks) │ │ │ └─────────────────────────────────────────────────────────────────────┘ 

### Async Reset Task Flow

 ┌─────────────────────────────────────────────────────────────────────┐ │ ASYNC RESET TASK │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ [Runs every 5 ticks on Async Thread] │ │ │ │ │ ▼ │ │ FOR each online player: │ │ │ │ │ ▼ │ │ Get MetricData (if exists) │ │ │ NULL → SKIP │ │ │ EXISTS ↓ │ │ ▼ │ │ Check: shouldResetCrit(currentTime)? │ │ │ YES → resetCrit() │ │ ▼ │ │ Check: shouldResetCombo(currentTime)? │ │ │ YES → resetCombo() │ │ ▼ │ │ Any reset occurred? │ │ │ NO → CONTINUE │ │ │ YES ↓ │ │ ▼ │ │ Schedule SYNC task: │ │ - Update action bar │ │ - Or clear if both expired │ │ │ └─────────────────────────────────────────────────────────────────────┘ 

---

## Use Cases

### PvP Servers

| Use Case | Benefit |
|----------|---------|
| Competitive PvP | Players can track their crit consistency |
| Practice Servers | Train timing for critical hits |
| Combo Training | Improve sprint-reset techniques |
| Tournaments | Verify critical hit mechanics |

### PvE Servers

| Use Case | Benefit |
|----------|---------|
| Mob Farming | Optimize damage output |
| Boss Fights | Track DPS effectiveness |
| Speedrunning | Monitor combat efficiency |

### Content Creators

| Use Case | Benefit |
|----------|---------|
| YouTube/Twitch | Visual feedback for viewers |
| Tutorials | Demonstrate critical hit mechanics |
| Challenges | Create crit-based achievements |

---

## Statistics Tracking

### What Gets Tracked

| Metric | Description | Reset Condition |
|--------|-------------|-----------------|
| Crit Count | Total critical hits in current streak | 2 seconds no crit |
| Combo Count | Total combo hits in current streak | 2 seconds no combo |
| Last Crit Time | Timestamp of most recent crit | On reset |
| Last Combo Time | Timestamp of most recent combo | On reset |

### What Is NOT Tracked

| Not Tracked | Reason |
|-------------|--------|
| All-time statistics | Would require database storage |
| Damage numbers | Beyond plugin scope |
| Kill/death counts | Other plugins handle this |
| Weapon types | Not relevant to hit detection |

---

## Developer API

### Accessing CombatMetrics

java // Get plugin instance CombatMetrics plugin = CombatMetrics.getInstance(); // Get the metric manager MetricManager manager = plugin.getMetricManager(); 

### Reading Player Data

java // Get current stats MetricData data = manager.getMetricData(player); int crits = data.getCritCount(); int combos = data.getComboCount(); // Check if display is enabled boolean enabled = manager.isDisplayEnabled(player); 

### Modifying Player Data

java // Manually register hits manager.registerCriticalHit(player); manager.registerComboHit(player); // Reset counters manager.resetCounters(player); // Toggle display boolean newState = manager.toggleDisplay(player); manager.setDisplayEnabled(player, true); 

### Custom Action Bar Updates

java // Get data and update display MetricData data = manager.getMetricData(player); manager.updateActionBar(player, data); // Update with highlight effect manager.showHitWithHighlight(player, true, false); // Highlight crit 

--

## Compatibility

### Server Software

| Software | Compatible | Notes |
|----------|:----------:|-------|
| Paper 1.21.1+ | ✅ | Primary target |
| Paper 1.21.2 | ✅ | Fully supported |
| Paper 1.21.3 | ✅ | Fully supported |
| Paper 1.21.4 | ✅ | Fully supported |
| Paper 1.21.5 | ✅ | Fully supported |
| Paper 1.21.6 | ✅ | Fully supported |
| Paper 1.21.7 | ✅ | Fully supported |
| Paper 1.21.8 | ✅ | Fully supported |
| Spigot | ⚠️ | May work, untested |
| Bukkit | ❌ | Missing Adventure API |
| Folia | ⚠️ | Requires region-aware modifications |

### Java Versions

| Java | Compatible |
|------|:----------:|
| Java 21 | ✅ Required |
| Java 22+ | ✅ Should work |
| Java 17 | ❌ Too old for Paper 1.21 |

### Plugin Conflicts

| Plugin Type | Compatibility |
|-------------|---------------|
| Combat plugins | ✅ Runs on MONITOR priority |
| Action bar plugins | ⚠️ May overwrite display |
| Anticheat plugins | ✅ No conflicts |
| Protection plugins | ✅ Respects cancelled events |

---

## Installation

### Step-by-Step

1. Download the CombatMetrics-1.0.0.jar file
2. Stop your server
3. Place the JAR in your plugins/ folder
4. Start your server
5. Verify with /plugins - should show green

### First-Time Setup

No configuration required! The plugin works out of the box:

- Display is enabled by default for all players
- Players can toggle with /metrics toggle
- Settings automatically persist

---

## Changelog

### Version 1.0.0
- Initial release
- Critical hit detection (11 conditions)
- Combo hit detection (3 conditions)
- Action bar display with left-alignment
- Auto-reset after 2 seconds
- PDC-based persistence
- Toggle/status/reset commands
- Async timer task
- Hit highlight effects

---

## FAQ

Q: Why doesn't it detect my critical hits?
> A: Ensure your attack is fully charged (90%+) and you're falling without any blocking conditions (water, climbing, slow falling, etc.)

Q: Can both Crit and Combo trigger on the same hit?
> A: Yes! If you're falling AND sprinting with a charged attack, both counters will increment.

Q: Does this work in creative mode?
> A: Yes, but attack cooldown is always 1.0 in creative, so timing doesn't matter.

Q: Will this cause lag?
> A: No. The plugin uses async processing and minimal memory. Tested with 100+ players.

Q: Can I customize the display colors?
> A: Not in this version. Colors are hardcoded for consistency.

Q: Does it track hits on all entities?
> A: Only hits on LivingEntity (mobs, players, animals, etc.)

---

## Summary

CombatMetrics provides:

✅ Accurate vanilla-matching critical hit detection
✅ Real-time action bar display
✅ Automatic 2-second reset timers
✅ Persistent per-player preferences
✅ Performant async processing
✅ Simple toggle commands
✅ Zero configuration required
✅ Zero dependencies

Perfect for PvP servers, practice servers, and any server where players want to track their combat effectiveness!

Versionen

Release

1.0

Kommentare 0

Noch keine Kommentare. Sei der Erste, der seine Meinung teilt.

CombatMetrics

Versionen

Kommentare 0

Herunterladen CombatMetrics