Custom Blocks

Custom blocks

Carrier-backed custom block definitions, drops, hardness, placement and version-specific behavior.

Documentation for VoxelCore v1.0.0. Home · Installation · Compatibility

Custom blocks

VoxelCore supports real, full-cube custom blocks intended for ores, building blocks, logs, and similar content. It does not use display entities or furniture-style placement; furniture belongs in an addon such as VoxelFurniture.

The smallest definition needs one texture:

blocks:
  ruby_ore:
    display_name: "&cRuby Ore"
    texture: mypack:block/ruby_ore
    break_tools:
      - PICKAXE
    minimum_tool_tier: IRON
    drop: ruby_ore

model: cube_column supports a log-style side/top/bottom layout, while model: cube supports six independent faces:

blocks:
  ruby_log:
    model: cube_column
    textures:
      side: mypack:block/ruby_log
      top: mypack:block/ruby_log_top
      bottom: mypack:block/ruby_log_bottom

  directional_ore:
    model: cube
    textures:
      north: mypack:block/ore_north
      south: mypack:block/ore_south
      east: mypack:block/ore_east
      west: mypack:block/ore_west
      up: mypack:block/ore_top
      down: mypack:block/ore_bottom

Supported block fields are extends, abstract, display_name, method, model, texture, textures, hardness, blast_resistance, break_tools, minimum_tool_tier, stackable, explosion_immune, drop_when_mined, drop, silk_touch, and events. Block definitions support the same bounded, cycle-aware inheritance rules as items.

break_tools is an optional harvesting whitelist, not a destruction whitelist. Category entries PICKAXE, AXE, SHOVEL, HOE, SWORD, SHEARS, and HAND match the corresponding family, while a material such as DIAMOND_PICKAXE matches only that exact vanilla item. Namespaced VoxelCore item IDs such as voxel:ruby_drill are also supported. minimum_tool_tier can be WOOD, GOLD, STONE, IRON, DIAMOND, or NETHERITE; combine PICKAXE with IRON for vanilla gold/diamond-ore harvesting. A wrong tool or an empty hand still breaks the block but produces no configured drop. Omitting both fields lets any held item harvest the block, while Creative breaking never produces a drop.

Generated block items are stackable by default and use a clean stackable carrier on modern versions. Set stackable: false to opt into a non-stackable carrier. Minecraft 1.12–1.13 automatically use a hidden damageable carrier because those clients require durability predicates for custom inventory models. display_name and inherited item lore accept legacy & formatting codes on every supported server version.

Carrier methods in VoxelCore 1.0.0:

Method	Modern servers	1.12 legacy servers	Status
auto	selects conservatively reserved mushroom states	selects mushroom	supported
solid	existing note-block allocations retained; new allocations refused (every note/pitch is vanilla-reachable)	legacy mushroom states	legacy/existing only
mushroom	reserved opposing-face mushroom masks, excluding vanilla inventory placement and normal generated cap/stem patterns	legacy mushroom states	supported
transparent, wire, fire	—	—	recognized but rejected until a safe runtime implementation is available

Allocations are persisted in plugins/VoxelCore/block-allocations.yml. Removed IDs become tombstones instead of silently reusing a state, so existing worlds remain stable. Do not delete this file on a live server. New modern allocations prefer 24 conservatively reserved mushroom face states (8 per carrier); they never silently fall back to note blocks and fail with an explicit capacity error. Existing note-block allocations are preserved to avoid corrupting placed blocks. Commands/debug sticks can create any legal vanilla state: no carrier-based custom-block system can promise absolute non-collision under arbitrary commands, so the reservation policy only excludes normal vanilla generation/placement; do not repurpose an existing world's persisted carrier manifest without a world migration. Interaction, physics, and note playback are suppressed for allocated carrier states, and explosion_immune: true removes the block from explosion damage lists.

On Minecraft 1.20.5 and newer, hardness controls survival mining time through the native player block-break-speed attribute. VoxelCore applies the ratio between the carrier's vanilla hardness and the configured hardness without replacing the player's base value or other active modifiers. Effects and modifiers therefore continue to compose with the custom hardness, while vanilla carrier-specific tool effectiveness remains the underlying behavior. hardness: 0 is instant-break. Minecraft 1.12–1.20.4 retain carrier-native mining time. blast_resistance remains compiled metadata; non-immune blast-strength simulation is not yet implemented.

The Java resource-pack compiler generates the block model, inventory model, and complete carrier blockstate tables. The Bedrock compiler additionally generates Geyser state-specific overrides (voxelcore-blocks.json) and terrain atlas entries for supported cube-based definitions, using the existing Java block allocations. It publishes these with voxelcore.mcpack and voxelcore-items.json; a Geyser restart and Bedrock reconnect are required before the new registration can appear. Real-client validation remains required. Authors only supply the referenced texture PNGs. Every concrete block automatically receives a matching placeable inventory item, and its default drop is that item. An explicit items: definition with the same content ID overrides the generated item when a special 2D icon or custom item behavior is required.

On Paper versions with PlayerPickBlockEvent, Creative middle-click on a placed custom block selects its matching VoxelCore item from the inventory, or creates one in the selected hotbar slot if absent. Older server APIs continue to load without this optional pick-block behavior.