Skip to content

blocks.md

Latest commit

 

History

History
676 lines (585 loc) · 18.8 KB

blocks.md

File metadata and controls

676 lines (585 loc) · 18.8 KB
layout default
title Blocks Regeneration
nav_order 6

Blocks

Block regen creates fake, player-specific resource nodes. The real world block does not need to change. ClientCore sends block packets to eligible players, handles the break packet, gives rewards, then sends a cooldown block and later the ready block again.

Vanilla mining rules are different: they apply to real vanilla blocks already placed in the world. ClientCore cancels the normal break, runs a server-side mining timer, sends PacketEvents crack animation packets, and breaks the real block when the timer completes.

Folder:

plugins/ClientCore/blocks/

Minimal Example

plugins/ClientCore/blocks/coal.yml

level-2-coal:
  enabled: true
  location:
    world: world
    x: 233.423
    y: -34
    z: 257.638
  ready-block: COAL_ORE
  cooldown-block: BEDROCK
  condition: ""
  conditions:
    - "%mmocore_level%;>=;2"
    - "%mmocore_level%;<=;5"
  regen-ticks: 80
  drops:
    - type: vanilla
      material: COAL
      amount: 1

Coordinates can be decimal. Minecraft block packets target the block position containing that coordinate.

Full Root Example

block-regen:
  enabled: true
  refresh-radius: 16
  refresh-period-ticks: 40
  join-delay-ticks: 5
  default-worldguard-flag: clientcore-regen
  rules:
    tutorial-stone:
      enabled: true
      location:
        world: world
        x: 10
        y: 65
        z: 10
      ready-block: STONE
      cooldown-block: BEDROCK
      regen-ticks: 100
      drops:
        - type: vanilla
          material: COBBLESTONE
          amount: 1

Global Settings

These are read from the merged block-regen root:

block-regen:
  enabled: true
  refresh-radius: 10
  refresh-period-ticks: 40
  join-delay-ticks: 5
  default-worldguard-flag: clientcore-regen
  enchant-effects:
    efficiency:
      enabled: true
      reduction-percent-formula: "level * random(1, level)"
      min-time-ticks: 1
    fortune:
      enabled: true
      bonus-amount-formula: "random(0, level)"
    custom:
      - type: sinceenchantments
        id: excavator
        mode: time-reduction
        formula: "level * 3"
        min-time-ticks: 1
      - type: sinceenchantments
        id: fortune_plus
        mode: drop-bonus
        formula: "random(0, level)"

If you use direct rule style only, these settings fall back to defaults.

block-regen.enchant-effects applies to client-side block regen mining. If it is omitted, ClientCore falls back to vanilla-mining.enchant-effects, then top-level enchant-effects. custom is a list; ClientCore reads each entry without adding synthetic keys back into the live Bukkit config tree.

Vanilla Mining

Use vanilla-mining when you want custom mining speed and rewards for real vanilla blocks such as STONE, DIAMOND_ORE, or DEEPSLATE. It does not change the client's built-in mining speed table; it replaces the break flow with server-authoritative timing.

vanilla-mining:
  enabled: true
  # Leave blank to allow configured vanilla mining anywhere.
  # Set a WorldGuard flag name if the rule should only work in allowed regions.
  default-worldguard-flag: ""
  enchant-effects:
    efficiency:
      enabled: true
      reduction-percent-formula: "level * random(1, level)"
      min-time-ticks: 1
    fortune:
      enabled: true
      bonus-amount-formula: "random(0, level)"
  blocks:
    STONE:
      enabled: true
      condition: ""
      conditions: []
      mining:
        default-time-ticks: 60
        tools:
          - item:
              type: vanilla
              material: WOODEN_PICKAXE
            enchants:
              efficiency: 1
            time-ticks: 80
            drops:
              - type: vanilla
                material: COBBLESTONE
                amount: 1
          - item:
              type: mmoitems
              mmo-type: TOOL
              mmo-id: STARTER_PICKAXE
            time-ticks: 40
            mmocore-exp:
              mining: 4
            drops:
              - type: mmoitems
                mmo-type: MATERIAL
                mmo-id: STARTER_STONE
                material: COBBLESTONE

Vanilla mining supports the same mining.feedback, tools, vanilla item matching, MMOItems tool matching, conditions, MMOItems rewards, and optional MMOCore profession EXP as client-side block regen mining.

Enchant behavior is applied at runtime after a tool rule chooses the base time-ticks and drops:

  • efficiency reduces the base mining time using reduction-percent-formula.
  • fortune adds to each configured drop stack using bonus-amount-formula; Silk Touch disables this configured drop bonus.

Formula variables include level, plus base/time for Efficiency and base/amount for Fortune. Supported functions are random(min,max), min(a,b), max(a,b), floor(x), ceil(x), and round(x).

