Mining

← Back to the index

With this plugin installed, humanoid mobs — zombies, skeletons, piglins and friends — pick up a pickaxe and mine blocks themselves: the block pressing down on their head, the block in their way, the block under your feet. They work out how long it takes and then dig through it in front of you. This page covers when they mine, what they can actually break, how long a block takes, and how to tune every key in mining.yml.

What it actually does

With a pickaxe in the main hand, a mob that runs into a blocking block mines it on the spot instead of walking around, grinding against a wall, or just standing there.
Mining is never instant: the duration is derived from block hardness × your multiplier ÷ pickaxe speed factor, and nearby players see crack progress, particles and hit sounds.
By default no items are dropped — the block simply disappears, which keeps item farming off the table.
By default mobs only mine blocks touching their body, so they cannot tear your base apart from three blocks away.

Three gates: filtered first, triggered later

Before "which block gets mined" even matters, a mob has to pass three gates. Fail any one and it does nothing at all:

Switch and filters — enabled: true, the world is not in worlds.blacklist (if worlds.whitelist is non-empty, only those worlds count), and the mob type passes mob-whitelist / mob-blacklist.
Tool gate — with tool.require-pickaxe: true (the default), a mob whose main hand is not a pickaxe does not mine at all; it will not even pick a candidate block. Whether mobs carry pickaxes is decided by tool.give.*.
Per-block checks — each candidate must pass the tool, material, safety, reach, protection and duration checks in turn. Only then is it a candidate.

Triggers: five rules and their priority

The five rules are evaluated in order, and the first hit returns — once a rule matches, the later ones are never considered. This is the first thing to look at when a mob "refuses" to mine the block you wanted it to mine.

Order	Trigger	Condition	Config key
0	Tool gate	`require-pickaxe: true` and the main hand is not a pickaxe → no mining at all	`tool.require-pickaxe`
1	Mine the ceiling	The target is ≥1.5 blocks higher and the second block above the mob's feet is occupied	`trigger.ceiling-blocked`
2	Mine under itself	The target is ≥1.5 blocks lower, within 3 blocks horizontally, the mob stands on the ground, and the second block below its feet is not a liquid	`trigger.dig-below-self`
3	Mine under the target	The target is ≥0.5 blocks higher and the block below it is mineable	`trigger.dig-under-target`
4	Pathfinding blocked	Checks the two blocks at foot / head level straight ahead first, then the first solid block on the "eyes → target" ray	`trigger.path-blocked`
5	Configured blocks	A block listed in `trigger.configured-blocks.blocks` appears within `max-distance` ahead (line of sight not required)	`trigger.configured-blocks.enabled`

Note the difference between rules 1 and 3: mine the ceiling means "I am pinned down, I have to clear the block above my own head before I can stack up"; mine under the target means "the target is standing up high, drop it by removing the block beneath it". They are toggled separately by trigger.ceiling-blocked and trigger.dig-under-target.

Ray casting: it does not pass through

The "eyes → target" ray used by rule 4 has one important property: it does not pass through blocks.

If the first non-passable block on the ray is mineable, that is the block it mines;
if the first non-passable block is not mineable (bedrock, a protected area, something in materials.disabled, …), the attempt is abandoned outright. It never routes around that block to reach something behind it.

The ray is sampled from the body's outer edge (skipping the mob's own footprint), with a step of 0.25 blocks and at most 64 sample points — precise enough to catch diagonal gaps and slab edges without costing server time.

Straight-ahead check: each horizontal axis is tried separately

The first half of rule 4 (the two blocks at foot / head level straight ahead) is evaluated on each of the two horizontal axes separately, and the axis with the larger horizontal delta is tried first.

The reason is subtle: when a mob stands diagonally at a block corner, checking only one axis can make the space between two blocks look passable. The mob "slips through" the gap on paper, but in reality it stands uselessly in front of a fence. Trying both axes in turn means any blocked axis properly enters the mining flow.

Reach: `require-adjacent` and `max-distance`

Key	Default	Effect
`require-adjacent`	`true`	Only blocks touching the body: horizontal ±1, vertical −1..+2 (where +2 is "the block right above its own head")
`max-distance`	`4.5`	Maximum mining distance; used when `require-adjacent: false`

Practical notes:

While require-adjacent: true, max-distance has no effect — adjacency wins. To widen the reach you must first set require-adjacent: false; changing max-distance: 8.0 on its own does nothing.
The vertical range deliberately stops at +2: a mob must be able to clear the block above its own head, otherwise it can never stack its way up and stays pinned forever.
With require-adjacent: false a mob can mine up to 4.5 blocks away and right through walls. On servers with dense player builds, keep it true.

