Block States

Block states allow your blocks to have variants, each with its own functionality and appearance through use of permutations.

Defining States ​

Valid state values can be defined as a boolean, integer or string array - or as an integer range by using an object. The first item in the values array is used as the default.

Permutation Limit ​

Each state may have up to 16 valid values defined. The amount of possible state value combinations (permutations) should not exceed 65,536.

To calculate how many permutations your block has, multiply the amount of valid state values each state has together. For instance, the calculation for the example below would be 3 × 2 × 3 × 6, meaning this block has 108 possible permutations.

Released from experiment Holiday Creator Features for format versions 1.19.70 and higher.

{
  "format_version": "1.21.20",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:custom_block",
      "states": {
        "wiki:string_state_example": ["red", "green", "blue"],
        "wiki:boolean_state_example": [false, true],
        "wiki:integer_state_example": [1, 2, 3],
        "wiki:integer_range_state_example": {
          "values": { "min": 0, "max": 5 } // The same as [0, 1, 2, 3, 4, 5]
        }
      }
    },
    "components": { ... },
    "permutations": [ ... ]
  }
}

Getting State Values ​

Listed below are ways to get the current value of block states in different contexts.

Molang Query Function ​

State values are returned by the block_state query function.

q.block_state('wiki:string_state_example') == 'blue'

Command Argument ​

The block states argument is included in commands such as execute and testforblock, and can be used to check the value of block states.

execute if block ~~~ wiki:custom_block["wiki:string_state_example"="blue", "wiki:integer_state_example"=4] run kill

Script API ​

The BlockPermutation.getState() method allows you to get the current value of different states.

customBlock.permutation.getState("wiki:integer_state_example") === 3;

Setting State Values ​

Command Argument ​

The block states argument is included in commands such as setblock and fill, and can be used to change states away from their default values.

setblock ~~~ wiki:custom_block["wiki:string_state_example"="blue", "wiki:integer_state_example"=4]

Script API ​

The BlockPermutation.withState() method returns a new block permutation with the specified state value changed. This permutation can be applied to the block using the Block.setPermutation() method, as seen below.

customBlock.setPermutation(customBlock.permutation.withState("wiki:boolean_state_example", false));