Better Veinminer

Version: 1.5.1 | API: Paper 1.21+ | Author: Duong2012G
License: Apache-2.0 | Link: Modrinth

Mine an entire ore vein in one swing — with tier progression, persistent statistics, a custom event API, and deep configuration.

---

Features

Core

• 6-direction BFS — accurate face-adjacent vein detection matching vanilla ore generation; no false positives from diagonal neighbours
• Strict same-type matching — only collects blocks of the exact same material
• Fortune & Silk Touch — work automatically on every block in the vein
• Per-player toggle — each player can enable/disable independently with /bvm toggle
• Unbreaking-aware durability — matches vanilla's per-hit random probability model
• World whitelist/blacklist — restrict which worlds allow veinminer
• Hot reload — /bvm reload applies config changes without a restart

Tier System

Players progress through 4 tiers as they mine more blocks:

Tier	Blocks Required	Max Blocks (default)
1	0	32
2	100,000	64
3	500,000	128
4	1,000,000	256

All thresholds and max-block limits are configurable. Check progress with /bvm tier.

Persistent Statistics

Stats survive server restarts. Saved per-player to plugins/BetterVeinminer/stats/<uuid>.yml:

• Total blocks mined via veinminer
• Total veinmines performed
• Current tier
• Auto-save every 5 minutes (thread-safe snapshot) + on player quit

Daily Limits

Cap veinmines per player per day. Resets at real midnight, persisted across restarts in data.yml. The counter itself is also persisted — a restart mid-day no longer resets progress toward the daily cap.

Custom Event API

BetterVeinmineEvent lets other plugins hook into every veinmine:

@EventHandler
public void onVeinmine(BetterVeinmineEvent event) {
    // Cancel completely (e.g. in protected regions)
    if (isProtected(event.getPlayer())) {
        event.setCancelled(true);
        return;
    }

    // Double EXP on ancient debris
    if (event.getOreType() == Material.ANCIENT_DEBRIS) {
        event.setExpReward(event.getExpReward() * 2);
    }

    plugin.getLogger().info(event.getPlayer().getName()
        + " veinmined " + event.getBlocks().size() + " blocks.");
}

Protection Plugin Support

The main BlockBreakEvent listener runs at HIGH priority (ignoreCancelled = true), so protection plugins (WorldGuard, Lands, GriefPrevention, Residence) that cancel the event at NORMAL or LOW priority are respected — no veinmine task is ever scheduled for a block the player cannot break. For each extra block in the vein a second BlockBreakEvent is fired before breaking, allowing region-level per-block checks. Per-block events are guarded by an anti-recursion lock so the plugin never triggers itself in a loop.

Permission-Based Limits

Give VIP/Premium players special treatment via permission-levels in config. When a player holds multiple permission nodes, the one with the highest max-blocks value always takes precedence — no more random ordering.

Cooldown Feedback

When a player is still on cooldown, the remaining time is shown on the action bar using the configurable cooldown message and its {remaining} placeholder.

Ore Multipliers

Configure different EXP multipliers per ore type.

Per-Ore Cooldowns

Different cooldown per ore type.

---

Installation

1. Download BetterVeinminer-1.5.0.jar
2. Drop into your server's plugins/ folder
3. Restart or reload the server
4. Edit plugins/BetterVeinminer/config.yml
5. Use /bvm reload to apply changes without restarting

Requirements: Paper (or any Paper fork) 1.21+, Java 21+

---

Permissions

Permission	Description	Default
betterveinminer.use	Use veinminer + /bvm toggle/stats/tier	true
betterveinminer.admin	Reload config (/bvm reload)	op
betterveinminer.vip	VIP tier (custom limits via config)	false
betterveinminer.premium	Premium tier (best limits via config)	false

---

Commands

Command	Description	Permission
/bvm toggle	Enable/disable veinminer for yourself	betterveinminer.use
/bvm stats	View your mining statistics	betterveinminer.use
/bvm tier	Check your current tier & progression	betterveinminer.use
/bvm reload	Reload configuration file	betterveinminer.admin

---

How to Use

1. Hold a pickaxe from tool-whitelist
2. Sneak (Shift) if require-sneak: true
3. Break any ore block — the entire connected vein drops at once

Fortune and Silk Touch both work automatically on every block in the vein.

---

Configuration Reference

Basic Settings

enabled: true              # Master on/off switch
require-sneak: true        # Player must sneak to activate
require-pickaxe: true      # Player must hold a whitelisted pickaxe
max-blocks: 64             # Max blocks per veinmine (fallback when tier system is off)
cooldown-ms: 200           # Cooldown between veinmines in milliseconds
damage-tool: true          # Whether the pickaxe takes extra durability damage
damage-multiplier: 1.0     # Multiplier applied to the extra durability loss

Tier System