Protection: blocks that are never mined

Even when a rule matches, these checks can still veto it:

Protection	Behaviour
Built-in safety blacklist (not configurable)	Bedrock, barriers, command blocks, structure blocks, portals, moving pistons, monster spawners, `BUDDING_AMETHYST`, and anything with hardness < 0
World limits	Nothing outside the world height or the world border is ever touched
`protect-mob-blocks: true` (default)	Never mines blocks placed by the mob itself or its companions (the temporary blocks in the registry)
`safety.disallow-tile-entities: true` (default)	Never mines block entities: chests, signs, furnaces, …
`materials.disabled`	Your additional deny list, default `[WATER, LAVA]`
`materials.allowed`	When non-empty, only the listed blocks may be mined; highest priority

Never mining blocks the mob placed itself

protect-mob-blocks (default true) solves a very specific failure mode: a mob with a pickaxe has just built a bridge using placement, and then a companion chasing behind it — or the same mob looping back — cheerfully tears the bridge down. Build, demolish, build, demolish: a perpetual motion machine.

With this key enabled, any block in the plugin's temporary-block registry is excluded from mining candidates. The flag shares that registry with the temporary-block expiry cleanup, and it is independent of the block's remaining lifetime — a block does not become mineable just because it is about to expire.

`materials.allowed` versus `materials.disabled`

materials.allowed empty (default): no master whitelist; only disabled and the built-in blacklist subtract from the set.
materials.allowed non-empty: only listed blocks may be mined, and it has the highest priority. Use it on strict servers ("stone and dirt only, nothing else").
materials.disabled adds further denials by block name (default WATER, LAVA). If you only want to limit the range without maintaining a long whitelist, disabled plus the built-in blacklist is usually less work; reserve allowed for locking the mineable set down completely.

Duration: how the three keys work

The formula

player base duration = 1.5 × block hardness            // bare-hand approximation, computed at runtime, never hard-coded
mob duration         = max(base duration × effective multiplier ÷ tool speed factor, break-time.min-seconds)
if mob duration > break-time.hard-cap-seconds  →  treated as "cannot be mined" and skipped

Effective multiplier = the per-block override in materials.multiplier; blocks without an override use break-time.multiplier (default 4.0, wooden-pickaxe baseline).
Tool speed factor comes from tool.speed (wooden pickaxe = 1.0 baseline); bare hands use tool.hand-speed (default 0.5) when require-pickaxe: false.
A multiplier of 4.0 versus 2.0 in earlier versions simply means half the mining speed. Lower it (say 2.0) to speed everything up, raise it to slow everything down.

The three keys

Key	Default	Purpose
`break-time.multiplier`	`4.0`	Default multiplier (wooden-pickaxe baseline), range 0.01..10000; 4.0 = 4× the player's duration
`break-time.min-seconds`	`0.2`	Floor for zero-hardness blocks (grass, flowers, …)
`break-time.hard-cap-seconds`	`180.0`	Hard cap; anything above it counts as "cannot be mined", range 0.05..3600

hard-cap-seconds is a final number of seconds, after multiplier and pickaxe factor are applied — not a hardness value. It decides which blocks a given mob simply cannot chew through: set it to 500 and a wooden pickaxe can grind obsidian; set it to 60 and even iron ore becomes off-limits.

Conversion table (default configuration)

Block	Hardness	Effective multiplier	Wooden pickaxe	Iron pickaxe (3.0)	Diamond pickaxe (4.0)	Mineable by default
Dirt	0.5	4.0	3 s	1 s	0.75 s	Yes
Stone	1.5	4.0	9 s	3 s	2.25 s	Yes
Iron ore	3.0	4.0	18 s	6 s	4.5 s	Yes
Obsidian	50	6.0	450 s	150 s	112.5 s	Wooden / stone pickaxe exceed the cap; iron and above can mine it
Ancient debris	30	8.0	360 s	120 s	90 s	Wooden pickaxe exceeds the cap
Reinforced deepslate	100	20.0	3000 s	1000 s	750 s	Never mineable by default

The "effective multiplier" column is exactly what the calculation uses: materials.multiplier overrides obsidian / ancient debris / reinforced deepslate (6.0 / 8.0 / 20.0), and only blocks without an override fall back to break-time.multiplier (4.0).

The "cannot be mined" log line

Blocks skipped for exceeding hard-cap-seconds produce one console notice per material:

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

That line is genuinely useful: seeing it means "triggered but too slow to break", while not seeing it means "never triggered at all" — two problems you fix with completely different keys.

Tools and pickaxes

