Merge branch 'main' into animation

doc/en/block-properties.md

@@ -1,6 +1,6 @@
 # Block properties
 
-## Visual
+## Visual & Audio
 
 ### *texture*
 
@@ -70,6 +70,18 @@ Rotation profile (set of available block rotations and behaviour of placing bloc
 - "pane" - panels, doors, signs
 - "stairs" - "pane" + flipped variants
 
+### *particles*
+
+Particles are specified as a JSON object. Property names can be found [in the particles section](particles.md).
+
+When camera is near to the block, the engine will create an emitter that will run
+until the block is destroyed or the camera moves away a certain distance.
+
+### Material - *material*
+
+Defines the name of the block's material in the format `pack:material_name`, which affects the selection of block interaction sounds.
+Material definitions are located in /block_materials.
+
 ## Variants
 
 Some properties can vary dynamically, depending on the variant number stored in the user bits of the block.

doc/en/rigging.md

@@ -38,7 +38,7 @@ Models are loaded automatically; adding them to preload.json is not required.
 
 ## Models
 
-Models should be located in the models folder. Currently only OBJ format is supported.
+Models must be located in the models folder. Currently, the following formats are supported: obj, vec3, and [vcm](vcm.md).
 
 >[!IMPORTANT]
 > When loading an obj model, the \*.mtl file is ignored.

doc/en/scripting.md

@@ -16,6 +16,7 @@ Subsections:
     - [block](scripting/builtins/libblock.md)
     - [byteutil](scripting/builtins/libbyteutil.md)
     - [cameras](scripting/builtins/libcameras.md)
+    - [ctypes](scripting/builtins/libctypes.md)
     - [entities](scripting/builtins/libentities.md)
     - [file](scripting/builtins/libfile.md)
     - [gfx.blockwraps](scripting/builtins/libgfx-blockwraps.md)

doc/en/scripting/builtins/libapp.md

@@ -180,14 +180,34 @@ app.get_content_sources() -> table<string>
 
 Returns a list of content sources (paths), in descending priority order.
 
-``lua
+```lua
 app.set_content_sources(sources: table<string>)
 ```
 
 Sets a list of content sources (paths). Specified in descending priority order.
 
-``lua
+```lua
 app.reset_content_sources()
 ```
 
 Resets content sources.
+
+## Sub-instances
+
+```lua
+-- Creates a headless engine instance with the current project and the specified application script.
+-- Returns the instance ID. The number of active sub-instances is currently limited to one.
+app.start_background_instance(
+    -- script file
+    app_script: string,
+    -- log file
+    output_file: string | nil
+) -> int
+
+-- Checks if the engine sub-instance is alive.
+app.is_instance_alive(handle: int) -> boolean
+
+-- Stops the engine sub-instance.
+-- Returns true if the instance was alive at the time of the call.
+app.terminate(handle: int) -> boolean
+```

doc/en/scripting/builtins/libblock.md

@@ -28,7 +28,8 @@ block.get(x: int, y: int, z: int) -> int
 block.get_states(x: int, y: int, z: int) -> int
 
 -- Set block with given integer ID and state (default - 0) at given position.
-block.set(x: int, y: int, z: int, id: int, states: int)
+-- If noupdate=true is passed, the `on_update` event will not be called for adjacent blocks.
+block.set(x: int, y: int, z: int, id: int, states: int, noupdate: boolean=false)
 
 -- Places a block with a given integer id and state (default - 0) at given position.
 -- on behalf of the player, calling the on_placed event.

doc/en/scripting/builtins/libctypes.md

@@ -0,0 +1,28 @@
+# *ctypes* Library
+
+A library for safe work with C types.
+
+| ctypes.\<name\> | C-Type   | Minimum              | Maximum              |
+| --------------- | -------- | -------------------- | -------------------- |
+| uint8           | uint8_t  | 0                    | 255                  |
+| uint16          | uint16_t | 0                    | 65535                |
+| uint32          | uint32_t | 0                    | 4294967295           |
+| uint64          | uint64_t | 0                    | 18446744073709551615 |
+| int8            | int8_t   | -128                 | 127                  |
+| int16           | int16_t  | -32768               | 32767                |
+| int32           | int32_t  | -2147483648          | 2147483647           |
+| int64           | int64_t  | -9223372036854775808 | 9223372036854775807  |
+
+
+Usage examples:
+
+```lua
+local x = ctypes.uint64(1234)
+print(x) --> 1234ULL (cdata)
+local y = ctypes.uint64("18446744073709551615")
+print(y) --> 18446744073709551615ULL (cdata)
+print(x + y) --> 1233ULL
+
+local z = tonumber(x)
+print(z) --> 1234 (number)
+```

doc/ru/block-properties.md

@@ -1,6 +1,6 @@
 # Свойства блоков
 
-## Вид
+## Вид & Звук
 
 ### Текстура - *texture*
 
@@ -78,6 +78,11 @@
 При приближении к блоку движок создаст эмиттер, который будет работать 
 до разрушения блока или отдаления камеры на некоторое расстояние.
 
+### Материал - *material*
+
+Определяет имя материала блока в формате `пак:имя_материала`, что влияет на выбор звуков взаимодействия с блоком.
+Определения материалов расположены в /block_materials.
+
 ## Варианты
 
 Некоторые свойства могут варьироваться динамически, в зависимости от номера варианта, хранимого в пользовательских битах блока.

doc/ru/rigging.md

@@ -38,7 +38,7 @@
 
 ## Модели
 
-Модели должны располагаться в папке models. На данный момент поддерживается только OBJ формат.
+Модели должны располагаться в папке models. На данный момент поддерживаются форматы: obj, vec3 и [vcm](vcm.md).
 
 >[!IMPORTANT]
 > При загрузке obj модели игнорируется файл \*.mtl. 

doc/ru/scripting.md

@@ -16,6 +16,7 @@
     - [block](scripting/builtins/libblock.md)
     - [byteutil](scripting/builtins/libbyteutil.md)
     - [cameras](scripting/builtins/libcameras.md)
+    - [ctypes](scripting/builtins/libctypes.md)
     - [entities](scripting/builtins/libentities.md)
     - [file](scripting/builtins/libfile.md)
     - [gfx.blockwraps](scripting/builtins/libgfx-blockwraps.md)

doc/ru/scripting/builtins/libapp.md

@@ -142,4 +142,24 @@ app.set_content_sources(sources: table<string>)
 
 -- Сбрасывает список источников контента.
 app.reset_content_sources()
-```
+```
+
+## Под-экземпляры
+
+```lua
+-- Создаёт headless-экземпляр движка с текущим проектом и указанным сценарием.
+-- Возвращает id экземпляра. Число живых под-экземпляров, на данный момент, ограничено одним.
+app.start_background_instance(
+    -- файл сценария
+    app_script: string,
+    -- файл лога
+    output_file: string | nil
+) -> int
+
+-- Проверяет, жив ли под-экземпляр движка.
+app.is_instance_alive(handle: int) -> boolean
+
+-- Останавливает под-экземпляр движка.
+-- Возвращает true если экземпляр был жив в момент вызова.
+app.terminate_instance(handle: int) -> boolean
+```

doc/ru/scripting/builtins/libctypes.md

@@ -0,0 +1,28 @@
+# Библиотека *ctypes*
+
+Библиотека для безопасной работы с типами языка С.
+
+| ctypes.\<name\> | С-тип    | Минимум              | Максимум             |
+| ------------- | -------- | -------------------- | -------------------- |
+| uint8         | uint8_t  | 0                    | 255                  |
+| uint16        | uint16_t | 0                    | 65535                |
+| uint32        | uint32_t | 0                    | 4294967295           |
+| uint64        | uint64_t | 0                    | 18446744073709551615 |
+| int8          | int8_t   | -128                 | 127                  |
+| int16         | int16_t  | -32768               | 32767                |
+| int32         | int32_t  | -2147483648          | 2147483647           |
+| int64         | int64_t  | -9223372036854775808 | 9223372036854775807  |
+
+
+Примеры использования:
+
+```lua
+local x = ctypes.uint64(1234)
+print(x) --> 1234ULL (cdata)
+local y = ctypes.uint64("18446744073709551615")
+print(y) --> 18446744073709551615ULL (cdata)
+print(x + y) --> 1233ULL
+
+local z = tonumber(x)
+print(z) --> 1234 (number)
+```

doc/ru/scripting/bytearray.md

@@ -2,6 +2,8 @@
 
 *Bytearray* - динамический байтовый массив, реализованный через LuaJIT FFI. По нему можно итерироваться стандартными функциями **pairs** и **ipairs**
 
+<small>Примечание касаемо условных обозначений в документации: псведотип `posint` означает натуральное (положительное ненулевое целое) число.</small>
+
 ## Основное
 ### Создание массива
 ```lua
@@ -22,29 +24,64 @@ bytes:insert(index: int, value: int)
 -- Удаляет элемент(ы), если передан `count`, удалит `count` кол-во элементов с выбранного индекса.
 bytes:remove(index: int, [опционально] count: int)
 
--- Очищает массив
+-- Очищает массив.
 bytes:clear()
 
+--[[
+Заполняет массив определённым байтом полностью либо в определённом диапазоне.
+Логика работы следующая: если параметр size или index равны nil, то указанным байтом будет заполнен весь массив,
+    иначе будет заполнен диапазон внутри массива начиная с индекса index и размером size.
+В случае выхода заполняемого блока за границы массива генерирует соответствующую ошибку.
+]]
+bytes:fill(index: posint/nil, size: posint/nil, byte: uint8)
+
 -- Создаёт новый Bytearray, содержащий копию части данных с offset до offset+length
 bytes:slice(offset: int, length: int) -> Bytearray
+
+--[[
+Копирует блок байт из исходного массива, начиная с индекса srcindex, в массив dst, начиная в нём с индекса dstindex.
+В случае выхода за границы исходного, конечного массива, либо при некорректном значении параметра size генерирует соответствующую ошибку.
+]]
+bytes:copy(srcindex: posint, dst: Bytearray, dstindex: posint, size: posint)
+
+--[[
+Безопасно копирует перекрывающиеся области памяти (байт) в пределах одного массива.
+В случае выхода за пределы массива начального или конечного диапазона байт генерирует соответствующую ошибку.
+]]
+bytes:move(fromindex: posint, toindex: posint, size: posint)
 ```
 
 ## View
 
 Это "вьюшки" поверх Bytearray, которые интерпретируют его байты как массив чисел другого размера - **без копирования данных**.
 
-Не имеет своих методов, является просто объектной ссылкой на оригинальный Bytearray.
+Практически не имеют своих методов, являются простыми объектными ссылками на оригинальный Bytearray.
 
-| Класс        | Тип элементов      | Размер  |
-| ------------ | ------------------ | ------- |
-| `I16view` | `int16_t` | 2 байта |
-| `U16view` | `uint16_t`         | 2 байта |
-| `I32view` | `int32_t`          | 4 байта |
-| `U32view` | `uint32_t`         | 4 байта |
+| Класс        | Тип элементов      | Размер    |
+| ------------ | ------------------ | --------- |
+| `I8view`     | `int8_t`           | 1 байт    |
+| `I16view`    | `int16_t`          | 2 байта   |
+| `U16view`    | `uint16_t`         | 2 байта   |
+| `I32view`    | `int32_t`          | 4 байта   |
+| `U32view`    | `uint32_t`         | 4 байта   |
+| `I64view`    | `int64_t`          | 8 байт    |
+| `U64view`    | `uint64_t`         | 8 байт    |
+| `FLTview`    | `float`            | 4 байта*  |
+| `DBLview`    | `double`           | 8 байт*   |
 
----
+<small>* Размеры "оригинальных" C-шных типов являются платформозависимыми и их точный размер не описан в стандарте языка. В данной таблице предоставлены наиболее распространённые размеры типов.</small>
 
-### Пример использования
+### Специфические методы "вьюшек"
+
+```lua
+--[[
+Возвращает размер типа вьюшки. Результат тот же, что и от применения оператора sizeof() из языка C для данного типа.
+    Полезно для вьюшек, использующих C-шные типы нефиксированного размера, например те же float или double.
+]]
+view:typesize() -> posint
+```
+
+## Пример использования
 
 ```lua
 local bytes = Bytearray({1, 0, 2, 0, 250, 255})
@@ -59,4 +96,4 @@ print(i16[3]) -- -6 (signed вьюшка)
 for _, num in ipairs(i16) do
     print(num)
 end -- 1; 2; -6
-```
+```