Presets & Tags

zVeinMiner never turns vein mining on for every tool. A tool only vein mines once it carries vein mining data: a size (how many blocks one vein can contain) and a list of tags (which blocks can be vein mined). This data is stored on the item itself (in its PersistentDataContainer), so it stays on the item when it is traded, stored in a chest or renamed.

The easiest way to give this data to an item is a preset, defined in config.yml.

Defining presetsCopy Anchor Link

Presets are declared in the presets list of config.yml. Each entry needs three keys:

The default configuration ships one preset:

presets:
  - name: "pickaxe-1"
    size: 8
    tags:
      - COAL_ORES
      - COPPER_ORES
      - DIAMOND_ORES
      - EMERALD_ORES
      - GOLD_ORES
      - IRON_ORES
      - LAPIS_ORES
      - REDSTONE_ORES
      - ANCIENT_DEBRIS

Presets are loaded in the order of config.yml and reloaded with /zveinminer reload. A broken entry does not stop the loading: it is skipped with a warning in the console.

TagsCopy Anchor Link

Each entry of tags (in a preset or added with /zveinminer add) is one of:

Rules applied when a tag is read:

• Names are not case sensitive (coal_ores and COAL_ORES are the same) and surrounding spaces are ignored.
• Tags are the names of the constants of Bukkit's Tag class (for example COAL_ORES, IRON_ORES, LOGS, CRIMSON_STEMS), not namespaced keys like minecraft:coal_ores. A tag name is checked first, then a material name.
• Only block materials are accepted. Items that cannot be placed in the world are rejected.
• NETHERITE_SCRAP (used by older default configurations) is automatically converted to ANCIENT_DEBRIS.

How the vein follows a tagCopy Anchor Link

When you break a block, zVeinMiner looks at the tags of your tool in their order and keeps the first one that matches the broken block. The match-by-tag option (section vein-mining of config.yml) then decides which neighbouring blocks belong to the vein:

vein-mining:
  match-by-tag: true

When a material name matches (for example DIAMOND_ORE), only that exact block is connected, whatever the value of match-by-tag.

Giving vein mining data to an itemCopy Anchor Link

Five commands write vein mining data on the item held in the main hand (or on a new item for give). They do not work on an empty hand.

apply: linked to the presetCopy Anchor Link

/zveinminer apply pickaxe-1

The item only remembers the name pickaxe-1. Change the size or the tags of pickaxe-1 in config.yml, run /zveinminer reload, and every item that received apply pickaxe-1 uses the new values. If the preset is removed from the configuration, these items stop vein mining (unless they have their own size and tags).

set and give: a frozen copyCopy Anchor Link

/zveinminer set pickaxe-1
/zveinminer give Maxlego08 pickaxe-1 NETHERITE_PICKAXE

The size and tags of the preset are copied onto the item. Editing the preset later does not change these items. give creates a new item of the given material (default DIAMOND_PICKAXE), copies the preset onto it and gives it to an online player whose name must be exact. If the inventory is full, the item is dropped at the player's feet.

add, remove and size: fine tuning one itemCopy Anchor Link

/zveinminer add GRAVEL
/zveinminer remove DIAMOND_ORES
/zveinminer size 16
/zveinminer size

• add and remove start from the current tags of the item (including the tags inherited from an applied preset) and write the resulting list on the item. From then on, the item keeps its own tag list instead of the preset one. Removing the last tag leaves the item with no tag: it does not fall back to the preset tags.
• size <size> stores a size on the item. It must be a whole number 0 or more and, when max-size-limit is greater than 0, cannot be greater than max-size-limit. size 0 removes the size stored on the item, so it uses the size of its applied preset again.
• size without argument displays the current size of the held item.

Which value winsCopy Anchor Link

The item values always win over the preset values:

Use /zveinminer info to display the size and tags resolved for the held item (the size shown is the stored or preset value, before the max-size-limit cap).

Vein size and max-size-limitCopy Anchor Link

The size is the total number of blocks of a vein, the broken block included: a size of 8 breaks the block you mine plus up to 7 more.

vein-mining:
  # Maximum vein size limit (overrides preset if lower)
  max-size-limit: 64

• max-size-limit caps every vein, whatever the size of the preset or of the item. With max-size-limit: 64, an item with a size of 200 mines at most 64 blocks.
• max-size-limit: 0 (or lower) disables the cap.
• A size of 1 or less never triggers vein mining: the block is broken normally.

Vein detectionCopy Anchor Link

