Minecraft:Block definition

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

Structure

Block definitions are structured as follows:

• Template:Nbt
  • Template:Nbt: The format version of the file. This is a string representing a Template:BE version. It is recommended to use the latest version. For 26.0 and later, add a leading 1. For example: Template:Cd for Minecraft:26.0. Preview versions should use the version that it is a preview for (Example: Minecraft:Preview 26.0.27 would be Template:Cd).
  • Template:Nbt: Whether or not this block is using beta features.
  • Template:Nbt: The block definition.
    • Template:Nbt: The technical definition of the block.
      • Template:Nbt: A namespaced Minecraft:identifier for the block. This defines the technical name of the block for Minecraft:commands, scripts, and other Minecraft:add-on files.
      • Template:Nbt: Defines where the block is located in the Minecraft:creative inventory and Minecraft:recipe book.
        • Template:Nbt: The inventory tab to put the block under. Can be Template:Cd. If omitted or Template:Cd, the block will not appear in the creative inventory or recipe book.
        • Template:Nbt: The creative inventory group to add the block to. Custom groups can be added via the Template:File. Vanilla groups are:
          • Template:Cd
        • Template:Nbt: Whether or not the block is hidden from commands.
      • [[#States|Template:Nbt]]: Definitions of custom block state names and their possible values.
      • [[#Traits|Template:Nbt]]: The block traits to enable, which provide access to specific vanilla states.
    • Template:Nbt: The block's components. This defines the block's behavior and visuals.
    • Template:Nbt: The block's permutations, which allow for components to be added only under certain conditions.
      • Template:Nbt: A permutation
        • Template:Nbt: The condition when this permutation's components should be active. This should be a Minecraft:molang expression resulting in a boolean.
        • Template:Nbt: The components that should be active when the Template:Cd is true.

States

The Template:Nbt object is used to define custom Minecraft: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 Minecraft:molang query "query.block_state('<state_name>')".

Examples:

<syntaxhighlight lang=json copy> "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
 }

} </syntaxhighlight>

Traits

The Template:Nbt 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

Gives blocks the boolean states Template:Cd, allowing for the block to connect to blocks next to it.

• Template:Nbt
  • Template:Nbt: Which states to enable. The only valid value is minecraft:cardinal_connections.

Example:

<syntaxhighlight lang=json copy> "traits": {

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

} </syntaxhighlight>

minecraft:multi_block

Allows a block to be made up of multiple block parts like a Minecraft:door. This adds the Template:Cd state, which is an integer representing which part this block is in the multi block.

• Template:Nbt
  • Template:Nbt: Which states to enable. The only valid value is Template:Cd.
  • Template:Nbt: The number of parts that this multi block should have. The value must be between 2 and 4, inclusive.
  • Template:Nbt: The direction to place the parts of the multi block in. Can be either Template:Cd.

Example:

<syntaxhighlight lang=json copy> "traits": {

 "minecraft:multi_block": {
   "enabled_states": [
     "minecraft:multi_block_part"
   ],
   "parts": 3,
   "direction": "up"
 }

} </syntaxhighlight>

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 Template:Cd.
• minecraft:block_face: The block face that the player placed the block on, allowing for log and pillar functionality. Possible values are Template:Cd.

• Template:Nbt
  • Template:Nbt: Which states to enable. Valid values are Template:Cd.

Example:

<syntaxhighlight lang=json copy> "traits": {

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

} </syntaxhighlight>

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 Template:Cd.
• minecraft:facing_direction: Same as minecraft:cardinal_direction, but allows up and down as well. Possible values are Template:Cd.
• minecraft:corner: Allows the block to form corners with other blocks like stairs. Possible values are Template:Cd.

• Template:Nbt
  • Template:Nbt: Which states to enable. Valid values are Template:Cd. minecraft:corner_and_cardinal_direction enables both the minecraft:cardinal_direction and minecraft:corner states.
  • Template:Nbt: The offset to apply to the y rotation of the block. Can be Template:Cd.
  • Template:Nbt: A list of blocks (or block tags) to consider for minecraft:corner.
    • Template:NbtTemplate:Nbt: Either a block identifier or an object.
      • Template:Nbt: A molang expression representing the tags of the target blocks.

Example:

<syntaxhighlight lang=json copy> "traits": {

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

} </syntaxhighlight>