Better Veinminer

🌐 English

Version: 1.5.3 | API: Paper 26.1 – 26.3 (Java 25) | Author: Duong2012G License: Apache-2.0 | Link: Modrinth

Mine a whole ore vein with one swing. Out of the box every player can use it with the same limit — no permissions, tiers or daily caps get in the way. Tiers, permission levels (VIP / Premium), daily limits and per-ore cooldowns are optional advanced features for server admins.

---

Features

Feature	Description
Same-type vein mining	Finds every ore of the same type that is connected through block faces (6-direction breadth-first search) and breaks them all. The block you break is the origin; at most max-blocks blocks (default 64, for everyone) are mined per swing. Ores that touch only at a corner are not part of the vein.
Ores and tools through vanilla tags	Ores come from the vanilla block tags (coal_ores, iron_ores, copper_ores, gold_ores, redstone_ores, lapis_ores, diamond_ores, emerald_ores) plus NETHER_QUARTZ_ORE and ANCIENT_DEBRIS; tools from the pickaxes item tag, so the Copper Pickaxe works and so will ores and pickaxes added later. Add single materials with ore-types / tool-whitelist, remove with ore-exclude / tool-exclude.
Sneak to activate	Veinmining only triggers while sneaking (require-sneak) with a pickaxe in hand (require-pickaxe), so normal mining is never affected. /bvm toggle switches it off/on for yourself (not saved — resets when you log out).
Fortune & Silk Touch	Every extra block is broken with your actual pickaxe, so Fortune, Silk Touch and the correct-tool rule behave like vanilla (a pickaxe that cannot harvest the ore yields no drops, like vanilla).
Vanilla XP for every ore	Extra ores drop their normal XP (vanilla-exp, v1.5.3). Silk Touch and Creative mode give none, like vanilla. Optional custom EXP on top: see exp-settings.
Durability-aware	Mined blocks cost durability (damage-tool, damage-multiplier) with a per-hit Unbreaking roll like vanilla. With limit-by-durability the veinmine only mines as many blocks as the tool can afford, instead of mining everything and breaking it (v1.5.3). Unbreakable tools, tools with a custom max durability and Creative mode are handled correctly; damage goes through the server's item-damage API, so item-damage / item-break events and the break animation work like vanilla (v1.5.3).
Protection plugin support	Fires a normal BlockBreakEvent for each extra block, so protection plugins that work through that event can cancel individual blocks (cancelled blocks are skipped, the rest of the vein is still mined). Veinmining only starts when the player's own break was not cancelled, at any plugin priority (v1.5.3).
Drop-plugin friendly	If another plugin sets setDropItems(false) on one of those events (custom drops, auto-pickup...), the block is removed without vanilla drops instead of dropping twice (v1.5.3).
Lag-friendly	Big veins are mined over several ticks (blocks-per-tick, default 50) and the search never loads unloaded chunks (v1.5.3).
Anti-recursion guard	While a veinmine batch runs, the player is held in an internal set so the plugin ignores the BlockBreakEvents it fires itself.
Effects	A particle effect at the origin block and a completion sound for the player when a veinmine finishes. Choose the particle (BLOCK, SMOKE, DUST with a colour...) and the sound in effects; invalid values are reported in the console.
Statistics	Blocks mined and veinmines used are tracked per player (/bvm stats) and saved in plugins/BetterVeinminer/stats/<uuid>.yml; only changed players are written, asynchronously.
World restrictions	whitelist-worlds / blacklist-worlds, by world name or world key (minecraft:overworld).
Developer API	Cancellable BetterVeinmineEvent fired right before the extra blocks are mined.

Optional features for server admins (all off by default)

Feature	What it does
Tier system (tier-system.enabled)	Players level up through 4 tiers by veinmining blocks (100 000 / 500 000 / 1 000 000 blocks by default). The tier replaces the global max-blocks with its own limit (32 / 64 / 128 / 256 by default). Progress is tracked even while the system is off, so enabling it later keeps everyone's progress. /bvm tier shows the player's limit and progress.
Permission levels (permission-levels)	Reward some players: whoever holds the permission of an entry gets that entry's max-blocks and/or cooldown-ms. Entries only raise the limit and lower the cooldown; nobody needs a permission to veinmine. The nodes betterveinminer.vip and betterveinminer.premium exist and default to false, but any node can be used.
Daily limits (daily-limits)	Cap the number of veinmines per player per day (default 10 when enabled). Resets at the server's local midnight; the counters are saved with the periodic auto-save.
Per-ore cooldowns (per-ore-cooldowns)	A separate cooldown for each ore. When enabled it replaces the normal cooldown, including the faster cooldown of permission levels.
Custom EXP (exp-settings)	A bonus EXP reward per veinmine (base-exp + per-extra-block for each extra block), optionally multiplied by the Fortune level and by ore-multipliers. Added on top of the vanilla XP.

