Merge branch 'main' into animation

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
-```
+```