Mining zh

挖掘

简体中文 | English

← 返回目录

装上这个插件之后，僵尸、骷髅、猪灵这类人形怪物会自己拿镐子挖方块：头顶被压住的方块、挡住去路的方块、你脚下的方块，它们会算一遍耗时，然后当着你的面一块一块挖穿。这一页讲清楚"它什么时候挖、挖得动什么、挖一块要多久"，以及 mining.yml 里每个键怎么调。

它到底会做什么

怪物主手有镐子时，追击途中遇到挡路的方块会就地开挖，而不是绕路、卡墙或者干站着。
挖一块不是瞬间完成：耗时按方块硬度 × 你的倍率 ÷ 镐子速度系数换算，附近玩家能看到裂纹进度、粒子和命中音效。
默认不产生掉落物，方块挖掉就直接消失，防止被刷物品。
默认只挖紧贴身体的方块，不会隔着三格远隔空拆你家。

三道门槛：先过筛，再谈触发

在讨论"挖哪种方块"之前，怪物必须先过三道门，任何一道没过就完全不动手：

开关与筛选：enabled: true，世界不在 worlds.blacklist 里（填了 worlds.whitelist 就只在这些世界生效），生物类型通过 mob-whitelist / mob-blacklist。
工具门槛：tool.require-pickaxe: true（默认）时，主手不是镐子 → 完全不参与挖掘，连候选方块都不会选。怪物能不能自带镐子由 tool.give.* 决定。
逐方块检查：每个候选方块还要依次通过工具、材料、安全、可及范围、保护区、耗时这六项检查，全过才算候选。

触发：五条规则与优先级

五条规则按顺序判定，命中即返回——排在前面的规则一旦成立，后面的就不再考虑。这也是排查"为什么它不挖我想让它挖的那块"的第一把钥匙。

顺序	触发	成立条件	配置键
0	工具门槛	`require-pickaxe: true` 且主手不是镐子 → 完全不参与挖掘	`tool.require-pickaxe`
1	挖头顶	目标比自己高 ≥1.5 格，且脚上方第 2 格被方块压着	`trigger.ceiling-blocked`
2	挖自己脚下	目标比自己低 ≥1.5 格、水平 3 格内、自己站在地上、脚下第二格不是液体	`trigger.dig-below-self`
3	挖目标脚下	目标比自己高 ≥0.5 格，且目标下方那一格可挖	`trigger.dig-under-target`
4	寻路受阻	先查正前方脚下 / 头顶那两格，再看"眼睛 → 目标"射线上的第一处实体方块	`trigger.path-blocked`
5	指定方块	面前 `max-distance` 范围内出现 `trigger.configured-blocks.blocks` 里的方块（不要求挡视线）	`trigger.configured-blocks.enabled`

注意第 1 条和第 3 条的差别：挖头顶是"我被压住了，先把自己头顶那格挖掉才能往上垫"；挖目标脚下是"目标站在高处，把它脚下那格挖了让它掉下来"。两条分别由 trigger.ceiling-blocked 和 trigger.dig-under-target 单独开关。

射线判定：不穿透

第 4 条规则后面的"眼睛 → 目标"射线有一个很重要的性质：射线不穿透方块。

射线打到的第一处不可通过方块，如果能挖就挖它；
如果第一处不可通过方块不能挖（基岩、保护区、materials.disabled 里的方块等），直接放弃本次尝试，不会绕过它去挖后面那一块。

射线从身体外沿开始采样（跳过怪物自身占位的那一格），步长 0.25 格，最多 64 个采样点——精度足够判断"斜角缝"和"台阶边缘"，也不会因为采样点太多而卡服。

正前方判定：两条水平轴分别试

第 4 条规则的前半段（正前方脚下 / 头顶那两格）是按两条水平轴分别尝试的，并且先试水平差更大的那条轴。