When a block is broken with a valid tool, the vein is searched with a breadth-first search (BFS) starting from that block:

1. The 26 surrounding blocks (faces, edges and corners) of each block are checked, so diagonal ores are part of the vein.
2. A block joins the vein if it matches the tag (see How the vein follows a tag) and the held tool is the right tool to harvest it.
3. The search stops when the vein reaches its size, and the closest blocks are found first.

The search never goes outside the world height, outside the world border, or into an unloaded chunk.

Vein mining is only triggered if all these conditions are met:

Each extra block is broken as if the player broke it: a BlockBreakEvent is fired for every block, the drops, Fortune, Silk Touch and experience of the tool apply, and protection plugins can refuse any of them (see Integrations).

Preview while sneakingCopy Anchor Link

When the player starts sneaking while looking at a block (up to 5 blocks away) that their tool could vein mine, the outline of the vein is shown with glowing invisible shulkers. Only the outer blocks of the vein are highlighted, and only blocks the player is allowed to break are shown.

vein-mining:
  # Show the outline of the vein while sneaking
  preview: true

• The preview uses the same checks as vein mining (permission, toggle, world, item data, tool), so it shows exactly what would be mined. It works whether or not require-sneak is enabled.
• It is computed when the player starts sneaking. To preview another vein, stop sneaking and sneak again while looking at it.
• Only the player who sneaks can see their preview.
• It disappears when the player stops sneaking, breaks a block, changes held item, swaps hands, teleports, changes world, dies or quits, and when a previewed block is destroyed or moved (another player, explosion, piston).
• Preview shulkers are never saved with the world. Shulkers left by a crash or by an older version are removed on startup and when their chunk loads.

Set preview: false to disable it.

DurabilityCopy Anchor Link

The tools section of config.yml controls how the tool is damaged:

tools:
  # Check tool durability before mining (prevents breaking more blocks than durability allows)
  check-durability: true
  # Apply durability damage to the tool
  apply-damage: true

Durability checks are skipped in Creative mode and for unbreakable items. Custom tools with a modified maximum durability or a higher damage per block are taken into account.

CooldownCopy Anchor Link

vein-mining:
  # Cooldown between vein mines in ticks (0 = disabled)
  cooldown: 0

• The cooldown is in ticks (20 ticks = 1 second). 0 disables it.
• It starts after a vein mine that broke at least one extra block.
• During the cooldown, the broken block is mined normally (without vein) and the cooldown message is shown in the action bar with the remaining seconds.
• Players with zveinminer.bypass.cooldown ignore the cooldown.

ExamplesCopy Anchor Link

All the examples below go in the presets list of config.yml. Give them with /zveinminer apply <name>, /zveinminer set <name> or /zveinminer give <player> <name> [material].

Pickaxe for oresCopy Anchor Link

presets:
  - name: "pickaxe-ores"
    size: 16
    tags:
      - COAL_ORES
      - COPPER_ORES
      - IRON_ORES
      - GOLD_ORES
      - REDSTONE_ORES
      - LAPIS_ORES
      - DIAMOND_ORES
      - EMERALD_ORES
      - NETHER_QUARTZ_ORE
      - ANCIENT_DEBRIS

With match-by-tag: true, stone and deepslate variants of each ore are mined together. The tool must still be able to harvest each ore: an iron pickaxe is needed for diamond ores.

/zveinminer give Maxlego08 pickaxe-ores DIAMOND_PICKAXE

Axe for treesCopy Anchor Link

presets:
  - name: "axe-trees"
    size: 32
    tags:
      - LOGS

LOGS contains every log, wood, stem and hyphae. With match-by-tag: true, logs of different species that touch each other are mined together.

To fell one species at a time, list materials instead:

presets:
  - name: "axe-oak"
    size: 32
    tags:
      - OAK_LOG
      - DARK_OAK_LOG

/zveinminer give Maxlego08 axe-trees DIAMOND_AXE

Shovel for gravel and clayCopy Anchor Link

presets:
  - name: "shovel-1"
    size: 12
    tags:
      - GRAVEL
      - CLAY

Upgrading a single itemCopy Anchor Link

Start from a preset, then tune one item in hand:

/zveinminer apply pickaxe-1
/zveinminer add NETHER_QUARTZ_ORE
/zveinminer size 24
/zveinminer info

After these commands the item keeps its own tag list (the pickaxe-1 tags plus NETHER_QUARTZ_ORE) and its own size of 24. size 24 is refused if max-size-limit is enabled and lower than 24.