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.

Each state may have up to 16 valid values defined. For integer range states, this means that the max value cannot be more than 15 higher than the min value.

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

{
  "format_version": "1.21.40",
  "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));