这样做的目的是：怪物斜着站在方块拐角时，如果只沿一条轴判断，就可能从两块方块之间的缝里"穿过去"，看起来前面是空的，结果怪物对着围栏干站着不动。分开两条轴依次试，任一轴被挡住就会正常进入挖掘流程。

可及范围：`require-adjacent` 与 `max-distance`

键	默认	效果
`require-adjacent`	`true`	只挖紧贴身体的方块：水平 ±1 格、竖直 −1..+2 格（+2 就是"自己头顶那一格"）
`max-distance`	`4.5`	挖掘距离上限；`require-adjacent: false` 时按它判断

几点实操提醒：

require-adjacent: true 时，max-distance 不生效——邻接优先。想放宽距离必须先把 require-adjacent 设成 false，否则改 max-distance: 8.0 不会有任何效果。
竖直方向的上限是 +2，这是刻意留出来的：怪物要能挖掉自己头顶那格才能继续往上搭路，否则会永远卡在"头顶被压住"的状态。
把 require-adjacent 改成 false 之后，怪物能挖到 4.5 格开外，隔着墙也能对穿，在玩家建筑密集的服务器上建议保持 true。

保护：哪些方块永远不挖

即使一条规则成立了，下面这些检查仍然会拦下来：

保护项	说明
安全黑名单（内置，不可配置）	基岩、屏障、命令方块、结构方块、传送门、移动活塞、刷怪笼、`BUDDING_AMETHYST`，以及硬度 < 0 的方块
世界边界	世界高度之外、世界边界之外一律不动
`protect-mob-blocks: true`（默认）	不挖"怪物自己 / 同伴放下的方块"（登记表里的临时方块）
`safety.disallow-tile-entities: true`（默认）	不挖方块实体：箱子、告示牌、熔炉等
`materials.disabled`	你额外加的禁用列表，默认 `[WATER, LAVA]`
`materials.allowed`	非空时只允许列表内方块，优先级最高

不挖"怪物自己放的方块"

protect-mob-blocks（默认 true）解决一个很具体的翻车场景：一只带镐子的怪物刚用放置搭了一座桥，后面追上来的同伴（或者它自己绕回来）顺手就把桥拆了，来回搭拆变成永动机。

打开这个键之后，插件登记过的临时方块一律不进挖掘候选。这个标记和临时方块的到期清理是同一套登记表，与方块的存活时间无关——不会因为方块快到期了就允许被挖。

`materials.allowed` 与 `materials.disabled` 的关系

materials.allowed 为空（默认）：不启用总白名单，只用 disabled 与内置黑名单做减法。
materials.allowed 非空：只有列表内的方块允许挖，优先级最高。适合"只准它挖石头和泥土，别的都别碰"这类严格服。
materials.disabled 是"再额外禁一批"，写方块名（默认 WATER、LAVA）。只想要"限制范围"却不想维护长白名单时，用 disabled + 内置黑名单通常更省事；想彻底锁死可挖种类才用 allowed。

耗时：三个键怎么算

公式

玩家基础耗时 = 1.5 × 方块硬度                      // 空手近似值，运行时换算，不写死在配置里
怪物耗时     = max(基础耗时 × 有效倍率 ÷ 工具速度系数, break-time.min-seconds)
若 怪物耗时 > break-time.hard-cap-seconds  →  视为“挖不动”，跳过

有效倍率 = 该方块在 materials.multiplier 里的覆盖值；没有覆盖时用 break-time.multiplier（默认 4.0，以木镐为基准）。
工具速度系数来自 tool.speed（木镐 1.0 为基准）；空手且 require-pickaxe: false 时用 tool.hand-speed（默认 0.5）。
倍率 4.0 相对早期版本的 2.0 就是"挖掘速度减半"。想整体加速就把它调小（例如 2.0），想整体变慢就调大。

三个键

键	默认	作用
`break-time.multiplier`	`4.0`	默认倍率（木镐基准），范围 0.01..10000；4.0 = 玩家耗时的 4 倍
`break-time.min-seconds`	`0.2`	最短耗时兜底，硬度 0 的方块（草、花等）按它算
`break-time.hard-cap-seconds`	`180.0`	上限，超过即"挖不动"，范围 0.05..3600

