Skip to content

Custom Blocks

natan307 edited this page Nov 16, 2026 · 1 revision

Custom Blocks

Any custom item can become a placeable 3D block by adding a block: section. The block uses the item's model, so no extra pack work is needed.

items:
  ruby_block:
    display_name: "&cRuby Block"
    material: PAPER
    model: "packloader:item/ruby_crystal"
    block:
      scale: 1.0
      rotation: 90
      transform: NONE
      glow: false
      sound: stone

Shortcut with defaults: block: true.

Keys

Key Default Description
scale 1.0 Size of the displayed model.
rotation 90 Snap the facing (toward the player) to multiples of this many degrees. 0 = never rotate.
transform NONE ItemDisplay transform: NONE, FIXED, HEAD, GROUND, GUI, ... Try FIXED or HEAD if the model looks too small or wrongly rotated.
glow false Render at full brightness.
sound stone Sound family: plays block.<sound>.place and block.<sound>.break.

Using blocks

  • Place: right-click a block with the item. Not possible in Adventure or Spectator mode. Right-clicking an interactable block (chest, door...) uses that block, unless you sneak.
  • Break: left-click. Breaking is instant. In Survival the item drops; in Creative it does not.
  • Placing and breaking call the normal BlockPlaceEvent / BlockBreakEvent, so protection plugins (WorldGuard, claims) can cancel them.
  • A block cannot be placed where a living entity stands.

How it works

Each block is two things: an invisible BARRIER block (collision and hitbox) and an ItemDisplay entity that shows the model. The entity is tagged with the item id.

Limitations

  • Mining speed cannot be changed (always instant).
  • The hitbox is always one full block, whatever the model shape.
  • Barrier blocks are not removed together with the model by tools that bypass events (/fill, /setblock, WorldEdit). Leftover display entities are cleaned up when their chunk loads again, but they can remain visible until then. Prefer breaking blocks normally.
  • Pistons, explosions and fluids treat the block as a barrier. Explosion drops/removal of the display are not handled specially.
  • Blocks are not redstone-aware and have no block-state variants.

If you need a richer block system, please open an issue to discuss it.

Clone this wiki locally