Block Permutations
FORMAT & MIN ENGINE VERSION 1.21.20
Before you learn about block permutations, you should be confident with block states.
When working with block states, ensure that the min_engine_version
in your pack manifest is 1.20.20
or higher.
What are Permutations?
Block permutations represent all state value configurations that each block can possibly be in.
For example, if you added a custom block with two boolean states…
"description": {
"identifier": "wiki:permutations_example",
"states": {
"wiki:first_state": [false, true],
"wiki:second_state": [false, true]
}
}
…the 4 following block permutations would be added to the world:
Block Identifier | wiki:first_state | wiki:second_state |
---|---|---|
wiki:permutations_example | false | false |
wiki:permutations_example | true | false |
wiki:permutations_example | false | true |
wiki:permutations_example | true | true |
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 above would be 2 × 2, meaning this block has 4 permutations.
Misconceptions
- All blocks have permutations, even blocks with no states have 1 permutation that is simply made up of the block identifier.
- The number of permutations your block has is based on the states it has, not the number of items in the
permutations
array.
Conditionally Applying Components
The block permutations
array provides a way of conditionally applying components (including tags) to a block based on its current permutation.
Components within the permutations
array can override the block's base components, as well as those of other component lists. The latest component list in the permutations
array takes priority.
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:integer_state_example": [2, 4, 6, 8],
"wiki:boolean_state_example": [false, true],
"wiki:string_state_example": ["red", "green", "blue"]
}
},
"components": {},
"permutations": [
{
"condition": "q.block_state('wiki:integer_state_example') == 2",
"components": {
"minecraft:friction": 0.1
}
},
{
"condition": "q.block_state('wiki:boolean_state_example')",
"components": {
"minecraft:friction": 0.8 // Overrides previous permutation
}
},
{
"condition": "q.block_state('wiki:string_state_example') == 'red' && !q.block_state('wiki:boolean_state_example')",
"components": {
"minecraft:geometry": "geometry.pig"
}
}
]
}
}
Permutation Conditions
When evaluated as truthy (not false or 0), the involved component list is applied.
Permutation conditions are written as Molang expression strings, and have very limited context:
- Conditions are purely based on the block's permutation, therefore only have access to the
q.block_state
query function. - This also means that conditions cannot have side effects.
- The following math functions may not be used:
math.die_roll
,math.die_roll_integer
,math.random
,math.random_integer
. - Variables (including
temp
variables) cannot be assigned.
- The following math functions may not be used:
q.block_state('wiki:integer_state_example') < 6 && !q.block_state('wiki:boolean_state_example')
Permutation Limits
As with all things blocks, some limitations have been put in place by Mojang to prevent undesirable behavior.
Maximum Amount Per Block
A block cannot have more than 65,536 permutations (equivalent to 4 states with 16 values each). Exceeding this limit will result in a content log error and some states being absent from your block.
Maximum Amount Per World
A world should not have more than 65,536 block permutations registered (not necessarily placed). Exceeding this limit will result in the following content log warning:
World with over 65536 block permutations may degrade performance. Current world has XXXXX permutations.