From cadd08b132c18b13747f74f7a7a907db0c02071c Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Mon, 14 Jul 2025 01:10:10 +0300
Subject: [PATCH] update doc/*/block-properties.md

---
 doc/en/block-properties.md | 34 ++++++++++++++++++++++++++++++++++
 doc/ru/block-properties.md | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/doc/en/block-properties.md b/doc/en/block-properties.md
index 055a5901..676dfa44 100644
--- a/doc/en/block-properties.md
+++ b/doc/en/block-properties.md
@@ -34,6 +34,7 @@ Block model type from list:
 - "none" - invisible block (air)
 - "X" - grass model (two crossed sprites)
 - "aabb" - model based of block hitbox (complex hitbox will be combined into one). Examples: pipes, bulbs, panels.
+- "custom" - used when specifying custom models via *model-name*
 
 ### *model-name*
 
@@ -64,6 +65,39 @@ Rotation profile (set of available block rotations and behaviour of placing bloc
 - "pane" - panels, doors, signs
 - "stairs" - "pane" + flipped variants
 
+## Variants
+
+Some properties can vary dynamically, depending on the variant number stored in the user bits of the block.
+
+Variability parameters are specified in the `state-based` block:
+
+```json
+{
+    ...
+    "state-based": {
+        "offset": 0,
+        "bits": 4,
+        "variants": [
+            {...},
+            ...
+        ]
+    }
+}
+```
+
+- `offset` specifies the bit offset from which the variant index starts. (Default is 0)
+- `bits` specifies the number of bits encoding the variant index. (Default is 4).
+Currently, the maximum number of variants is 16, so specifying more than 4 bits does not make practical sense.
+
+Properties available for variance:
+- model
+- model-name
+- texture
+- texture-faces
+- model-primitives (deprecated)
+
+Variants are managed via `block.set_variant(x, y, z, index)`.
+
 ## Lighting
 
 ### *emission*
diff --git a/doc/ru/block-properties.md b/doc/ru/block-properties.md
index 8013ac14..1fabcd5c 100644
--- a/doc/ru/block-properties.md
+++ b/doc/ru/block-properties.md
@@ -34,6 +34,7 @@
 - "none" - невидимый блок (пример: воздух)
 - "X" - модель травы (крест из двух спрайтов)
 - "aabb" - модель, соответствующая хитбоксу блока (составной хитбокс будет объединен в один). Примеры: трубы, лампочки, панели.
+- "custom" - используется при указании собственной модели через *model-name*
 
 ### Имя модели - *model-name*
 
@@ -72,6 +73,39 @@
 При приближении к блоку движок создаст эмиттер, который будет работать 
 до разрушения блока или отдаления камеры на некоторое расстояние.
 
+## Варианты
+
+Некоторые свойства могут варьироваться динамически, в зависимости от номера варианта, хранимого в пользовательских битах блока.
+
+Параметры вариативности указываются в блоке `state-based`:
+
+```json
+{
+    ...
+    "state-based": {
+        "offset": 0,
+        "bits": 4,
+        "variants": [
+            {...},
+            ...
+        ]
+    }
+}
+```
+
+- `offset` определяет битового смещения, с которого начинается индекс варианта. (По-умолчанию - 0)
+- `bits` определяет число бит, кодирующих индекс варианта. (По-умолчанию - 4).
+На данный момент максимальное число вариантов - 16, поэтому указание более 4 бит не имеет практического смысла.
+
+Доступные для вариативности свойства:
+- model
+- model-name
+- texture
+- texture-faces
+- model-primitives (устарело)
+
+Управление состоянием производится через `block.set_variant(x, y, z, index)`.
+
 ## Освещение
 
 ### Излучение - *emission*: