From 9fe3ff5ede428c9c6a077bf4696cae7068f4be8a Mon Sep 17 00:00:00 2001 From: QuazChick Date: Sun, 29 Sep 2024 13:20:12 +0100 Subject: [PATCH] Improved block permutation documentation --- docs/blocks/block-permutations.md | 67 +++++++++++++++++++++++++++---- docs/blocks/block-states.md | 3 -- 2 files changed, 59 insertions(+), 11 deletions(-) diff --git a/docs/blocks/block-permutations.md b/docs/blocks/block-permutations.md index 6cae68081e7..dde2d9ae4e3 100644 --- a/docs/blocks/block-permutations.md +++ b/docs/blocks/block-permutations.md @@ -1,6 +1,6 @@ --- title: Block Permutations -description: The block permutations array provides a way of conditionally applying components to a block based on its current permutation. +description: Block permutations represent all state configurations that blocks can possibly be in. category: General nav_order: 7 mentions: @@ -14,15 +14,46 @@ Before you learn about block permutations, you should be confident with [block s When working with block states, ensure that the `min_engine_version` in your pack manifest is `1.20.20` or higher. ::: -The block `permutations` array provides a way of conditionally applying components (including event triggers and tags) to a block based on its current permutation (collection of state values). +## What are Permutations? -Components within the `permutations` array can override the block's base components, as well as those of other component lists. The latest item in the `permutations` array takes priority. +Block permutations represent all state value configurations that each block can possibly be in. -## Defining Permutations +For example, if you added a custom block with two boolean states… -The `permutations` array is a direct child of `minecraft:block` and is made up of objects containing components which get applied if the evaluated condition is truthy (not false or 0). +minecraft:block -**Permutation conditions must adhere to their [Molang limitations](#permutation-conditions).** +```json +"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._ @@ -65,7 +96,7 @@ _Released from experiment `Holiday Creator Features` for format versions 1.19.70 } ``` -## Permutation Conditions +### Permutation Conditions When evaluated as truthy (not false or 0), the involved component list is applied. @@ -74,4 +105,24 @@ Permutation conditions are written as Molang expression strings, and have very l - 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 cannot be assigned. + - Variables (including `temp` variables) cannot be assigned. + +```c +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. diff --git a/docs/blocks/block-states.md b/docs/blocks/block-states.md index a6db01cd1c9..5c5456905e7 100644 --- a/docs/blocks/block-states.md +++ b/docs/blocks/block-states.md @@ -22,9 +22,6 @@ Valid state values can be defined as a boolean, integer or string array - or as **Each state may have up to 16 valid values defined. The amount of possible state value combinations ([permutations](/blocks/block-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._ BP/blocks/custom_block.json