Compatibility
Minecraft: Java Edition
Platforms
Links
Tags
Creators
Details
**## 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:
// 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
// Get plugin instance
CombatMetrics plugin = CombatMetrics.getInstance();
// Get the metric manager
MetricManager manager = plugin.getMetricManager();
Reading Player Data
// 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
// 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
// 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
- Download the
CombatMetrics-1.0.0.jarfile - Stop your server
- Place the JAR in your
plugins/folder - Start your server
- 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!**


