🧱 Block

Overview

A custom block is a single entry under blocks: in your configuration. Each entry is keyed by its id — namespace:path, e.g. default:palm_log — and is assembled from a handful of independent sections. You configure only the ones you need.

Only one section is mandatory: state / states — it tells the plugin what the block looks like. Everything else is optional layering you add when the block needs it.

Anatomy

Every block follows the same skeleton. Each top-level key answers one question about the block:

blocks:
  default:my_block:     # the block id — referenced everywhere as default:my_block
    state:              # REQUIRED  → what it looks like   (model, texture, orientation)
      ...
    settings:           # optional  → how it physically behaves (hardness, sounds, light, tools, tags)
      ...
    behavior:           # optional  → its unique mechanics (grow, fall, open, spread, …)
      ...
    loot:               # optional  → what it drops when broken
      ...
    events:             # optional  → reactions to player interaction (click, break, …)
      ...

Sections to Configure

🔣 Block StatesModel, texture, orientation & variants — what the block looks like

🔧 Block SettingsHardness, sounds, light, burn, mining tools, tags — physical properties

🕹️ Block BehaviorsMechanics — grow, fall, open, doors, crops, fences, seats, …

🎲 Loot TableWhat the block drops when broken

🪇 EventsReact to clicks & breaks with functions, gated by conditions

Quick Start

1. The smallest possible block

One state, one texture, nothing else — already a fully working block:

blocks:
  default:my_block:
    state:
      auto_state: note_block                       # let the plugin auto-pick a carrier state
      model:
        texture: "minecraft:block/custom/my_block" # single texture → cube_all model

2. Tune its physics

Add a settings section so it behaves like stone — sound, hardness, the right tool:

blocks:
  default:my_block:
    state:
      auto_state: note_block
      model:
        texture: "minecraft:block/custom/my_block"
    settings:
      hardness: 1.5
      resistance: 6.0
      sounds:
        break: minecraft:block.stone.break
        step: minecraft:block.stone.step
        place: minecraft:block.stone.place
        hit: minecraft:block.stone.hit
        fall: minecraft:block.stone.fall
      tags:
        - minecraft:mineable/pickaxe

3. Add mechanics

Drop in a behavior to give it real function. Here it becomes a log you can strip with an axe:

blocks:
  default:my_block:
    state:
      auto_state: note_block
      model:
        texture: "minecraft:block/custom/my_block"
    settings:
      hardness: 1.5
      tags:
        - minecraft:mineable/axe
        - minecraft:logs
    behavior:
      type: strippable_block
      stripped: default:stripped_my_block

Keep layering the same way — loot for drops, events for interaction, an entity_renderer inside a state for custom rendering. Each section is independent.

Binding an Item to a Block

A block and the item players hold to place it are two separate things — you connect them from either side:

From the block side: settings.item

Tells the plugin which item this block corresponds to. Mainly used so the right item is picked in creative middle-click and for block→item lookups. Optional.

blocks:
  default:my_block:
    state: ...
    settings:
      item: default:my_block    # the item id this block maps to

From the item side: the block_item behavior

This is what actually makes the block placeable by right-clicking. Attach a block_item behavior to the item, and point its block field at the block id:

items:
  default:my_block:
    behavior:
      type: block_item
      block: default:my_block   # the block this item places

blocks:
  default:my_block:
    state: ...
    settings: ...

block can also hold the entire block config inline instead of an id, when you'd rather keep them in one place:

items:
  default:my_block:
    behavior:
      type: block_item
      block:
        state: ...
        settings: ...
        loot: ...

tip

Placement variants

Plain block_item places the block where you aim. For special placement rules, CraftEngine offers variants that all take the same block field: Ceiling Block Item, Wall Block Item, Ground Block Item, Double High Block Item, Multi High Block Item, and Liquid Collision Block Item.

Where to Look When You're Stuck

Match what you're trying to do to the right page:

You want to…	Go to
Give it a model, texture, or orientation	Block States
Change hardness, sounds, light, burn, mining tools, friction	Block Settings
Make it grow, fall, open, spread, or act like a door / crop / fence / seat	Block Behaviors
Find which property types a behavior expects	Properties
Control what it drops	Loot Table
Make it drop experience	Drop Experience Block
React to clicks or breaks	Events · Conditions
Store per-block data or render items / text / 3D models	Block Entity Renderer
Make the block placeable by hand (bind it to an item)	Binding an Item · Block Item
Add it to a vanilla tag group (mineable, logs, beacon base…)	Block Tags