Block definition

This feature is exclusive to Bedrock Edition.

 

A block definition is a JSON file used to define a custom block and its behavior. Block definition files are located in the  blocks folder of a behavior pack.

Structure

Block definitions are structured as follows:

States

The [NBT Compound / JSON Object] states object is used to define custom block states. Only custom states are allowed, using a vanilla state or the "minecraft" namespace will cause an error and fail. The object consists of state names as properties, and an array of possible values for each state. Integer states can also be defined as a range using an object. Block state values can be queried in permutations using the molang query "query.block_state('<state_name>')".

Examples:

"states": {
  "example:string_state": ["a", "b", "c"],
  "example:int_state": [1,2,3],
  "example:bool_state": [true,false],
  "example:int_state_2": {
    "min": 0,
    "max": 10
  }
}

Traits

The [NBT Compound / JSON Object] traits object is used to add vanilla block traits, which allow for custom blocks to have access to some vanilla block states. This object only gives access to the states, other functionality usually has to be added using permutations. The object consists of traits and their enabled states:

minecraft:connection

This section describes an experimental feature in Bedrock Edition.

 

This feature is not enabled in-game by default and requires enabling the "Upcoming Creator Features" setting in the "Experiments" section in Bedrock Edition‌^{[until BE 26.0]}.

This trait is not compatible with Multiplayer; using it will make it impossible for players to enter your world see MCPE-235104.

Gives blocks the boolean states minecraft:connection_north, minecraft:connection_south, minecraft:connection_east, and minecraft:connection_west, allowing for the block to connect to blocks next to it.

Example:

"traits": {
  "minecraft:connection": {
    "enabled_states": ["minecraft:cardinal_connections"]
  }
}

minecraft:placement_position

Gives blocks states related to where the player places the block. Two states are available:

• minecraft:vertical_half: The half of the block space that the block was placed in, allowing for stair and slab functionality. Possible values are top, and bottom.
• minecraft:block_face: The block face that the player placed the block on, allowing for log and pillar functionality. Possible values are up, down, east, north, west, and south.

Example:

"traits": {
  "minecraft:placement_position": {
    "enabled_states": ["minecraft:vertical_half"]
  }
}

minecraft:placement_direction

Gives blocks states related to the direction in which the player places the block. Three states are available:

• minecraft:cardinal_direction: The direction the player was facing when the block was placed. Possible values are north, south, east, and west.
• minecraft:facing_direction: Same as minecraft:cardinal_direction, but allows up and down as well. Possible values are up, down, east, north, west, and south.
• minecraft:corner: Allows the block to form corners with other blocks like stairs. Possible values are none, inner_left, inner_right, outer_left, and outer_right‌^{["Beta APIs" Experiment only]}.

Example:

"traits": {
  "minecraft:placement_direction": {
    "enabled_states": ["minecraft:corner_and_cardinal_direction"],
    "blocks_to_corner_with": [{"tags": "q.any_tag('minecraft:cornerable_stairs')"}]
  }
}

History

Navigation