Block kinds

A block can be one of the game's kinds: stairs that join at corners, doors two blocks high, fences that connect, chests, signs, crops, ores. Give it a kind and it is made like the game's block of that kind, with its shape, states and behaviour, and your texture.

Kinds and materials

block "jade_bricks" { hardness: 2, tool: "pickaxe" }

block "jade_stairs" { kind: "stairs", base: "jade_bricks", texture: "mymod:block/jade_bricks" }
block "jade_slab" { kind: "slab", texture: "mymod:block/jade_bricks" }
block "jade_wall" { kind: "wall", texture: "mymod:block/jade_bricks" }

block "willow_log" { kind: "pillar", material: "wood", sound: "wood" }
block "willow_door" { kind: "door", material: "wood", sound: "wood" }
block "jade_door" { kind: "door", material: "metal" }
block "willow_fence" { kind: "fence", material: "wood", texture: "mymod:block/willow_planks" }

Kind	What it is
cube	a plain block (the default)
pillar	a log or pillar: it lies along the axis it is placed on
slab, stairs, wall, fence, fence_gate	building blocks that join their neighbours as the game's do. Stairs take the block they are made of in base
door, trapdoor, button, pressure_plate	doors are two blocks high; a pressure plate is on or off
leaves, lantern, vine, ladder, carpet, bars, chain	bars and panes are thin and join their neighbours; a chain lies along the axis it is placed on
plant, water_plant, crop	plants (below)
barrel, bookshelf, chiseled_bookshelf, shelf, composter, crafting_table, chest, furnace	blocks that work (below)
sign, hanging_sign	signs (below)
path, ore	paths and ores (below)

material is stone (the default), wood or metal, for the kinds where it matters: a wooden door or trapdoor opens by hand, a metal one only with redstone. Slabs, stairs, fences, buttons, plates and pillars are made like the game's of that material too.

What it takes from the game's block. Without files of its own, a block of a kind takes the game's blockstate and models with your texture (by default textures/block/<id>.png), its item, its drops and its tags: fences join fences, logs count as logs, a door drops one item. Where the game's block uses more than one texture, a texture of yours with the same ending is used when the mod has it: <id>_top.png and <id>_bottom.png for a door, <id>_top.png for a pillar, <id>_front.png and <id>_front_on.png for a furnace. If it has its own models, loot or tags, those are used. hardness, sound, light and the other properties of Blocks, items and recipes work as for any block.

Plants and crops

block "glow_grass" { kind: "plant", hardness: 0, grows_on: ["#minecraft:dirt", "mymod:glow_moss"] }

block "reed" { kind: "water_plant", hardness: 0 }

block "rice" { kind: "crop", hardness: 0 }

• plant: drawn as two crossed images, like grass, a flower, a mushroom or a sapling. Nothing collides with it and it needs ground.
• water_plant: a plant that lives under water, like seagrass.
• crop: it grows through ages 0 to 3 on its own and with bone meal. Its age state can be read with block.state("age"), and <id>_stage0.png to <id>_stage3.png are its textures at each age.

grows_on lists the blocks it stands on, ids or tags such as #minecraft:dirt. Without it, a plant grows where the game's plant of its kind does (a crop on farmland). A plant whose ground goes breaks.

Blocks that work

block "willow_barrel" { kind: "barrel", sound: "wood" }
block "willow_chest" { kind: "chest", sound: "wood" }
block "willow_bookshelf" { kind: "bookshelf", sound: "wood" }
block "jade_furnace" { kind: "furnace", hardness: 3.5, tool: "pickaxe" }

They keep their items, open their screen and work like the game's: a barrel holds 27 stacks, a chiseled bookshelf 6 books, a shelf 3 items, a composter fills up, a crafting table crafts, a furnace smelts and is lit while it burns.

A chest is drawn with textures/entity/chest/<id>.png, and two side by side make a double chest, drawn with <id>_left.png and <id>_right.png in that same folder. They have the layout of the game's chest textures.

Signs

block "willow_sign" { kind: "sign", sound: "wood" }

block "willow_hanging_sign" { kind: "hanging_sign", sound: "wood" }

Players write on them as on the game's. Declaring a sign also declares its wall form, the block its item places against a wall: jade_sign comes with jade_wall_sign, and jade_hanging_sign with jade_wall_hanging_sign. wall gives that id yourself. The wall form drops the sign. A hanging sign hangs under a block, and its wall form from the side of one.