Tool rules can still require enchantments as a gate. Vanilla enchantments use Bukkit/Paper enchant keys; un-namespaced keys default to minecraft:. When SinceEnchantments is active, ClientCore also checks SinceEnchantments' combined enchant map for the same requirement, so vanilla and custom enchant levels can both satisfy configured enchant gates.

tools:
  # 1) Vanilla shorthand on a vanilla tool.
  - item:
      type: vanilla
      material: DIAMOND_PICKAXE
    enchants:
      efficiency: 3
      silk_touch: 1
    time-ticks: 70

  # 2) Vanilla object form on an MMOItems tool.
  - item:
      type: mmoitems
      mmo-type: TOOL
      mmo-id: STARTER_PICKAXE
    enchants:
      fortune:
        type: vanilla
        min-level: 2
    time-ticks: 40

SinceEnchantments custom IDs can use custom-enchants on the same tool rule. These checks work with vanilla, MMOItems, and any tool rules when hooks.sinceenchantments is enabled and the SinceEnchantments plugin is installed. You can also put a SinceEnchantments ID under enchants with type: sinceenchantments if you prefer one list.

tools:
  # 3) SinceEnchantments dedicated list on an MMOItems tool.
  - item:
      type: mmoitems
      mmo-type: TOOL
      mmo-id: STARTER_PICKAXE
    custom-enchants:
      - type: sinceenchantments
        id: excavator
        min-level: 1
    time-ticks: 40

  # 4) SinceEnchantments object form inside enchants.
  - item:
      type: vanilla
      material: NETHERITE_PICKAXE
    enchants:
      excavator:
        type: sinceenchantments
        min-level: 1
    time-ticks: 45

  # 5) Any item, but still require both vanilla and custom enchant gates.
  - item:
      type: any
    enchants:
      efficiency: 2
      excavator:
        type: sinceenchantments
        min-level: 1
    time-ticks: 55

Tool-specific drops are preferred:

  • If the matching tool has drops, those drops are given.
  • If the matching tool has no drops, ClientCore uses the block-level drops.
  • If neither the tool nor the block has drops, ClientCore breaks the block naturally with the player's held item.

This lets each tool have a different reward table without defining a shared block drop:

vanilla-mining:
  enabled: true
  blocks:
    DIAMOND_ORE:
      mining:
        default-time-ticks: 120
        tools:
          - item:
              type: vanilla
              material: IRON_PICKAXE
            time-ticks: 140
            drops:
              - type: vanilla
                material: DIAMOND
                amount: 1
          - item:
              type: vanilla
              material: DIAMOND_PICKAXE
            time-ticks: 90
            drops:
              - type: vanilla
                material: DIAMOND
                amount: 2

Vanilla mining is intentionally disabled by default because it affects every matching real block in the world.

Rule Fields

enabled: true/false
location.world: Bukkit world name
location.x/y/z: block location
ready-block: material sent when the node is available
cooldown-block: material sent after mining
condition: optional one-line semicolon condition
conditions: optional list of semicolon conditions
worldguard-flag: overrides the default flag for this rule
regen-ticks: cooldown duration
mining: optional custom break time, tool requirements, and tool-specific drops
farming: optional right-click harvest support, tool requirements, and tool-specific drops
drops: rewards given directly to the player
variants: optional weighted variants

Use ORIGINAL for ready-block or cooldown-block when you want to send the real server block state.

MMOItems Reward

drops:
  - type: mmoitems
    mmo-type: MATERIAL
    mmo-id: RARE_STONE
    material: STONE
    amount: 2

If MMOItems cannot return the item, ClientCore falls back to the vanilla material. MMOItems drops support amount the same way vanilla drops do, including Fortune/custom drop-bonus scaling during mining.

MMOCore Profession EXP

Add mmocore-exp or profession-exp to a block rule, variant, vanilla-mining block, farming stage, or tool rule to give MMOCore profession experience when the action succeeds. This is optional: if MMOCore is not installed, or hooks.mmocore is false, ClientCore ignores these rewards safely.

Tool-level profession EXP overrides the rule, variant, vanilla block, or farming stage EXP for the matching tool.

mmocore-exp:
  mining: 4
  farming: 2
  fishing: 1

List style is also supported:

profession-exp:
  - profession: mining
    amount: 4
  - profession: farming
    amount: 2

Custom Mining

Add mining to a rule or variant when ClientCore should control the break time instead of using the vanilla client material timing. If tools is set, only matching tools can mine the node.