hard-cap-seconds 是已经算完倍率和镐子系数之后的最终秒数，不是硬度。它决定了"哪些方块这只怪物根本啃不动"——调到 500，木镐也能啃黑曜石；调到 60，连铁矿石都会变成禁区。

换算表（默认配置下）

方块	硬度	有效倍率	木镐	铁镐(3.0)	钻石镐(4.0)	默认能否挖
泥土	0.5	4.0	3 s	1 s	0.75 s	能
石头	1.5	4.0	9 s	3 s	2.25 s	能
铁矿石	3.0	4.0	18 s	6 s	4.5 s	能
黑曜石	50	6.0	450 s	150 s	112.5 s	木 / 石镐超上限，铁镐以上可挖
远古残骸	30	8.0	360 s	120 s	90 s	木镐超上限
强化深板岩	100	20.0	3000 s	1000 s	750 s	默认永远挖不动

表里的"有效倍率"就是实际参与计算的值：materials.multiplier 对黑曜石 / 远古残骸 / 强化深板岩有单独覆盖（6.0 / 8.0 / 20.0），没被覆盖的方块才用 break-time.multiplier（4.0）。

"挖不动"的日志

因超过 hard-cap-seconds 被跳过的方块，每种材质会在控制台提示一次：

[MobInteract] OBSIDIAN 的挖掘耗时超过 hard-cap-seconds=…

这条日志很有用：看到它说明"触发了但挖不动"，没看到它说明"根本没触发"——两种情况要调的是完全不同的键。

工具与镐子

配置	默认	作用
`tool.require-pickaxe`	`true`	主手没有镐子就完全不挖
`tool.hand-speed`	`0.5`	空手速度系数，仅 `require-pickaxe: false` 时生效
`tool.speed.<材质>`	见下表	材质 → 速度系数（系数越大越快）
`tool.give.enabled`	`true`	进入世界时按概率发一把镐子
`tool.give.chance`	`0.8`	发放概率
`tool.give.materials.<材质>`	木 60 / 石 25 / 铁 12 / 钻石 3	发放材质的权重表
`tool.give.drop-chance`	`0.0`	插件发放镐子的死亡掉落概率

tool.speed 的默认值（键就是材质名）：WOODEN_PICKAXE 1.0、STONE_PICKAXE 2.0、COPPER_PICKAXE 2.5、IRON_PICKAXE 3.0、GOLDEN_PICKAXE 6.0、DIAMOND_PICKAXE 4.0、NETHERITE_PICKAXE 4.5。

几个容易踩的点：

金镐系数 6.0 比钻石镐 4.0 还高，这是照原版挖掘速度折算的，不是笔误。想让钻石镐最快就自己改成 8.0 之类。
往 tool.speed 里写非镐子条目（比如 IRON_SWORD）会被忽略并告警一次，不会生效。
发放是每只怪只抽一次，主手已经有物品时不覆盖；drop-chance: 0.0 让插件发的镐子不掉落，防止刷装备。
怪物自己捡到的镐子不算"插件发放"，死亡时仍按原版规则掉落。
方块背包是虚拟的，怪物死亡不会掉落背包里的方块。

一次挖掘的完整流程

