伤害探针 / Damage Probe

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.**

伤害探针 / 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**
- **纯服务端工具**(客户端侧事件会被跳过)
- 不依赖任何其它模组,可与任何模组共存

---

## 一句话总结

> **它是把手术刀,不是家具。用完请收起来。**

伤害探针 / Damage Probe Team

profile avatar
  • 3
    Projects
  • 380
    Downloads

More from qianzhiqinghang

  • 属性上限解除 / Attribute Cap Lift project image

    属性上限解除 / Attribute Cap Lift

    让属性上限不再影响「数值转加成」,属性本身仍然受限/ Lets curios convert attribute values into bonuses without being blocked by attribute caps, while the attribute's actual effect on the player stays capped.

    • 10
    • November 18, 2026
  • 神秘遗物增强 (Enigmatic Enhance) project image

    神秘遗物增强 (Enigmatic Enhance)

    Enigmatic Enhance is an add-on mod for Enigmatic Legacy. It enhances the curios found in Enigmatic Legacy and its add-on mod, and also includes some content built around its own mechanics.

    • 362
    • November 14, 2026
  • 属性上限解除 / Attribute Cap Lift project image

    属性上限解除 / Attribute Cap Lift

    让属性上限不再影响「数值转加成」,属性本身仍然受限/ Lets curios convert attribute values into bonuses without being blocked by attribute caps, while the attribute's actual effect on the player stays capped.

    • 10
    • November 18, 2026
  • 神秘遗物增强 (Enigmatic Enhance) project image

    神秘遗物增强 (Enigmatic Enhance)

    Enigmatic Enhance is an add-on mod for Enigmatic Legacy. It enhances the curios found in Enigmatic Legacy and its add-on mod, and also includes some content built around its own mechanics.

    • 362
    • November 14, 2026