mining:
  active-block: BARRIER
  visual-mode: block-display
  feedback:
    display: true
    glowing: true
    glowing-color-argb: "80FFFFFF"
    actionbar: false
    particles: true
    sounds: true
    interval-ticks: 4
    message: "<gray>Mining <white>{progress}%</white>"
    display-format: "<bold>{bar}</bold> <white>{progress}%</white>"
    bar-length: 12
    low-color: "<gold>"
    mid-color: "<yellow>"
    high-color: "<green>"
    empty-color: "<dark_gray>"
    background-argb: "8C0C1016"
  default-time-ticks: 60
  tools:
    - item:
        type: vanilla
        material: IRON_PICKAXE
      enchants:
        efficiency: 2
      time-ticks: 80
      regen-ticks: 100
      mmocore-exp:
        mining: 3
      drops:
        - type: vanilla
          material: RAW_IRON
          amount: 1
    - item:
        type: mmoitems
        mmo-type: TOOL
        mmo-id: MINER_PICKAXE
      time-ticks: 30
      regen-ticks: 60
      drops:
        - type: mmoitems
          mmo-type: MATERIAL
          mmo-id: RICH_IRON
          material: RAW_IRON

Tool drops override the variant/rule drops. If a matching tool has no drops, ClientCore uses the normal variant/rule drops. Tool regen-ticks overrides the variant/rule cooldown for block-regen mining; omit it to use the normal variant/rule regen-ticks.

active-block is the hitbox block sent while the player is actively mining.

visual-mode controls what the player sees while the custom mining timer is active:

  • block-display is the default and preserves the old behavior. BARRIER is recommended because it is hard to break and normally invisible; ClientCore renders a player-only BlockDisplay with the ready block on top.
  • active-block uses the sent active-block itself as the visual block and does not spawn the ready-block BlockDisplay. Use this with a resource pack that remaps a hard block or block state to your stone/ore/custom-block texture. Because the client is mining a real block state, vanilla crack overlays render on that texture.

Aliases accepted for active-block mode: resource-pack, resource-pack-block, and vanilla-crack.

ClientCore can also resolve custom block IDs directly when the matching plugin is installed and its hook is enabled:

mining:
  active-block: oraxen:amethyst_ore
  visual-mode: active-block

Supported prefixes:

  • oraxen:<id>
  • itemsadder:<namespace:id>
  • nexo:<id>
  • craftengine:<namespace:id>

Concrete examples:

oraxen-active-block-ore:
  enabled: true
  location:
    world: world
    x: 30
    y: 65
    z: 30
  ready-block: oraxen:amethyst_ore
  cooldown-block: STONE
  regen-ticks: 300
  mining:
    active-block: oraxen:amethyst_ore
    visual-mode: active-block
    default-time-ticks: 80

itemsadder-active-block-ore:
  enabled: true
  location:
    world: world
    x: 31
    y: 65
    z: 30
  ready-block: itemsadder:customcrops:ruby_ore
  cooldown-block: STONE
  regen-ticks: 300
  mining:
    active-block: itemsadder:customcrops:ruby_ore
    visual-mode: active-block
    default-time-ticks: 80

nexo-active-block-ore:
  enabled: true
  location:
    world: world
    x: 32
    y: 65
    z: 30
  ready-block: nexo:topaz_ore
  cooldown-block: STONE
  regen-ticks: 300
  mining:
    active-block: nexo:topaz_ore
    visual-mode: active-block
    default-time-ticks: 80

craftengine-active-block-ore:
  enabled: true
  location:
    world: world
    x: 33
    y: 65
    z: 30
  ready-block: craftengine:default:tin_ore
  cooldown-block: STONE
  regen-ticks: 300
  mining:
    active-block: craftengine:default:tin_ore
    visual-mode: active-block
    default-time-ticks: 80

The resolver asks the custom block plugin for the block state it uses in-game, then sends that state as the active mining block. This works for normal block-state based custom blocks. Furniture/entity-based custom blocks cannot use vanilla crack overlays because the client is not mining a real block state.

Troubleshooting Active-Block Custom Blocks

If the custom block does not crack, first run /clientcore status. The Oraxen, ItemsAdder, Nexo, or CraftEngine hook for the configured prefix must show active. Also confirm the matching hook remains true in config.yml.

If the block resolves to air, check the console after /clientcore reload. ClientCore logs the rule, variant, custom ID, visual mode, provider, and hook states when active-block uses a supported custom ID that cannot resolve to a non-air block state.

Common causes:

  • The ID prefix is wrong, for example itemsadder:namespace:id or craftengine:namespace:id is required for namespaced IDs.
  • The custom block is furniture/entity-based instead of backed by a normal block state.
  • The custom block plugin loaded after ClientCore or the hook is disabled; reload ClientCore after the provider plugin is enabled.
  • The provider returns AIR for that ID. Use a block-state based custom block, or switch back to visual-mode: block-display with a hard active-block such as BARRIER.