扫描：每 5 tick 重新扫一次候选方块；有候选就激活任务，抢占移动与朝向，并清掉原版残留的寻路，避免"一边寻路一边挖"互相拉扯。
推进：进度按 break-time.tick-interval（默认 2 tick，范围 1..20）推进；每推进一次就向 feedback.progress-radius（默认 32 格）内的玩家重发裂纹进度，每 feedback.sound-interval（默认 10 tick）播一次命中音效与粒子。
收尾：进度满后把方块移除提交到目标方块所在的区域执行。drop-items: false（默认）直接把方块置为空气；true 时走原版破坏流程（有正常掉落）。成功后进入 cooldown-seconds（默认 8 秒）冷却，失败进 retry-seconds（默认 1.5 秒）重试冷却。
中途续挖：因为原版 AI 抢回控制权、配置热重载等原因导致任务重新激活时，只要还是同一块、且中断在 100 tick（5 秒） 以内，就接着上次的进度挖，不从 0 重来。
停滞放弃：进度推进时会刷新时间戳；连续 3 秒（60 tick）没有任何推进才判定停滞并放弃，控制台打印 挖掘停滞，已放弃，随后进入 retry-seconds 冷却。
玩家插手：玩家点击正在被挖的方块会覆盖掉客户端的裂纹显示，插件会在下一次实体 tick 重发进度——只影响显示，不影响服务端进度，玩家点两下并不能"抢"走这块方块。

cooldown-seconds 是"挖断一块之后歇多久"：默认 8 秒意味着穿墙时要挖一块停一下，观感上像在"思考"，想让它连挖就降到 1~2 秒。

反馈与调试

`feedback.*`

键	默认	说明
`feedback.progress-viewers`	`true`	是否给附近玩家发裂纹进度
`feedback.progress-radius`	`32.0`	裂纹广播半径，1..128
`feedback.particles`	`true`	是否出粒子
`feedback.particle`	`BLOCK`	粒子类型（默认带方块数据）
`feedback.particle-count`	`4`	每次粒子数量
`feedback.sounds`	`true`	是否出音效
`feedback.hit-sound`	`BLOCK_STONE_HIT`	命中音效
`feedback.break-sound`	`BLOCK_STONE_BREAK`	挖断音效
`feedback.sound-interval`	`10`	命中音效间隔（tick）

反馈全部在怪物所属区域的线程里"读方块 + 发包"，不会因为开反馈而把主线程拖住。大服人多时可以只把 progress-radius 调小（比如 16），比直接关掉裂纹体验更好。

`debug`

debug: true 后，控制台会打印每个候选方块的取舍原因：

选中 … 耗时 …
跳过 …：原因

同时也会打印临时方块到期时的续期判定。排查"为什么不挖"和"为什么方块没消失"时非常直接，但它会刷屏——排查完请务必关掉。

可直接复制的配置片段

把下面这段贴进 mining.yml（注释可以保留，也可以删掉）：

# 总开关。false 时所有怪物都不挖。
enabled: true
# 调试日志：打印每个候选方块的取舍原因，会刷屏，排查完关掉。
debug: false

# 世界筛选：白名单留空 = 所有世界；黑名单优先。
worlds:
  whitelist: []
  blacklist: []
# 生物筛选：白名单留空 = 默认人形生物；支持 "*"。
mob-whitelist: []
mob-blacklist: []

# 可及范围。require-adjacent 为 true 时以“邻接”为准，max-distance 不生效。
max-distance: 4.5
require-adjacent: true
# 不挖怪物自己 / 同伴放下的方块，防止边搭边拆。
protect-mob-blocks: true

# 耗时：怪物耗时 = 基础耗时 × 倍率 ÷ 镐子系数，再夹在 min / hard-cap 之间。
break-time:
  multiplier: 4.0          # 木镐基准；4.0 = 玩家耗时的 4 倍
  min-seconds: 0.2         # 硬度 0 的方块按它算
  hard-cap-seconds: 180.0  # 超过就算“挖不动”，直接跳过
  tick-interval: 2         # 进度推进间隔（tick，1..20）

# 工具门槛与镐子速度系数（木镐 = 1.0）。
tool:
  require-pickaxe: true    # 主手没镐子就完全不挖
  hand-speed: 0.5          # 空手系数，仅 require-pickaxe: false 时生效
  speed:
    WOODEN_PICKAXE: 1.0
    STONE_PICKAXE: 2.0
    COPPER_PICKAXE: 2.5
    IRON_PICKAXE: 3.0
    GOLDEN_PICKAXE: 6.0
    DIAMOND_PICKAXE: 4.0
    NETHERITE_PICKAXE: 4.5
  give:
    enabled: true
    chance: 0.8            # 自带镐子的概率
    materials:
      WOODEN_PICKAXE: 60
      STONE_PICKAXE: 25
      IRON_PICKAXE: 12
      DIAMOND_PICKAXE: 3
    drop-chance: 0.0       # 插件发的镐子不掉落，防刷装备