Paths and ores

block "moss_path" { kind: "path", base: "minecraft:moss_block" }

block "jade_ore" { kind: "ore", hardness: 3, tool: "pickaxe", tier: "iron", xp: [1, 4] }

A path is a little lower than a block, like the game's dirt path. A shovel makes it from its base when there is air above. It turns back into its base when a block covers it, and it drops its base.

An ore gives off experience when it is broken without silk touch: xp is a number or [min, max]. To make it drop itself with silk touch and more with fortune, see Drops in Blocks, items and recipes.

Attached blocks

With attached: true, a block is fixed to the block it is placed against, and it breaks when that block goes. These properties work on any block, with or without a kind.

block "crystal_shard" {
    attached: true
    states: ["facing_all"]
    model: "block/crystal_shard"
}

block "glow_bulb" {
    attached: true
    floor_state: "standing"
    states: ["standing"]
    light: 12
}

• With a "facing" or "facing_all" state, it faces away from what holds it: facing_all also faces up and down, so a shard can sit on a floor, a wall or a ceiling (see Block states in Blocks, items and recipes).
• floor_state names a toggle state that is on when the block stands on a floor and off when it hangs from a ceiling, like a lantern. Declare the toggle in states too.

Seats and blocks two high

block "stool" { seat: 9, shape: [[3, 0, 3, 13, 9, 13]] }

block "throne" {
    model: "block/throne"
    seat: 10
    upper: "top"
    states: ["facing", "top"]
}

seat lets players sit on the block with a click of an empty hand, that many pixels above its bottom (0 to 16; a chair is about 10). If the block has an on_use that takes the click, the player doesn't sit.

upper makes the block two blocks high, like a door or a tall chair: it names a toggle state that is on in its upper half. Placing it places both halves when there is room above, breaking one breaks both, and only the lower half drops it. A two-high seat is sat on at its lower half. Declare the toggle in states too. The upper half has a look of its own like any state: here models/block/throne_top.json.

Plants in a column

block "glow_vine" {
    plant: true
    column: "hanging"
    states: [{ shape: ["top", "middle", "bottom"] }]
}

column makes a plant grow in a column, like a hanging vine. Its shape state follows the same plant above and below it: bottom with none below, top with none above, middle in between. Declare it in states as { shape: ["top", "middle", "bottom"] }; the textures <id>_middle.png and <id>_bottom.png are its looks there.

• hanging: it hangs from the block above, which is the same plant, leaves or a block solid underneath.
• standing: it stands on its ground (grows_on) or on the same plant.

Without what holds it up, it breaks, and the plants that hang or stand on it go with it.

Properties

Property	Values	Default
kind	one of the kinds above	cube
material	stone, wood, metal	stone
base	for stairs and paths: the block they are made of, yours or the game's	—
grows_on	for plants: block ids and tags	its kind's ground
wall	for signs: the id of the wall form	jade_sign → jade_wall_sign
xp	for ores: a number or [min, max]	—
attached	fixed to the block it is placed against	false
floor_state	with attached: the toggle that is on when it stands on a floor	—
seat	pixels above its bottom where players sit (0–16)	not a seat
upper	two blocks high: the toggle that is on in its upper half	—
column	hanging or standing	—

In Kotlin

block("jade_stairs") { kind = BlockKind.STAIRS; base = "jade_bricks"; texture = "mymod:block/jade_bricks" }
block("willow_door") { kind = BlockKind.DOOR; material = BlockMaterial.WOOD; sound = SoundGroup.WOOD }
block("glow_grass") { kind = BlockKind.PLANT; growsOn = listOf("#minecraft:dirt") }
block("jade_ore") { kind = BlockKind.ORE; xp = 1..4 }

block("crystal_shard") { attached = true; facingAll() }

block("throne") {
    seat = 10
    upper = "top"
    facing()
    toggle("top")
}

block("glow_vine") {
    plant = true
    column = Column.HANGING
    choice("shape", "top", "middle", "bottom")
}

The kinds are in BlockKind and the materials in BlockMaterial. The other properties have the same names in camelCase: growsOn, floorState, xp = 1..4, column = Column.HANGING. facingAll() and choice(name, …) declare the states.