feedback adds non-vanilla progress feedback for the BARRIER + BlockDisplay mode. display creates a player-only TextDisplay progress bar above the block, and particles/sounds provide extra local feedback while the server-side mining timer is running. glowing: true makes the block glow, and glowing-color-argb configures the glow color (Minecraft 1.20.2+).

Farming

Add farming to a rule or variant when the node should be harvested by right-click instead of being mined. Farming uses the same visibility, conditions, variants, cooldown, regen, WorldGuard flag, direct inventory rewards, MMOItems rewards, and tool matching behavior as mining. Optional stages let crops grow through visible block ages over time and provide stage-specific early harvest rewards.

wheat-farm:
  enabled: true
  location:
    world: world
    x: 20
    y: 65
    z: 20
  ready-block: WHEAT
  cooldown-block: FARMLAND
  regen-ticks: 200
  farming:
    enabled: true
    stages:
      - block: WHEAT[age=0]
        after-ticks: 1
        drops:
          - type: vanilla
            material: WHEAT_SEEDS
            amount: 1
      - block: WHEAT[age=3]
        after-ticks: 80
        drops:
          - type: vanilla
            material: WHEAT_SEEDS
            amount: 2
      - block: WHEAT[age=7]
        after-ticks: 120
        drops:
          - type: vanilla
            material: WHEAT
            amount: 2
    tools:
      - item:
          type: vanilla
          material: WOODEN_HOE
  drops:
    - type: vanilla
      material: WHEAT
      amount: 1

If tools is set, only matching tools can harvest the node. Tool drops override the variant/rule drops; if the matching tool has no drops, ClientCore uses the normal variant/rule drops.

If stages is set, stage drops are used before the normal variant/rule drops. Players can harvest at any stage: stage WHEAT[age=3] can give one reward, while the final mature stage WHEAT[age=7] can give wheat. after-ticks is the delay before that stage appears after the previous stage. The first stage is sent immediately after harvest. Stage-level mmocore-exp works the same way as stage drops.

Supported stage block formats:

block: WHEAT[age=3]

or:

material: WHEAT
age: 3

Common Farm Ages

Use the crop's max age as the final mature stage. These are common vanilla block data ages:

WHEAT: 0-7
CARROTS: 0-7
POTATOES: 0-7
BEETROOTS: 0-3
NETHER_WART: 0-3
COCOA: 0-2
SWEET_BERRY_BUSH: 0-3
CAVE_VINES: 0-25
CAVE_VINES_PLANT: 0-25
KELP: 0-25
KELP_PLANT: 0-25
CACTUS: 0-15
SUGAR_CANE: 0-15
BAMBOO: 0-1
TORCHFLOWER_CROP: 0-1
PITCHER_CROP: 0-4
CHORUS_FLOWER: 0-5

Examples:

# Wheat/carrot/potato, max age 7
stages:
  - block: WHEAT[age=0]
    after-ticks: 1
  - block: WHEAT[age=3]
    after-ticks: 80
  - block: WHEAT[age=7]
    after-ticks: 120

# Beetroot/nether wart, max age 3
stages:
  - block: BEETROOTS[age=0]
    after-ticks: 1
  - block: BEETROOTS[age=1]
    after-ticks: 80
  - block: BEETROOTS[age=3]
    after-ticks: 120

# Cocoa, max age 2. Cocoa also needs a facing direction.
stages:
  - block: COCOA[age=0,facing=north]
    after-ticks: 1
  - block: COCOA[age=1,facing=north]
    after-ticks: 80
  - block: COCOA[age=2,facing=north]
    after-ticks: 120

Variants

rich-coal:
  enabled: true
  location:
    world: world
    x: 30
    y: 60
    z: 30
  ready-block: COAL_ORE
  cooldown-block: BEDROCK
  regen-ticks: 100
  drops:
    - type: vanilla
      material: COAL
      amount: 1
  variants:
    - id: normal
      weight: 90
      ready-block: COAL_ORE
    - id: rare
      weight: 10
      rare: true
      luck-multiplier: 1.0
      ready-block: DIAMOND_ORE
      drops:
        - type: vanilla
          material: DIAMOND
          amount: 1

Debug Checklist

  • Run /clientcore status and check Block Regen: is above 0. For real vanilla block overrides, check Vanilla Mining: instead. For right-click harvest nodes, check Farming:.
  • Run /clientcore refresh near the configured location.
  • Temporarily set condition: "" and conditions: [].
  • Confirm the world name exactly matches /mv info or Bukkit world folder name.
  • Confirm PlaceholderAPI expansion returns a number for placeholders such as %mmocore_level%.
  • If WorldGuard is installed, allow the configured flag or leave the rule flag unset while testing.