Improved block permutation documentation

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).
+<CodeHeader>minecraft:block</CodeHeader>
 
-**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 &times; 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.

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._
 
 <CodeHeader>BP/blocks/custom_block.json</CodeHeader>