---

Requirements

• A Paper server on Minecraft 26.3 (compiled against the 26.3 API). plugin.yml declares api-version: 26.1, so 26.1 and 26.2 are allowed to load it, but only 26.3 has been targeted.
• Java 25 (required by Minecraft 26.x itself)
• Servers on 1.21.x must stay on BetterVeinminer 1.5.2.
• Paper API only: Spigot is not supported, and Folia is not declared supported.

Installation

1. Put BetterVeinminer-1.5.3.jar into your server's plugins/ folder.
2. Start the server once; plugins/BetterVeinminer/config.yml is created.
3. Edit it and apply changes with /bvm reload (no restart needed).

Upgrading from an older version keeps your config.yml: keys that are missing fall back to the new defaults automatically. Stats files and data.yml keep their format.

---

How to use

By default you must sneak (Shift), hold a pickaxe, and mine an ore. The whole vein is mined with that single swing, within the limits below.

Veinmining only triggers when all of these hold:

• enabled: true, the player has betterveinminer.use (everyone does by default) and has not used /bvm toggle to switch it off
• the world is allowed (whitelist / blacklist) and the broken block is an enabled ore
• the player is sneaking (when require-sneak: true) and holds a configured tool (when require-pickaxe: true)
• the player's own break was not cancelled, their cooldown has expired and, if enabled, the daily limit is not reached

In Creative mode veins are mined too, but nothing drops and the tool takes no damage.

Commands & permissions

Command	Permission	Description
/bvm toggle	betterveinminer.use (default: everyone)	Turn veinmining on/off for yourself. Not saved — resets when you log out.
/bvm stats	betterveinminer.use	Show your blocks mined, tier and veinmines used.
/bvm tier	betterveinminer.use	Show your current limit and, if the tier system is on, your tier and progress.
/bvm reload	betterveinminer.admin (default: op)	Reload config.yml.

/veinminer is an alias of /bvm. The /bvm command itself requires betterveinminer.use, which everyone has by default. betterveinminer.vip and betterveinminer.premium (default: nobody) do nothing on their own — they only matter when a permission-levels entry uses them.

---

Configuration

Everything lives in plugins/BetterVeinminer/config.yml. Out-of-range numbers are clamped.