# 方块过滤与逐方块倍率覆盖。
materials:
  disabled:                # 额外禁用（在安全黑名单之外）
    - WATER
    - LAVA
  multiplier:              # 数值越大越慢；等效禁止可以写极大值
    OBSIDIAN: 6.0
    CRYING_OBSIDIAN: 6.0
    ANCIENT_DEBRIS: 8.0
    REINFORCED_DEEPSLATE: 20.0
    RESPAWN_ANCHOR: 10.0
  allowed: []              # 非空时只有列表内的方块允许挖（优先级最高）

# 五条触发规则（优先级从上到下）。
trigger:
  ceiling-blocked: true    # 挖头顶（被压住时先挖自己头顶那格）
  dig-below-self: true     # 目标在下方时挖自己脚下，一格一格往下掉
  dig-under-target: true   # 目标在高处时挖它脚下
  path-blocked: true       # 寻路受阻时挖挡路的方块
  configured-blocks:
    enabled: false
    blocks: []             # 例如 [OAK_FENCE, COBBLESTONE]

# 冷却：挖断一块后歇多久；中断 / 失败后多久重试。
cooldown-seconds: 8.0
retry-seconds: 1.5
# 是否产生掉落物。false = 方块直接消失，防刷物品。
drop-items: false

# 安全限制：不挖方块实体（箱子、告示牌、熔炉等）。
safety:
  disallow-tile-entities: true

# 表现反馈。
feedback:
  progress-viewers: true
  progress-radius: 32.0
  particles: true
  particle: BLOCK
  particle-count: 4
  sounds: true
  hit-sound: BLOCK_STONE_HIT
  break-sound: BLOCK_STONE_BREAK
  sound-interval: 10

常见问题速查

现象	先看这几个键
怪物完全不挖	`enabled`、`worlds.blacklist`、`mob-whitelist`、`tool.require-pickaxe`、`tool.give.chance`（没镐子就真的不挖）
只挖木头泥土，石头挖不动	`materials.disabled` / `allowed`、`break-time.hard-cap-seconds`、`materials.multiplier`
挖得太慢	`break-time.multiplier` 调小、`tool.speed` 给高级镐更高系数、`cooldown-seconds` 调小
挖了不该挖的方块	先加 `materials.disabled`，必要时用 `materials.allowed` 做总白名单
边搭桥边拆桥	确认 `protect-mob-blocks: true`，并检查放置那边的配置
方块挖掉却没有掉落物	这是默认行为，`drop-items: false`；需要掉落改成 `true`
隔着老远拆家	把 `require-adjacent` 设回 `true`
明明确实触发了但没动静	`debug: true` 看取舍原因；如果日志里有 hard-cap 提示，说明是"挖不动"而不是"没触发"

Mining zh

挖掘

它到底会做什么

三道门槛：先过筛，再谈触发

触发：五条规则与优先级

射线判定：不穿透

正前方判定：两条水平轴分别试

可及范围：require-adjacent 与 max-distance

保护：哪些方块永远不挖

不挖"怪物自己放的方块"

materials.allowed 与 materials.disabled 的关系

耗时：三个键怎么算

公式

三个键

换算表（默认配置下）

"挖不动"的日志

工具与镐子

一次挖掘的完整流程

反馈与调试

feedback.*

debug

可直接复制的配置片段

常见问题速查

相关页面

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

可及范围：`require-adjacent` 与 `max-distance`

`materials.allowed` 与 `materials.disabled` 的关系

`feedback.*`

`debug`