tier-system:
  enabled: true
  tier-2-threshold: 100000
  tier-3-threshold: 500000
  tier-4-threshold: 1000000
  tier-1-max-blocks: 32
  tier-2-max-blocks: 64
  tier-3-max-blocks: 128
  tier-4-max-blocks: 256

Ore Multipliers

ore-multipliers:
  enabled: true
  multipliers:
    DIAMOND_ORE: 1.5
    EMERALD_ORE: 2.0
    COAL_ORE: 0.5

Per-Ore Cooldowns

per-ore-cooldowns:
  enabled: false
  cooldowns:
    DIAMOND_ORE: 1000
    COAL_ORE: 200

Permission Levels

Players with multiple permission nodes always receive the benefits of the highest-max-blocks entry. Entries are evaluated highest-to-lowest automatically.

permission-levels:
  betterveinminer.vip:
    max-blocks: 128
    cooldown-ms: 100
  betterveinminer.premium:
    max-blocks: 256
    cooldown-ms: 50

Daily Limits

daily-limits:
  enabled: false
  limit-per-day: 10

The daily counter now persists across restarts. The count is only incremented when at least one extra block is actually broken (not when the veinmine is cancelled by another plugin or blocked by a protection plugin).

Custom Messages

All messages support § colour codes.

Message key	Placeholders
veinmine-success	{count}
tier-up	{tier}, {blocks}
stats	{blocks}, {tier}, {uses}
daily-limit	—
cooldown	{remaining}

The cooldown message is now actually sent to the player's action bar when they try to veinmine before the cooldown expires.

EXP Rewards

exp-settings:
  enabled: false
  base-exp: 10
  per-extra-block: 5
  multiply-by-fortune: true

World Restrictions

whitelist-worlds: []
blacklist-worlds: []

Effects

particle-effect: true
sound-effect: true

effects:
  particle-type: BLOCK
  particle-color: "0xFFFFFF"
  particle-speed: 1.0
  completion-sound: BLOCK_STONE_BREAK
  warning-sound: ENTITY_ITEM_PICKUP

---

Config Examples

Survival / Economy Server

tier-system:
  enabled: true
  tier-2-threshold: 50000
  tier-3-threshold: 250000
  tier-4-threshold: 500000

daily-limits:
  enabled: true
  limit-per-day: 5

ore-multipliers:
  enabled: true
  multipliers:
    DIAMOND_ORE: 1.5
    EMERALD_ORE: 2.0

Hardcore Mode

max-blocks: 16
cooldown-ms: 2000
tier-system:
  enabled: false
damage-multiplier: 2.0

---

Developer API

Add as a soft dependency:

softdepend: [BetterVeinminer]

Listen to BetterVeinmineEvent:

import dev.duong2012g.bvm.BetterVeinmineEvent;

@EventHandler
public void onVeinmine(BetterVeinmineEvent event) {
    Player player      = event.getPlayer();
    Material ore       = event.getOreType();
    List<Block> blocks = event.getBlocks();   // unmodifiable
    int exp            = event.getExpReward();

    event.setExpReward(exp * 2);
    event.setCancelled(true);
}

---

Bug Fixes by Version

v1.5.0

#	Bug	Severity	Status
1	Daily-limit counter not persisted — restart bypassed the daily cap	High	✅ Fixed
2	Blocking file I/O on async timer thread for data.yml writes	High	✅ Fixed
3	Cooldown message with {remaining} placeholder never sent to player	Medium	✅ Fixed
4	Permission priority non-deterministic — VIP+Premium received random limits	Medium	✅ Fixed
5	Daily counter incremented before veinmine task confirmed success	Medium	✅ Fixed
6	Cooldown cleanup evicted active entries for long per-ore cooldowns	Medium	✅ Fixed
7	breakNaturally() used stale 1-tick-old tool snapshot for drops	Small	✅ Fixed
8	instance static field not cleared on disable	Small	✅ Fixed
9	BFS visited set unbounded on abnormally large ore clusters	Small	✅ Fixed

---

Troubleshooting

Veinminer not activating:

• Check enabled: true in config
• Verify the ore is in ore-types
• Confirm you hold a pickaxe from tool-whitelist
• Check you are sneaking if require-sneak: true
• Verify the world is not blacklisted

Stats reset after restart:

• Check plugins/BetterVeinminer/stats/ is writable
• Look for "Failed to save stats" warnings in server logs

Daily limit resets on restart:

• Upgrade to v1.5.0 — daily usage is now persisted to data.yml and restored on startup

Daily limit resets too early / not resetting at midnight:

• Ensure you are on v1.4.0+ — the old tick-based timer drifted and was skipped on restarts
• The system persists the last reset date to data.yml and checks every 2 minutes

Cooldown message not showing:

• Upgrade to v1.5.0 — prior versions silently skipped cooldown feedback

---

Changelog

See CHANGELOG.md

---

License

Apache-2.0 © Duong2012G