Key	Default	Range	Description
enabled	true		Master switch.
require-sneak	true		Player must be sneaking.
require-pickaxe	true		Player must hold a tool from the tool list.
max-blocks	64	1 – 1000	Max blocks per veinmine, origin included, the same for everyone (unless tiers or permission levels are on).
cooldown-ms	200	0 – 300000	Per-player cooldown between veinmines.
blocks-per-tick	50	1 – 1000	Extra blocks mined per tick. Lower = smoother, higher = faster.
damage-tool	true		Veinmined blocks cost tool durability.
damage-multiplier	1.0	0.1 – 10.0	Durability cost per extra block.
limit-by-durability	true		Only mine as many blocks as the tool can afford.
vanilla-exp	true		Drop the vanilla XP of every extra ore.
particle-effect	true		Spawn the particle effect.
sound-effect	true		Play the sounds.
effects.particle-type	BLOCK		Particle name or key. Only particles that need no data, a block, or a dust colour are supported.
effects.particle-color	"0xFFFFFF"		Colour for the DUST particle: 0xRRGGBB, #RRGGBB or RRGGBB.
effects.particle-speed	1.0	0 – 20	Particle spread speed.
effects.completion-sound	BLOCK_STONE_BREAK		Sound played when a veinmine completes (enum-style name or key).
effects.warning-sound	ENTITY_ITEM_PICKUP		Sound played when the daily limit is reached.
tier-system.enabled	false		Optional tier system.
tier-system.tier-2/3/4-threshold	100000 / 500000 / 1000000	≥ 0	Blocks mined to reach each tier.
tier-system.tier-1/2/3/4-max-blocks	32 / 64 / 128 / 256	1 – 1000	Limit of each tier.
permission-levels	{}		Optional. Entries keyed by permission node, each with max-blocks and/or cooldown-ms.
daily-limits.enabled	false		Optional daily cap.
daily-limits.limit-per-day	10	1 – 100000	Veinmines per player per day.
per-ore-cooldowns.enabled / .cooldowns	false	0 – 300000	Optional per-ore cooldown (ore name → ms); unlisted ores use cooldown-ms.
exp-settings.enabled	false		Optional custom EXP bonus.
exp-settings.base-exp / .per-extra-block	10 / 5	0 – 10000 / 0 – 1000	Bonus formula.
exp-settings.multiply-by-fortune	true		Multiply the bonus by (1 + Fortune level).
ore-multipliers.enabled / .multipliers	true	0 – 100	Per-ore multiplier of the custom EXP bonus only — no effect while exp-settings.enabled is false.
messages.*	see file		veinmine-success, cooldown, tier-up, daily-limit, stats (legacy § colours; placeholders {count} {remaining} {tier} {blocks} {uses}).
whitelist-worlds	[]		If non-empty, only these worlds (name or key). Takes precedence.
blacklist-worlds	[]		Worlds where veinmining is disabled (checked only when the whitelist is empty).
ore-tags	coal_ores, iron_ores, copper_ores, gold_ores, redstone_ores, lapis_ores, diamond_ores, emerald_ores		Vanilla/datapack block tags (without #).
ore-types	NETHER_QUARTZ_ORE, ANCIENT_DEBRIS		Single materials added on top of the tags.
ore-exclude	[]		Materials removed again.
tool-tags	[pickaxes]		Vanilla/datapack item tags (without #).
tool-whitelist	[]		Single materials added on top of the tags.
tool-exclude	[]		Materials removed again.

Ore set = ore-tags + ore-types − ore-exclude; tool set = tool-tags + tool-whitelist − tool-exclude.

How the limits combine: the max blocks of a player is max-blocks (or their tier's limit when the tier system is on), raised by the highest max-blocks of any permission level they hold. The cooldown is the per-ore cooldown when that is enabled; otherwise cooldown-ms, lowered by the lowest cooldown-ms of any permission level they hold.

Examples:

# Reward VIPs: bigger veins and a shorter cooldown (everyone else keeps the normal limits)
permission-levels:
  betterveinminer.vip:
    max-blocks: 128
    cooldown-ms: 100

# Keep ancient debris out of veinmining
ore-exclude:
  - ANCIENT_DEBRIS

# Allow ONLY iron and better pickaxes
tool-tags: []
tool-whitelist:
  - IRON_PICKAXE
  - DIAMOND_PICKAXE
  - NETHERITE_PICKAXE

If an entry is unknown (a typo, or a tag/sound/particle that does not exist on your server version), a warning is printed to the console on startup and on /bvm reload.

---

Developer API

BetterVeinmineEvent is fired on the main thread, one tick after the player's own break, right before the extra blocks are mined. Cancel it to stop the veinmine. It is not fired when the vein is rejected earlier (e.g. the player swapped the tool, or the tool cannot afford a single extra block).

@EventHandler
public void onVeinmine(BetterVeinmineEvent e) {
    if (e.getOreType() == Material.ANCIENT_DEBRIS) {
        e.setCancelled(true);                     // no veinmining on ancient debris
    }
    List<Block> blocks = e.getBlocks();           // unmodifiable; the origin block is NOT included;
                                                  // already limited by the tool's durability
    e.setExpReward(e.getExpReward() * 2);         // the custom EXP bonus (0 while exp-settings is off)
}

Every extra block is then broken through a regular BlockBreakEvent fired for the player.

Known limitations

• Extra blocks are broken with Block#breakNaturally, so plugins that depend on BlockDropItemEvent (some auto-pickup / auto-smelt plugins) may not see the drops of the extra blocks.
• A vein is the ores of one exact material connected through faces: the stone and deepslate variants of an ore (e.g. DIAMOND_ORE and DEEPSLATE_DIAMOND_ORE) are separate veins.

---

Changelog

See CHANGELOG.md.