Config	Default	Purpose
`tool.require-pickaxe`	`true`	No pickaxe in the main hand means no mining at all
`tool.hand-speed`	`0.5`	Bare-hand speed factor, only effective with `require-pickaxe: false`
`tool.speed.<material>`	see below	Material → speed factor (larger = faster)
`tool.give.enabled`	`true`	Hand out a pickaxe when entering the world
`tool.give.chance`	`0.8`	Grant chance
`tool.give.materials.<material>`	wood 60 / stone 25 / iron 12 / diamond 3	Weight table for the granted material
`tool.give.drop-chance`	`0.0`	Death drop chance for plugin-granted pickaxes

Default tool.speed factors, keyed by material name exactly as written in the file: 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.

Things that trip people up:

Golden pickaxe 6.0 is faster than diamond 4.0. That mirrors vanilla mining speeds and is not a typo. If you want diamond to be the best, set it to 8.0 or so.
Putting a non-pickaxe entry (say IRON_SWORD) into tool.speed gets ignored with a warning.
The grant is rolled once per mob, and an existing main-hand item is never overwritten; drop-chance: 0.0 keeps plugin-granted pickaxes from dropping, which blocks equipment farming.
A pickaxe a mob picked up does not count as "plugin-granted" and still drops by vanilla rules.
The block backpack is virtual — a mob's death never drops the blocks it carries.

Full lifecycle of a single mining action

Scan — candidates are rescanned every 5 ticks. If one exists, the task activates, claims movement and look control, and clears leftover vanilla pathfinding so the mob does not fight itself.
Progress — advances every break-time.tick-interval (default 2 ticks, range 1..20). Each step resends crack progress to players within feedback.progress-radius (default 32 blocks), and every feedback.sound-interval (default 10 ticks) a hit sound and particles play.
Completion — the block removal is dispatched to the region that owns the target block. drop-items: false (default) just sets the block to air; true runs the vanilla break flow (normal drops). Success starts a cooldown-seconds (default 8 s) cooldown; failure starts a retry-seconds (default 1.5 s) retry cooldown.
Resuming mid-way — when the task reactivates (vanilla AI grabbed control back, the config was hot-reloaded, …), progress continues from where it stopped as long as it is still the same block and the interruption lasted at most 100 ticks (5 s). It never restarts from zero.
Stall give-up — the timestamp is refreshed on every progress step; only 3 seconds (60 ticks) with no progress counts as a stall. The action is abandoned with 挖掘停滞，已放弃 on the console, then the retry-seconds cooldown applies.
Player interference — a player clicking the block being mined overwrites the client-side crack display; the plugin resends progress on the next entity tick. This only affects the display, never server-side progress, so clicking twice does not "steal" the block.

cooldown-seconds is the pause after each broken block: 8 seconds by default means a mob digging through a wall mines one block, pauses, mines one, pauses — which reads as "thinking". Drop it to 1–2 seconds for continuous digging.

Feedback and debugging

`feedback.*`

Key	Default	Notes
`feedback.progress-viewers`	`true`	Send crack progress to nearby players
`feedback.progress-radius`	`32.0`	Crack broadcast radius, 1..128
`feedback.particles`	`true`	Enable particles
`feedback.particle`	`BLOCK`	Particle type (block data by default)
`feedback.particle-count`	`4`	Particles per burst
`feedback.sounds`	`true`	Enable sounds
`feedback.hit-sound`	`BLOCK_STONE_HIT`	Hit sound
`feedback.break-sound`	`BLOCK_STONE_BREAK`	Break sound
`feedback.sound-interval`	`10`	Hit sound interval (ticks)

All feedback runs on the mob's own region thread as "read block + send packet", so enabling it never blocks the main thread. On crowded servers, shrinking progress-radius (say 16) is usually a better trade than turning cracks off entirely.

`debug`

With debug: true the console prints the accept/reject reason for every candidate block:

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

It also prints the renewal decision when a temporary block expires. This is the most direct way to diagnose "why isn't it mining" and "why doesn't that block disappear", but it floods the log — turn it back off once you are done.

Copy-paste configuration

Drop this into mining.yml (keep the comments or delete them):

# Master switch. false = no mob mines anything.
enabled: true
# Debug logging: prints the accept/reject reason per candidate block. Floods the log.
debug: false

# World filter: empty whitelist = all worlds; blacklist wins.
worlds:
  whitelist: []
  blacklist: []
# Mob filter: empty whitelist = default humanoids; "*" supported.
mob-whitelist: []
mob-blacklist: []

