From 221a34fa2ea394e9c969225e66f40369af82b103 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Wed, 2 Oct 2024 17:00:51 +0300
Subject: [PATCH] add block data-fields to docs

---
 doc/en/block-properties.md            | 29 +++++++++++++++++++++++++++
 doc/en/scripting/builtins/libblock.md | 24 ++++++++++++++++++++++
 doc/ru/block-properties.md            | 29 +++++++++++++++++++++++++++
 doc/ru/scripting/builtins/libblock.md | 24 ++++++++++++++++++++++
 4 files changed, 106 insertions(+)

diff --git a/doc/en/block-properties.md b/doc/en/block-properties.md
index 1827a026..011b1a77 100644
--- a/doc/en/block-properties.md
+++ b/doc/en/block-properties.md
@@ -142,3 +142,32 @@ Number of block inventory slots. Default - 0 (no inventory).
 ### *size*
 
 Array of three integers. Default value is `[1, 1, 1]`.
+
+## Block fields
+
+Block fields allow you to write more data unique to a specified voxel than the user bits allow.
+
+Block fields are declared in the following format:
+
+```json
+"fields": {
+    "name": {"type": "data_type"},
+    "array_name": {"type": "data_type", "length": "array_length"}
+}
+```
+
+Available data types:
+
+| Type  | Size      | Description            |
+| ----- | --------- | ---------------------- |
+| i8    | 1 byte    | signed integer 8 bits  |
+| i16   | 2 bytes   | signed integer 16 bits |
+| i32   | 4 bytes   | signed integer 32 bits |
+| i64   | 8 bytes   | integer signed 64 bits |
+| f32   | 4 bytes   | floating-point 32 bits |
+| f64   | 8 bytes   | floating-point 64 bits |
+| char  | 1 byte    | character              |
+
+Currently, the total sum of the field sizes cannot exceed 240 bytes.
+
+A character array can be used to store UTF-8 strings.
diff --git a/doc/en/scripting/builtins/libblock.md b/doc/en/scripting/builtins/libblock.md
index 87176e20..82aba4e7 100644
--- a/doc/en/scripting/builtins/libblock.md
+++ b/doc/en/scripting/builtins/libblock.md
@@ -132,3 +132,27 @@ To use filter `dest` argument must be filled with some value(can be nil), it's d
 The function returns a table with the results or nil if the ray does not hit any block.
 
 The result will use the destination table instead of creating a new one if the optional argument specified.
+
+## Data fields
+
+```lua
+-- writes a value to the specified block field
+-- * throws an exception if the types are incompatible
+-- * does nothing if the block does not have the field
+block.set_field(
+    x: int, y: int, z: int,
+    name: str,
+    value: bool|int|number|string,
+    [optional] index: int = 0
+)
+
+-- returns the value written to the block field
+-- * returns nil if:
+-- 1. the field does not exist
+-- 2. no writes were made to any block field
+block.get_field(
+    x: int, y: int, z: int,
+    name: str,
+    [optional] index: int = 0
+) -> the stored value or nil
+```
diff --git a/doc/ru/block-properties.md b/doc/ru/block-properties.md
index 7e3a9768..8e4d7d5d 100644
--- a/doc/ru/block-properties.md
+++ b/doc/ru/block-properties.md
@@ -145,3 +145,32 @@
 ### Размер блока - *size*
 
 Массив из трех целых чисел. Значение по-умолчанию - `[1, 1, 1]`.
+
+## Поля блока
+
+Поля блоков позволяет записывать больше уникальных для конкретного блока данных, чем это позволяют пользовательские биты.
+
+Поля блока объявляются в следующем формате:
+
+```json
+"fields": {
+    "имя": {"type": "тип_данных"},
+    "имя_массива": {"type": "тип_данных", "length": "длина_массива"}
+}
+```
+
+Доступные типы данных:
+
+| Тип   | Размер   | Описание                      |
+| ----- | -------- | ----------------------------- |
+| i8    | 1 байт   | целочисленный знаковый 8 бит  |
+| i16   | 2 байта  | целочисленный знаковый 16 бит |
+| i32   | 4 байта  | целочисленный знаковый 32 бит |
+| i64   | 8 байт   | целочисленный знаковый 64 бит |
+| f32   | 4 байта  | вещественный 32 бит           |
+| f64   | 8 байт   | вещественный 64 бит           |
+| char  | 1 байт   | символьный                    |
+
+На данный момент общая сумма размеров полей не может превышать 240 байт.
+
+Массив символьного типа может использоваться для хранения UTF-8 строк.
diff --git a/doc/ru/scripting/builtins/libblock.md b/doc/ru/scripting/builtins/libblock.md
index 150e776e..0b4f5e35 100644
--- a/doc/ru/scripting/builtins/libblock.md
+++ b/doc/ru/scripting/builtins/libblock.md
@@ -159,3 +159,27 @@ block.get_model(id: int) -> str
 -- возвращает массив из 6 текстур, назначенных на стороны блока
 block.get_textures(id: int) -> таблица строк
 ```
+
+## Поля данных
+
+```lua
+-- записывает значение в указанное поле блока
+-- * бросает исключение при несовместимости типов
+-- * ничего не делает при отсутствии поля у блока
+block.set_field(
+    x: int, y: int, z: int, 
+    name: str,
+    value: bool|int|number|string, 
+    [опционально] index: int = 0
+)
+
+-- возвращает значение записанное в поле блока
+-- * возвращает nil если:
+--     1. поле не существует
+--     2. ни в одно поле блока не было произведено записи
+block.get_field(
+    x: int, y: int, z: int, 
+    name: str, 
+    [опционально] index: int = 0
+) -> хранимое значение или nil
+```