**## 概览
CombatMetrics 是一款轻量级、高性能的战斗追踪插件,适用于 Paper 1.21+ 服务器。它通过玩家的操作栏(Action Bar)实时准确检测并显示暴击(Critical Hits)和冲刺连击(Sprint Combo Hits)。该插件忠实还原了原版 Minecraft 的精确战斗机制,确保每一个被追踪到的命中都与基础游戏中触发相应副标题/粒子效果的条件完全一致。
核心概念
┌─────────────────────────────────────────────────────────────────────┐
│ COMBATMETRICS 流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 玩家攻击实体 │
│ │ │
│ ▼ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ 检查暴击 │ │ 检查连击 │ │
│ │ 条件 │ │ 条件 │ │
│ │ (11项检查) │ │ (3项检查) │ │
│ └─────────┬──────────┘ └─────────┬──────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ 增加暴击 │ │ 增加连击 │ │
│ │ 计数器 │ │ 计数器 │ │
│ └─────────┬──────────┘ └─────────┬──────────┘ │
│ │ │ │
│ └───────────┬───────────────┘ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ 更新操作栏 │ │
│ │ [ ☠ 暴击: X | ⚔ 连击: Y ] │
│ └────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ 超过2秒未命中? │ │
│ │ → 将计数器重置为0 │ │
│ └────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
✨ 功能特性
核心功能
| 功能 |
描述 |
| 暴击追踪 |
使用11项严格条件检测符合原版标准的暴击 |
| 连击追踪 |
检测冲刺击退以进行连击计数 |
| 实时显示 |
在操作栏中显示实时计数器 |
| 自动重置 |
无操作2秒后计数器自动重置 |
| 左对齐显示 |
文本定位在屏幕左侧以提高可见性 |
| 命中高亮 |
命中注册时短暂闪烁绿色 |
持久化功能
| 功能 |
描述 |
| 按玩家切换 |
每个玩家可以独立启用/禁用显示 |
| 重连保留 |
使用 PersistentDataContainer 保存偏好设置 |
| 重启保留 |
设置跨服务器重启持久化保存 |
| 无需外部存储 |
数据直接存储在玩家实体上 |
⚡ 性能优化
| 功能 |
描述 |
| 异步计时器检查 |
重置检测在异步线程上运行 |
| 高效数据存储 |
使用 ConcurrentHashMap 实现线程安全访问 |
| 极低开销 |
提前返回条件防止不必要的处理 |
| 延迟初始化 |
仅在玩家发起攻击时创建数据 |
| 轻量级任务 |
计时器每5刻(0.25秒)运行一次 |
☠️ 暴击检测
CombatMetrics 使用符合原版标准的检测机制,与 Minecraft 的精确暴击要求相匹配。只有当所有条件都满足时,命中才会被计为暴击:
条件清单
| # |
条件 |
使用的方法 |
解释 |
| 1 |
下落中 |
fallDistance > 0.0 |
玩家必须具有正的下落距离 |
| 2 |
空中 |
!isOnGround() |
玩家不能接触地面 |
| 3 |
未攀爬 |
!isClimbing() |
不能在梯子、藤蔓或脚手架上 |
| 4 |
不在水中 |
!isInWater() |
不能淹没在水中 |
| 5 |
不在熔岩中 |
!isInLava() |
不能淹没在熔岩中 |
| 6 |
未游泳 |
!isSwimming() |
不能使用游泳动画 |
| 7 |
未滑翔 |
!isGliding() |
不能使用鞘翅飞行 |
| 8 |
无失明 |
!hasPotionEffect(BLINDNESS) |
失明效果会阻止暴击 |
| 9 |
无缓降 |
!hasPotionEffect(SLOW_FALLING) |
缓降效果会阻止暴击 |
| 10 |
未骑乘 |
!isInsideVehicle() |
不能骑乘任何实体 |
| 11 |
蓄力攻击 |
getAttackCooldown() > 0.9 |
攻击必须已蓄力90%以上 |
视觉表示
暴击验证
玩家状态检查结果
══════════════════════════════════════════
fallDistance > 0 ? ───────────→ ✓ 通过
│
▼
!isOnGround() ? ───────────→ ✓ 通过
│
▼
!isClimbing() ? ───────────→ ✓ 通过
│
▼
!isInWater() ? ───────────→ ✓ 通过
│
▼
!isInLava() ? ───────────→ ✓ 通过
│
▼
!isSwimming() ? ───────────→ ✓ 通过
│
▼
!isGliding() ? ───────────→ ✓ 通过
│
▼
无 BLINDNESS ? ───────────→ ✓ 通过
│
▼
无 SLOW_FALLING ? ───────────→ ✓ 通过
│
▼
!isInsideVehicle()? ───────────→ ✓ 通过
│
▼
attackCooldown > 0.9? ─────────→ ✓ 通过
│
▼
══════════════════════════════════════════
│
▼
★ 暴击已注册 ★
⚔️ 连击检测
连击检测冲刺击退攻击——即玩家在冲刺状态下击中敌人时应用的增强型击退效果。
条件清单
| # |
条件 |
使用的方法 |
解释 |
| 1 |
正在冲刺 |
isSprinting() |
玩家必须正在主动冲刺 |
| 2 |
蓄力攻击 |
getAttackCooldown() > 0.9 |
攻击必须已蓄力90%以上 |
| 3 |
活体目标 |
instanceof LivingEntity |
目标必须是能够承受击退的实体 |
视觉表示
连击验证
玩家状态检查结果
══════════════════════════════════════════
isSprinting() ? ───────────→ ✓ 通过
│
▼
attackCooldown > 0.9? ─────────→ ✓ 通过
│
▼
Target is Living? ───────────→ ✓ 通过
│
▼
══════════════════════════════════════════
│
▼
★ 连击已注册 ★
? 视觉显示系统
操作栏格式
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ [ ☠ 暴击: 5 | ⚔ 连击: 3 ] │
│ ↑ ↑ │
│ └── 左对齐内容 └── 不可见空格将内容推向左侧 │
│ │
└─────────────────────────────────────────────────────────────────────┘
配色方案
| 元素 |
颜色 |
样式 |
[ ] |
深灰色 |
普通 |
☠ |
深红色 |
普通 |
CRITS: |
红色 |
粗体 |
| 暴击计数 |
白色 |
普通 |
| |
深灰色 |
普通 |
⚔ |
金色 |
普通 |
COMBO: |
黄色 |
粗体 |
| 连击计数 |
白色 |
普通 |
命中高亮效果
当检测到一次命中时,对应的计数器会短暂高亮显示:
正常显示:
[ ☠ CRITS: 5 | ⚔ COMBO: 3 ]
↑ ↑
白色 白色
受到暴击后(持续 3 刻):
[ ☠ CRITS: 6 | ⚔ COMBO: 3 ]
↑
绿色 + 粗体
受到连击后(持续 3 刻):
[ ☠ CRITS: 6 | ⚔ COMBO: 4 ]
↑
绿色 + 粗体
左对齐技巧
Minecraft 的动作栏默认居中显示文本。为了实现左对齐:
// 在内容后追加不可见的空格
Component content = actualContent
.append(Component.text(" ") // 约 80 个空格
.color(NamedTextColor.BLACK)); // 不可见
这会将可见内容推至屏幕左侧,靠近生命值/护甲值显示区域。
⏱️ 重置计时器系统
工作原理
┌─────────────────────────────────────────────────────────────────────┐
│ 重置计时器系统 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 时间 ──────────────────────────────────────────────────────→ │
│ │
│ 命中!重置! │
│ │ │ │
│ ▼ ▼ │
│ ●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━● │
│ │←────────────── 2000毫秒(40 刻)───────────────→│ │
│ │ │ │
│ 上次命中时间 当前时间 │
│ │
│ │
│ [异步任务 - 每 5 刻执行一次] │
│ │ │
│ ▼ │
│ if (当前时间 - 上次命中时间 >= 2000毫秒) { │
│ 重置计数器(); │
│ 更新动作栏(); // 短暂显示 0 │
│ } │
│ │
└─────────────────────────────────────────────────────────────────────┘
独立计时器
暴击和连击计数器拥有独立的计时器:
场景:玩家造成一次暴击,随后继续造成连击
时间:0秒 1秒 2秒 3秒 4秒 5秒
│ │ │ │ │ │
暴击数:[1]─────[1]─────[0](在 2 秒时重置)
│ │ │
连击数:[1]────[2]────[3]────[4]─────[4]─────[0]
↑ ↑
上次连击重置发生在 5 秒
宽限期
计数器重置为 0 后,在完全清除显示之前有一个短暂的 500 毫秒宽限期:
命中! → 2 秒 → 重置为 0 → 500 毫秒 → 清除显示
↓
短暂显示 "[ ☠ CRITS: 0 | ⚔ COMBO: 0 ]"
命令与权限
命令
| 命令 |
描述 |
权限 |
/metrics toggle |
启用/禁用动作栏显示 |
combatmetrics.use |
/metrics status |
查看当前统计数据和设置 |
combatmetrics.use |
/metrics reset |
将两个计数器重置为零 |
combatmetrics.use |
命令别名
权限
| 权限 |
默认值 |
描述 |
combatmetrics.use |
true |
访问所有玩家命令 |
combatmetrics.admin |
op |
保留用于未来的管理功能 |
命令输出示例
开启:
✓ 战斗指标已启用
您的战斗统计数据现在将在动作栏中显示。
关闭:
✗ 战斗指标已禁用
动作栏显示已关闭。
状态:
══════ 战斗指标状态 ══════
显示:已启用
当前会话:
☠ 暴击次数:15
⚔ 连击次数:23
重置:
↺ 计数器已重置!
数据持久化
PersistentDataContainer (PDC) 存储
┌─────────────────────────────────────────────────────────────────────┐
│ 持久化系统 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 命名空间:combatmetrics │
│ 键名:metrics_display_enabled │
│ 类型:BYTE │
│ │
│ 数值: │
│ 0 = 显示已禁用 │
│ 1 = 显示已启用 │
│ null = 默认为启用 │
│ │
│ 存储位置:玩家实体 NBT 数据 │
│ │
└─────────────────────────────────────────────────────────────────────┘
持久化优势
| 优势 |
描述 |
| 无需文件 |
无需为每个玩家创建 YAML/JSON 配置文件 |
| 无需数据库 |
不需要 MySQL/SQLite |
| 自动保存 |
随玩家数据自动保存 |
| 可靠 |
经受崩溃、重启和重新登录的考验 |
| 轻量级 |
每位玩家仅占用一个字节 |
⚡ 性能分析
内存使用
每位玩家:
┌────────────────────────────────────┐
│ MetricData 对象 │
├────────────────────────────────────┤
│ int critCount = 4 字节 │
│ int comboCount = 4 字节 │
│ long lastCritTime = 8 字节 │
│ long lastComboTime = 8 字节 │
│ boolean needsUpdate = 1 字节 │
│ 对象开销 ≈ 16 字节 │
├────────────────────────────────────┤
│ 总计 ≈ 41 字节 │
└────────────────────────────────────┘
100 名玩家 = 约 4.1 KB 内存
1000 名玩家 = 约 41 KB 内存
CPU 使用率
| 任务 |
频率 |
成本 |
| 伤害事件处理器 |
每次攻击 |
极低(早期返回) |
| 异步重置检查器 |
每 5 刻 |
极小(简单的时间戳比较) |
| 动作栏更新 |
命中/重置时 |
低(组件创建) |
使用的优化技术
| 技术 |
实现方式 |
| 早期返回 |
在其他条件之前先检查冷却时间 |
| 异步处理 |
计时器检查在主线程之外运行 |
| ConcurrentHashMap |
无锁线程安全 |
| 懒加载 |
首次攻击时创建 MetricData |
| 最小化分配 |
尽可能复用模式 |
| 事件优先级 |
MONITOR 优先级 - 在其他插件之后运行 |
事件流程
完整事件生命周期
┌─────────────────────────────────────────────────────────────────────┐
│ 完整事件流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 触发 EntityDamageByEntityEvent │
│ │ │
│ ▼ │
│ 2. 检查:攻击者是否为玩家? │
│ │ 否 → 退出 │
│ │ 是 ↓ │
│ ▼ │
│ 3. 检查:目标是否为 LivingEntity? │
│ │ 否 → 退出 │
│ │ 是 ↓ │
│ ▼ │
│ 4. 检查:攻击冷却时间 > 0.9? │
│ │ 否 → 退出(弱攻击) │
│ │ 是 ↓ │
│ ▼ │
│ 5. 检查暴击条件(共 11 项检查) │
│ │ 通过 → 暴击计数器加 1 │
│ ▼ │
│ 6. 检查连击条件(共 2 项检查) │
│ │ 通过 → 连击计数器加 1 │
│ ▼ │
│ 7. 任一计数器是否增加? │
│ │ 否 → 退出 │
│ │ 是 ↓ │
│ ▼ │
│ 8. 检查:该玩家是否启用了显示功能? │
│ │ 否 → 退出 │
│ │ 是 ↓ │
│ ▼ │
│ 9. 使用高亮效果更新操作栏 │
│ │ │
│ ▼ │
│ 10. 安排高亮移除任务(3 刻) │
│ │
└─────────────────────────────────────────────────────────────────────┘
异步重置任务流程
┌─────────────────────────────────────────────────────────────────────┐
│ 异步重置任务 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ [每 5 刻在异步线程上运行] │
│ │ │
│ ▼ │
│ 遍历每个在线玩家: │
│ │ │
│ ▼ │
│ 获取 MetricData(如果存在) │
│ │ NULL → 跳过 │
│ │ 存在 ↓ │
│ ▼ │
│ 检查:shouldResetCrit(currentTime)? │
│ │ 是 → resetCrit() │
│ ▼ │
│ 检查:shouldResetCombo(currentTime)? │
│ │ 是 → resetCombo() │
│ ▼ │
│ 是否发生了重置? │
│ │ 否 → 继续 │
│ │ 是 ↓ │
│ ▼ │
│ 安排同步任务: │
│ - 更新操作栏 │
│ - 或清除(如果两者均已过期) │
│ │
└─────────────────────────────────────────────────────────────────────┘
用例
PvP 服务器
| 用例 |
收益 |
| 竞技 PvP |
玩家可以追踪其暴击的一致性 |
| 练习服务器 |
训练暴击时机 |
| 连击训练 |
提升冲刺重置技巧 |
| 锦标赛 |
验证暴击机制 |
PvE 服务器
| 用例 |
收益 |
| 刷怪塔 |
优化伤害输出 |
| Boss 战 |
追踪 DPS 效率 |
| 速通 |
监控战斗效率 |
内容创作者
| 用例 |
收益 |
| YouTube/Twitch |
为观众提供视觉反馈 |
| 教程 |
演示暴击机制 |
| 挑战 |
创建基于暴击的成就 |
统计追踪
追踪内容
| 指标 |
描述 |
重置条件 |
| 暴击计数 |
当前连击中的总暴击次数 |
2 秒内无暴击 |
| 连击计数 |
当前连击中的总连击次数 |
2 秒内无连击 |
| 上次暴击时间 |
最近一次暴击的时间戳 |
重置时 |
| 上次连击时间 |
最近一次连击的时间戳 |
重置时 |
不追踪内容
| 不追踪项 |
原因 |
| 历史总统计数据 |
需要数据库存储 |
| 伤害数值 |
超出插件范围 |
| 击杀/死亡计数 |
由其他插件处理 |
| 武器类型 |
与命中检测无关 |
开发者 API
访问 CombatMetrics
// 获取插件实例
CombatMetrics plugin = CombatMetrics.getInstance();
// 获取度量管理器
MetricManager manager = plugin.getMetricManager();
读取玩家数据
// 获取当前统计
MetricData data = manager.getMetricData(player);
int crits = data.getCritCount();
int combos = data.getComboCount();
// 检查显示是否启用
boolean enabled = manager.isDisplayEnabled(player);
修改玩家数据
// 手动注册命中
manager.registerCriticalHit(player);
manager.registerComboHit(player);
// 重置计数器
manager.resetCounters(player);
// 切换显示
boolean newState = manager.toggleDisplay(player);
manager.setDisplayEnabled(player, true);
自定义操作栏更新
// 获取数据并更新显示
MetricData data = manager.getMetricData(player);
manager.updateActionBar(player, data);
// 使用高亮效果更新
manager.showHitWithHighlight(player, true, false); // 高亮暴击
--
兼容性
服务端软件
| 软件 |
兼容 |
备注 |
| Paper 1.21.1+ |
✅ |
主要目标 |
| Paper 1.21.2 |
✅ |
完全支持 |
| Paper 1.21.3 |
✅ |
完全支持 |
| Paper 1.21.4 |
✅ |
完全支持 |
| Paper 1.21.5 |
✅ |
完全支持 |
| Paper 1.21.6 |
✅ |
完全支持 |
| Paper 1.21.7 |
✅ |
完全支持 |
| Paper 1.21.8 |
✅ |
完全支持 |
| Spigot |
⚠️ |
可能可用,未经测试 |
| Bukkit |
❌ |
缺少 Adventure API |
| Folia |
⚠️ |
需要区域感知修改 |
Java 版本
| Java |
兼容 |
| Java 21 |
✅ 必需 |
| Java 22+ |
✅ 应该可以工作 |
| Java 17 |
❌ 对于 Paper 1.21 来说太旧了 |
插件冲突
| 插件类型 |
兼容性 |
| 战斗类插件 |
✅ 以 MONITOR 优先级运行 |
| 操作栏类插件 |
⚠️ 可能会覆盖显示 |
| 反作弊插件 |
✅ 无冲突 |
| 保护类插件 |
✅ 尊重被取消的事件 |
安装
逐步指南
- 下载
CombatMetrics-1.0.0.jar 文件
- 停止你的服务器
- 放置 JAR 文件到
plugins/ 文件夹
- 启动服务器
- 验证输入
/plugins - 应显示绿色
首次设置
无需配置!插件开箱即用:
- 默认情况下所有玩家的显示功能已启用
- 玩家可以使用
/metrics toggle 进行切换
- 设置会自动持久化
更新日志
版本 1.0.0
- 初始发布
- 暴击检测(11 个条件)
- 连击检测(3 个条件)
- 带左对齐的操作栏显示
- 2 秒后自动重置
- 基于 PDC 的持久化
- 切换/状态/重置命令
- 异步计时器任务
- 命中高亮效果
常见问题
问:为什么检测不到我的暴击?
答:请确保你的攻击已蓄力至满(90%以上),并且你处于下落状态且没有任何阻碍条件(如水、攀爬、缓降等)。
问:Crit(暴击)和 Combo(连击)能在同一次命中中同时触发吗?
答:可以!如果你在下落的同时冲刺并发动蓄力攻击,两个计数器都会增加。
问:创造模式支持此功能吗?
答:支持,但在创造模式下攻击冷却时间始终为 1.0,因此时机并不重要。
问:这会导致服务器卡顿吗?
答:不会。该插件使用异步处理并占用极少的内存。已在超过 100 名玩家的环境中测试过。
问:我可以自定义显示颜色吗?
答:当前版本不支持。颜色是硬编码的,以保持视觉一致性。
问:它会追踪对所有实体的命中吗?
答:仅追踪对 LivingEntity(生物、玩家、动物等)的命中。
总结
CombatMetrics 提供:
✅ 精准 匹配原版机制的暴击检测
✅ 实时 动作栏显示
✅ 自动 2 秒重置计时器
✅ 持久化 每位玩家的偏好设置
✅ 高性能 异步处理
✅ 简单 的开关指令
✅ 无需 配置
✅ 零 依赖
非常适合 PvP 服务器、练习服务器以及任何希望玩家追踪自身战斗表现的服务器!
**## 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
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.jar file
- 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!**
评论 0
登录后参与评分
还没有评论,来抢沙发吧