# Reach. With require-adjacent: true, adjacency wins and max-distance is ignored.
max-distance: 4.5
require-adjacent: true
# Never mine blocks the mob or its companions placed (no build-then-demolish loops).
protect-mob-blocks: true

# Duration = base × multiplier ÷ pickaxe factor, clamped between min and hard cap.
break-time:
  multiplier: 4.0          # wooden-pickaxe baseline; 4.0 = 4× the player's duration
  min-seconds: 0.2         # floor for zero-hardness blocks
  hard-cap-seconds: 180.0  # above this = "cannot be mined", skipped outright
  tick-interval: 2         # progress interval in ticks (1..20)

# Tool gate and pickaxe speed factors (wooden = 1.0).
tool:
  require-pickaxe: true    # no pickaxe in the main hand = no mining at all
  hand-speed: 0.5          # bare-hand factor, only used with 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            # chance of carrying a pickaxe
    materials:
      WOODEN_PICKAXE: 60
      STONE_PICKAXE: 25
      IRON_PICKAXE: 12
      DIAMOND_PICKAXE: 3
    drop-chance: 0.0       # granted pickaxes never drop (anti-farming)

# Block filtering and per-block multiplier overrides.
materials:
  disabled:                # extra denials on top of the safety blacklist
    - WATER
    - LAVA
  multiplier:              # larger = slower; use a huge value for "effectively never"
    OBSIDIAN: 6.0
    CRYING_OBSIDIAN: 6.0
    ANCIENT_DEBRIS: 8.0
    REINFORCED_DEEPSLATE: 20.0
    RESPAWN_ANCHOR: 10.0
  allowed: []              # when non-empty, only these blocks may be mined (highest priority)

# The five triggers, top to bottom in priority.
trigger:
  ceiling-blocked: true    # clear the block above its own head when pinned down
  dig-below-self: true     # target below: dig out its own feet, one block at a time
  dig-under-target: true   # target above: dig out the block beneath it
  path-blocked: true       # dig through whatever blocks the path
  configured-blocks:
    enabled: false
    blocks: []             # e.g. [OAK_FENCE, COBBLESTONE]

# Cooldowns: after a broken block, and after an interruption / failure.
cooldown-seconds: 8.0
retry-seconds: 1.5
# Produce drops? false = the block just vanishes (anti-farming).
drop-items: false

# Safety: never mine block entities (chests, signs, furnaces, …).
safety:
  disallow-tile-entities: true

# Visual / audio feedback.
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

Quick troubleshooting

Symptom	Check these first
Mobs never mine	`enabled`, `worlds.blacklist`, `mob-whitelist`, `tool.require-pickaxe`, `tool.give.chance` (no pickaxe really means no mining)
Only wood and dirt, stone never breaks	`materials.disabled` / `allowed`, `break-time.hard-cap-seconds`, `materials.multiplier`
Mining is too slow	Lower `break-time.multiplier`, give better pickaxes a higher `tool.speed`, lower `cooldown-seconds`
It mines blocks it should not	Add them to `materials.disabled`; use `materials.allowed` as a master whitelist if needed
It builds a bridge and immediately tears it down	Confirm `protect-mob-blocks: true` and check the placement side
Blocks vanish without drops	That is the default, `drop-items: false`; set it to `true` to get drops
It demolishes things from far away	Set `require-adjacent` back to `true`
It clearly triggered but nothing happens	Turn on `debug: true`; if a hard-cap line shows up, it is "too slow to break", not "never triggered"

Related pages

← Back to the index
Placement (path building) — bridges and demolitions share the same temporary-block registry
Backpack and Pickup — where the blocks come from and how pickaxes are picked up
Equip and Messages — spawn-equipment chance and message texts
Commands — reload applies mining config immediately
FAQ
Changelog — why break-time.multiplier moved from 2.0 to 4.0

MobInteract · QQ 群 995974858 · Repository · Releases · Issues · English | 简体中文

MobInteract

English (default)

简体中文

Mining

Mining

What it actually does

Three gates: filtered first, triggered later

Triggers: five rules and their priority

Ray casting: it does not pass through

Straight-ahead check: each horizontal axis is tried separately

Reach: require-adjacent and max-distance

Protection: blocks that are never mined

Never mining blocks the mob placed itself

materials.allowed versus materials.disabled

Duration: how the three keys work

The formula

The three keys

Conversion table (default configuration)

The "cannot be mined" log line

Tools and pickaxes

Full lifecycle of a single mining action

Feedback and debugging

feedback.*

debug

Copy-paste configuration

Quick troubleshooting

Related pages

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

Reach: `require-adjacent` and `max-distance`

`materials.allowed` versus `materials.disabled`

`feedback.*`

`debug`