伤害探针 / Damage Probe
## English Summary
> ⚠️ Test-only tool: splits one damage instance from "intent" to "actual health lost" and shows which mod changed it and where it was swallowed. **Do not install for normal gameplay.**
---
## ⚠️ Read this first
**This is a diagnostic tool, not a gameplay mod.**
It installs a large number of event hooks and mixins on the server, continuously recording every damage instance, mob effect and attribute modifier.
**Measured overhead** (`spark`, 473 s sample):
```
AttributeOwnerRegistry 1620 ms
ModifierProbe 1504 ms
ProbeText 1104 ms
AmountCapture 992 ms
EffectProbe 576 ms
──────────────────────────────
≈1.2% of server CPU, plus continuous log output
```
| Scenario | Should you install it? |
|---|---|
| Debugging "the damage number is wrong" | ✅ Yes, temporarily |
| Debugging "the buff doesn't apply" | ✅ Yes, temporarily |
| Debugging "some mod swallows the damage" | ✅ Yes, temporarily |
| **Normal gameplay / long-running server** | ❌ **No** |
| **Shipping a modpack** | ❌ **Don't bundle it** |
**It is disabled by default** (`enabled = false`). Turn it on with `/damageprobe on`.
---
## The problem it solves
Players often say "that hit should have dealt 5000, but only 12 health was lost".
Normal logs can't answer this, because Forge damage passes through **four stages**, each of which a different mod may rewrite:
```
LivingAttackEvent → intended damage
LivingHurtEvent → armor / resistance / enchantments
LivingDamageEvent → absorption (golden hearts)
actuallyHurt → the real health loss
```
**This mod records every stage and tells you who changed it.**
---
## Damage probe
```
[伤害探针] Player→Dummy | 理论 457.9 | hurt出 2940.0 | damage 2928.0 | 实扣 2928.0
| 掉血 2928.0 | 血 5000.0→2072.0/5000.0
| 归属: 事件×6.42(+2482.1) 护甲段×0.996(-12.0) 实扣0.0 结算0.0
| 线程=Server thread
```
### Attribution
| Segment | Meaning |
|---|---|
| `事件×` | ratio from intended value to `LivingHurtEvent` exit |
| `护甲段×` | ratio from hurt exit to damage entry (**can exceed 1**) |
| `实扣` | difference between damage entry and real health loss (negative = clamped) |
| `结算` | amount written back after the health loss |
### Three pitfalls it handles explicitly
1. **Overkill** — shown as `实扣 9863.4(过量击杀,…)`, never as a negative "swallowed" value.
2. **Empty writes** — only `setAmount` calls that actually change the value are recorded, so attribution points at the real culprit.
3. **False async** — client-side events are skipped, so no bogus "Render thread" reports in singleplayer.
### Context snapshot
Detects whether the target class overrides `setHealth` (`血量托管=是(...)`) — the key clue for "my damage was swallowed".
---
## Effect probe
Distinguishes **applied** from **rejected**:
```
[效果探针] target=Zombie#21 gained minecraft:regeneration 1 200t
source=Player#20 result=被拒绝 call=xxx.Mod.apply:236
```
**`result=被拒绝` is the core signal for "why doesn't my buff work".**
Duplicate events within 20 ticks are merged as `(×N)` to keep high-frequency mods from flooding the log.
---
## Modifier probe
```
[修饰符探针] target=Player#23 attribute=minecraft:generic.max_health
modifier=tetra.stats.additioncharm2 amount=2.9 operation=ADDITION
result=已添加 value=20.0→22.9 call=…
```
**`value=20.0→22.9` shows the real applied amount**, regardless of what a tooltip claims.
---
## Commands
```
/damageprobe on | off
/damageprobe status
/damageprobe verbose
/damageprobe effects on|off
/damageprobe modifiers on|off
/damageprobe rejected on|off
/damageprobe filter all | players
```
`filter` is a runtime override — it does **not** write back to the config; restart returns to the configured default.
---
## Requirements
- Minecraft **1.20.1**, Forge **47.x**
- Server-side tool (client-side events are skipped)
- No dependencies; coexists with any mod
---
## TL;DR
> It's a scalpel, not furniture. Put it away when you're done.
> ⚠️ **仅测试用模组。正常游玩请勿装载。**
---
## 中文摘要(CurseForge Summary)
> ⚠️ 仅测试用:把一次伤害从「意图」到「真实掉血」全过程拆开,定位是哪个模组改了伤害、哪一段把它吞掉。**正常游玩请勿装载。**
---
## ⚠️ 必读:这是什么,以及为什么不该常开
**这是一个诊断工具,不是玩法模组。**
它会在服务端挂设大量事件钩子与 mixin,持续记录每一次伤害、状态效果、属性修饰符。
**实测开销**(`spark` 采样 473 秒):
```
com.hengx.damageprobe.probe.AttributeOwnerRegistry 1620 ms
com.hengx.damageprobe.probe.ModifierProbe 1504 ms
com.hengx.damageprobe.probe.ProbeText 1104 ms
com.hengx.damageprobe.core.AmountCapture 992 ms
com.hengx.damageprobe.probe.EffectProbe 576 ms
──────────────────────────────────────────────────────────
合计约占服务端 CPU 1.2%,并会持续写入日志
```
**所以:**
| 场景 | 是否建议装载 |
|---|---|
| 排查「伤害数值不对」 | ✅ 装,临时用 |
| 排查「buff 没生效」 | ✅ 装,临时用 |
| 排查「某个模组把伤害吞了」 | ✅ 装,临时用 |
| **正常游玩 / 长期开服** | ❌ **不要装** |
| 做整合包发布 | ❌ **不要打包进去** |
**默认就是关闭的**(`enabled = false`),需要用 `/damageprobe on` 手动打开。
---
## 它解决什么问题
玩家常说「我这一刀明明该打 5000,结果只掉了 12 点血」。
普通日志看不出来,因为伤害在 Forge 里经过**四个阶段**,每一段都可能被不同模组改写:
```
LivingAttackEvent → 意图伤害
LivingHurtEvent → 护甲/抗性/附魔介入
LivingDamageEvent → 吸收(黄心)介入
actuallyHurt → 真正扣血
```
**本模组把每一段的数值都记下来,并告诉你「谁改的」。**
---
## 伤害探针
### 一行摘要
```
[伤害探针] 玩家→训练人偶 | 理论 457.9 | hurt出 2940.0 | damage 2928.0 | 实扣 2928.0
| 掉血 2928.0 | 血 5000.0→2072.0/5000.0
| 归属: 事件×6.42(+2482.1) 护甲段×0.996(-12.0) 实扣0.0 结算0.0
| 线程=Server thread
```
### 归属分析(核心)
| 段 | 含义 |
|---|---|
| `事件×` | 从理论值到 `LivingHurtEvent` 出口的倍率(有模组乘了伤害) |
| `护甲段×` | 从 hurt 出口到 damage 入口的倍率(**可以大于 1**) |
| `实扣` | 从 damage 入口到真实掉血的差(负数 = 被 clamp 吞了) |
| `结算` | 扣血之后又被改回去的量 |
### 三个容易误判的地方,它专门处理了
**① 过量击杀**
```
实扣 9863.4(过量击杀,超出剩余血量 20222.6)
```
**不会**显示成 `实扣-20222`(那样看起来像被吞了伤害)。
**② 空写不抢归属**
有些模组会在末尾无条件 `setAmount(当前值)`(值没变)。探针只记录**真正改变数值**的那一次,所以能准确指向真凶。
**③ 假异步**
单人游戏里客户端也会触发 0 伤害事件,探针**跳过客户端侧**,不会误报「Render thread 异步伤害」。
### 上下文快照
```
上下文[攻击者]: 攻击力=3.0 非默认属性=... 效果=...
上下文[目标]: 护甲=0.0 韧性=0.0 血=1024/1024 吸收=0.0 无敌帧=20
效果=无 血量托管=是(ClampedZombie#m_21153_)
上下文[来源]: minecraft:mob_attack [穿甲=否 穿附魔=否 … 穿无敌=否]
```
**`血量托管=是(...)` 是排查「掉血被吞」的关键线索** —— 它检测目标类是否重写了 `setHealth`。
---
## 效果探针
每次有状态效果被施加/移除都记一条,**并区分「已施加」与「被拒绝」**:
```
[效果探针] 目标=玩家#20 获得 minecraft:strength 2级 1200t 可见=是 图标=是
来源=Zombie#1 结果=已施加 调用点=xxx.Mod.apply:88
[效果探针] 目标=Zombie#21 获得 minecraft:regeneration 1级 200t
来源=Player#20 结果=被拒绝 调用点=xxx.Mod.apply:236
```
**`结果=被拒绝` 是排查「buff 为什么没生效」的核心** —— 免疫、被更强效果覆盖、条件不满足,都在这里返回 `false`。
**20 tick 内同一事件合并成 `(×N)`**,避免高频重刷的模组刷爆日志:
```
… 结果=已添加 (×100)
```
---
## 修饰符探针
每次属性修饰符被增删都记一条,**并显示值的实际变化**:
```
[修饰符探针] 目标=Player#23 属性=minecraft:generic.max_health
修饰符=tetra.stats.additioncharm2 amount=2.9 operation=ADDITION
结果=已添加 值=20.0→22.9 调用点=…
```
**`值=20.0→22.9` 直接告诉你「实际加了多少」** —— 不受 tooltip 显示欺骗。
---
## 命令
```
/damageprobe on | off 总开关(默认关)
/damageprobe status 查看当前状态
/damageprobe verbose 详细模式(输出四阶段逐行)
/damageprobe effects on|off 状态效果探针
/damageprobe modifiers on|off 属性修饰符探针
/damageprobe rejected on|off 只看「被拒绝」的
/damageprobe filter all 记录所有(含无来源的效果施加)
/damageprobe filter players 只看与玩家相关的(默认)
```
**`filter` 是运行时覆盖,不写回配置文件,重启后回到配置默认值。**
---
## 输出通道
| 通道 | 谁能看到 |
|---|---|
| **聊天栏** | 权限 ≥2 的 OP;单人游戏发给房主 |
| **日志** | `logs/latest.log`,前缀 `[伤害探针]` / `[效果探针]` / `[修饰符探针]` |
---
## 前置与兼容
- Minecraft **1.20.1**
- Forge **47.x**
- **纯服务端工具**(客户端侧事件会被跳过)
- 不依赖任何其它模组,可与任何模组共存
---
## 一句话总结
> **它是把手术刀,不是家具。用完请收起来。**