Blocks 1.16+

experimental

Better documentation on the new block format introduced in the Minecraft Beta 1.16.100.

WARNING

This document covers experimental features, for 1.16 format version blocks. If you would like to learn about stable blocks, you can do so here.

Block Properties

Defining Properties:

Copy
{
	"format_version": "1.16.100",
	"minecraft:block": {
		"description": {
			"identifier": "wiki:my_block",
			"properties": {
				"wiki:string_property_example": [
					"red",
					"green",
					"blue",
					"purple"
				],
				"wiki:boolean_property_example": [true, false],
				"wiki:integer_property_example": [1, 2, 3, 4, 5]
			}
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Using Properties:

Properties can be queried with query.block_property, like this:

query.block_property('wiki:string_property_example') == 'blue'

Block Events

Copy
{
	"format_version": "1.16.100",
	"minecraft:block": {
		"description": {
			"identifier": "wiki:my_block"
		},
		"components": {
			"minecraft:on_step_on": {
				"event": "wiki:drop_loot",
				"target": "self"
			}
		},
		"events": {
			"wiki:drop_loot": {
				"spawn_loot": {
					"table": "loot_tables/blocks/my_loot_table.json"
				}
			}
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

This example spawns a loot table when an entity stands on the block.

Event Functions

add_mob_effect

Adds a mob effect when triggered

Copy
{
	"wiki:effect_event": {
		"add_mob_effect": {
			"effect": "poison",
			"target": "other",
			"duration": 8,
			"amplifier": 3
		}
	}
}
1
2
3
4
5
6
7
8
9
10

remove_mob_effect

Removes a mob effect when triggered

Copy
{
	"wiki:remove_effect_event": {
		"remove_mob_effect": {
			"effect": "poison",
			"target": "other"
		}
	}
}
1
2
3
4
5
6
7
8

spawn_loot

Summons a loot table when the event is triggered.

Copy
{
	"wiki:drop_loot": {
		"spawn_loot": {
			"table": "loot_tables/blocks/my_loot_table.json"
		}
	}
}
1
2
3
4
5
6
7

set_block

Removes the current block and replaces it with the defined block in the same position.

Copy
{
	"wiki:place_block": {
		"set_block": "minecraft:grass"
	}
}
1
2
3
4
5

set_block_property

Used to set the value of a block's property

Copy
{
	"wiki:change_color": {
		"set_block_property": {
			"wiki:string_property_example": "red"
		}
	}
}
1
2
3
4
5
6
7

set_block_at_pos

Used to set a block relative to the position of this block

Copy
{
	"wiki:trigger_event": {
		"set_block_at_pos": {
			"block_type": "minecraft:stone",
			"block_offset": [0, 0, 0]
		}
	}
}
1
2
3
4
5
6
7
8

run_command

Used to execute a command

Copy
{
	"wiki:execute_event": {
		"run_command": {
			"command": ["summon pig"]
		}
	}
}
1
2
3
4
5
6
7

damage

Copy
{
	"wiki:damage_event": {
		"damage": {
			"type": "magic",
			"target": "other",
			"amount": 4
		}
	}
}
1
2
3
4
5
6
7
8
9

decrement_stack

Decrements the stack

Copy
{
	"wiki:remove_one": {
		"decrement_stack": {}
	}
}
1
2
3
4
5

die

Kills the target or destroys the block

Copy
{
	"wiki:destroy": {
		"die": {
			"target": "self"
		}
	}
}
1
2
3
4
5
6
7

play_effect

Runs a particle effect on the target

Copy
{
	"wiki:particle_effect": {
		"play_effect": {
			"effect": "minecraft:campfire_smoke",
			"target": "self"
		}
	}
}
1
2
3
4
5
6
7
8

play_sound

Plays a sound on the target

Copy
{
	"wiki:play_sound": {
		"play_sound": {
			"sound": "mob.enderman.death",
			"target": "self"
		}
	}
}
1
2
3
4
5
6
7
8

trigger

Used to trigger an event, this can be a block event or an entity event.

Copy
{
	"wiki:trigger_event": {
		"trigger": {
			"event": "wiki:my_event",
			"target": "self" // If set to 'other' an entity event can be defined. It will be triggered on the entity that causes the block event.
		}
	}
}
1
2
3
4
5
6
7
8

sequence

Used to sequence event functions

Copy
{
	"wiki:sequence_event": {
		"sequence": [
			{
				"set_block_property": {
					"wiki:my_prop": true
				}
			},
			{
				"condition": "query.block_property('wiki:my_prop') == true",
				"trigger": {
					"event": "wiki:my_entity_event",
					"target": "other"
				}
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

randomize

Used to randomize event functions

Copy
{
	"wiki:randomize_events": {
		"randomize": [
			{
				"weight": 1,
				"set_block_property": {
					"wiki:boolean_property_example": false
				}
			},
			{
				"weight": 2,
				"set_block_property": {
					"wiki:boolean_property_example": true
				}
			},
			{
				"weight": 4,
				"set_block": "minecraft:stone"
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Triggering Events

Block components to trigger block events:

  • minecraft:on_interact

  • minecraft:on_step_on

  • minecraft:on_step_off

  • minecraft:on_fall_on

  • minecraft:on_placed

  • minecraft:on_player_placing

  • minecraft:on_player_destroyed

  • minecraft:ticking and minecraft:random_ticking can both be used to trigger events after a set amount of time or at random times, depending on which component you use

Block Components

List of all new block components, with usage examples.

minecraft:unit_cube

Copy
{
	"minecraft:unit_cube": {}
}
1
2
3

minecraft:crafting_table

Copy
{
	"minecraft:crafting_table": {
		"custom_description": "Example Crafting Table", // Name shown in GUI
		"grid_size": 3, // Currently only supports 3
		"crafting_tags": ["crafting_table", "custom_crafting_tag"]
	}
}
1
2
3
4
5
6
7

minecraft:material_instances

Copy
{
	"minecraft:material_instances": {
		// Can also be a specific material instance for a specific face mapped in the geometry
		// Wildcards follow render controller syntax
		// Options 'up', 'down', and 'sides' are builtin
		"*": {
			"texture": "texture_name", // References texture defined in terrain_textures.json
			"render_method": "blend", // Options 'blend', 'opaque', 'alpha_test',
			"face_dimming": true, // Defaults to true; refers to whether or not block is affected by lighting (Undocumented)
			"ambient_occlusion": true // Defaults to true; refers to whether or not faces have smooth lighting (Undocumented)
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13

minecraft:geometry

Copy
{
	"minecraft:geometry": "geometry.wiki" // Geometry identifier from geo file in 'RP/models/entity' folder
}
1
2
3

minecraft:on_step_on

Copy
{
	"minecraft:on_step_on": {
		"event": "block_event",
		"target": "self",
		"condition": "query.block_property('wiki:block_property') == true"
	}
}
1
2
3
4
5
6
7

minecraft:on_step_off

Copy
{
	"minecraft:on_step_off": {
		"event": "block_event",
		"target": "self",
		"condition": "query.block_property('wiki:block_property') == true"
	}
}
1
2
3
4
5
6
7

minecraft:on_fall_on

Copy
{
	"minecraft:on_fall_on": {
		"event": "block_event",
		"target": "self",
		"condition": "query.block_property('wiki:block_property') == true",
		"min_fall_distance": 5
	}
}
1
2
3
4
5
6
7
8

minecraft:on_placed

Copy
{
	"minecraft:on_placed": {
		"event": "block_event",
		"target": "self",
		"condition": "query.block_property('wiki:block_property') == true"
	}
}
1
2
3
4
5
6
7

minecraft:on_player_placing

Copy
{
	"minecraft:on_player_placing": {
		"event": "block_event",
		"target": "self",
		"condition": "query.block_property('wiki:block_property') == true"
	}
}
1
2
3
4
5
6
7

minecraft:on_player_destroyed

Copy
{
	"minecraft:on_player_destroyed": {
		"event": "block_event",
		"target": "self",
		"condition": "query.block_property('wiki:block_property') == true"
	}
}
1
2
3
4
5
6
7

minecraft:on_interact

Copy
{
	"minecraft:on_interact": {
		"event": "block_event",
		"target": "self",
		"condition": "query.block_property('wiki:block_property') == true"
	}
}
1
2
3
4
5
6
7

minecraft:ticking

Copy
{
	"minecraft:ticking": {
		"looping": true,
		"range": [4, 4],
		"on_tick": {
			"event": "block_event",
			"target": "self",
			"condition": "query.block_property('wiki:block_property') == true"
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11

minecraft:random_ticking

Copy
{
	"minecraft:random_ticking": {
		"on_tick": {
			"event": "block_event",
			"target": "self",
			"condition": "query.block_property('wiki:block_property') == true"
		}
	}
}
1
2
3
4
5
6
7
8
9

minecraft:entity_collision

Copy
{
	"minecraft:entity_collision": {
		"origin": [-8, 0, -8],
		"size": [16, 16, 16]
	}
}
1
2
3
4
5
6
Copy
{
	"minecraft:entity_collision": false
}
1
2
3

minecraft:pick_collision

Copy
{
	"minecraft:pick_collision": {
		"origin": [-8, 0, -8],
		"size": [16, 16, 16]
	}
}
1
2
3
4
5
6
Copy
{
	"minecraft:pick_collision": false
}
1
2
3

minecraft:breakonpush

Copy
{
	"minecraft:breakonpush": true
}
1
2
3

minecraft:display_name

Copy
{
	"minecraft:display_name": "Name"
}
1
2
3

minecraft:breathability

Copy
{
	"minecraft:breathability": "solid" // Also accepts 'air'
}
1
2
3

minecraft:immovable

Copy
{
	"minecraft:immovable": true
}
1
2
3

minecraft:onlypistonpush

Copy
{
	"minecraft:onlypistonpush": true
}
1
2
3

minecraft:placement_filter

Copy
{
	"minecraft:placement_filter": {
		"conditions": [
			{
				"block_filter": ["minecraft:dirt"],
				"allowed_faces": ["up"]
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10

This also accepts tags, such as:

Copy
{
	"minecraft:placement_filter": {
		"conditions": [
			{
				"allowed_faces": ["up"],
				"block_filter": [
					{
						"tags": "!query.any_tag('air')"
					}
				]
			}
		]
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

minecraft:preventsjumping

Copy
{
	"minecraft:preventsjumping": true
}
1
2
3

minecraft:rotation

Copy
{
	"minecraft:rotation": [90, 180, 0]
}
1
2
3

minecraft:unwalkable

Copy
{
	"minecraft:unwalkable": true
}
1
2
3

Block Tags

Block tags can be given to blocks to be queried or referenced with any_tag or all_tags, which is used inside item and entity files. A tag can be applied like this:

Copy
{
	"format_version": "1.16.100",
	"minecraft:block": {
		"description": {
			"identifier": "wiki:my_block"
		},
		"components": {
			"tag:wiki:my_tag": {},
			"tag:my_other_tag": {}
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11
12

and this tag can be queried with:

  • query.all_tags
  • query.any_tag
  • query.block_has_all_tags
  • query.block_has_any_tag
  • query.relative_block_has_all_tags
  • query.relative_block_has_any_tag

Example of querying a tag:

Copy
{
	"format_version": "1.16.100",
	"minecraft:item": {
		"description": {
			"category": "equipment",
			"identifier": "wiki:pickaxe"
		},
		"components": {
			"minecraft:digger": {
				"use_efficiency": true,
				"destroy_speeds": [
					{
						"block": {
							"tags": "query.any_tag('wiki:my_tag', 'stone', 'metal')"
						},
						"speed": 6
					}
				]
			}
		}
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Block Permutations

Block permutations are a way of conditionally applying components to a block with MoLang expressions.

wiki:

Copy
{
    "format_version": "1.16.100",
    "minecraft:block": {
        "description": {
            "identifier": "wiki:my_block",
            "properties": {
                "wiki:custom_integer_property": [ 10, 20, 30, 40 ],
                "wiki:custom_boolean_property": [ false, true ],
                "wiki:custom_string_property": [ "red", "green", "blue" ]
            }
        },
        "components": {...},
        "permutations": [
            {
                "condition": "query.block_property('wiki:custom_integer_property') == 20",
                "components": {
                    "minecraft:friction": 0.1
                }
            },
            {
                "condition": "query.block_property('wiki:custom_boolean_property') == true",
                "components": {
                "minecraft:destroy_time": 0.5
                }
            },
            {
                "condition": "query.block_property('wiki:custom_string_property') == 'red'",
                "components": {
                    "minecraft:geometry": "geometry.pig"
                }
            }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

Additional Notes

  • Vanilla Blocks are hardcoded. You may not override or access them.
  • Following components may only have one at any given time:
    • "minecraft:ticking"
    • "minecraft:random_ticking"
  • It is not recommended to use minecraft:display_name. Example:
Copy
{
	"minecraft:display_name": "Barrel of Foxes"
}
1
2
3

In-game, yields the result: tile.Barrel of Foxes.name. Using .lang files is recommended.

  • Maximum of 16 values per property.
  • Following components cannot be larger than 16x16x16:
    • minecraft:entity_collision
    • minecraft:pick_collision
  • Execute commands cannot be run on blocks.
  • Custom Blocks will not be mined any faster/slower with vanilla tools.
  • Block faces will become dark if buried in another block.
  • Blocks will always be dropped with Silk Touch enchantment.
  • Block Identifiers cannot match Vanilla blocks, even ignoring namespace.
  • Following components requires entity_collision to be 4 or higher on the y-axis:
    • on_step_on
    • on_step_off
    • on_fall_on

Contributors

SmokeyStackSirLichaexer0eMedicalJewel105