Merge branch 'dev' of https://github.com/Xertis/VoxelEngine-Cpp into dev

doc/ru/scripting/builtins/libapp.md

@@ -27,7 +27,10 @@ app.sleep_until(
     predicate: function() -> bool,
     -- максимальное количество тактов цикла движка, после истечения которых
     -- будет брошено исключение "max ticks exceed"
-    [опционально] max_ticks = 1e9
+    [опционально] max_ticks = 1e9,
+    -- максимальное длительность ожидания в секундах. 
+    -- (работает с системным временем, включая test-режим)
+    [опционально] timeout = 1e9
 )
 ```
 

doc/ru/scripting/builtins/libbase64.md

@@ -8,4 +8,10 @@ base64.encode(bytes: table|ByteArray) -> str
 
 -- Декодирует base64 строку в ByteArray или таблицу чисел, если второй аргумент установлен на true
 base64.decode(base64string: str, [опционально]usetable: bool=false) -> table|ByteArray
+
+-- Кодирует массив байт в urlsafe-base64 строку ('-', '_' вместо '+', '/')
+base64.encode_urlsafe(bytes: table|ByteArray) -> str
+
+-- Декодирует urlsafe-base64 строку в ByteArray или таблицу чисел, если второй аргумент установлен на true
+base64.decode_urlsafe(base64string: str, [опционально]usetable: bool=false) -> table|ByteArray
 ```

doc/ru/scripting/builtins/libblock.md

@@ -67,6 +67,9 @@ block.get_variant(x: int, y: int, z: int) -> int
 
 -- Устанавливает вариант блока по индексу
 block.set_variant(x: int, y: int, z: int, index: int) -> int
+
+-- Проверяет наличие тега у блока
+block.has_tag(id: int, tag: str) -> bool
 ```
 
 ### Raycast

doc/ru/scripting/builtins/libitem.md

@@ -33,6 +33,9 @@ item.emission(itemid: int) -> str
 
 -- Возвращает значение свойства `uses`
 item.uses(itemid: int) -> int
+
+-- Проверяет наличие тега у предмета
+item.has_tag(itemid: int, tag: str) -> bool
 ```
 
 

doc/ru/scripting/builtins/libnetwork.md

@@ -6,9 +6,15 @@
 
 ```lua
 -- Выполняет GET запрос к указанному URL.
--- После получения ответа, передаёт текст в функцию callback.
--- В случае ошибки в onfailure будет передан HTTP-код ответа.
-network.get(url: str, callback: function(str), [опционально] onfailure: function(int))
+network.get(
+    url: str,
+    -- Функция, вызываемая при получении ответа
+    callback: function(str),
+    -- Обработчик ошибок
+    [опционально] onfailure: function(int, str),
+    -- Список дополнительных заголовков запроса
+    [опционально] headers: table<str>
+)
 
 -- Пример:
 network.get("https://api.github.com/repos/MihailRis/VoxelEngine-Cpp/releases/latest", function (s)
@@ -16,13 +22,28 @@ network.get("https://api.github.com/repos/MihailRis/VoxelEngine-Cpp/releases/lat
 end)
 
 -- Вариант для двоичных файлов, с массивом байт вместо строки в ответе.
-network.get_binary(url: str, callback: function(table|ByteArray), [опционально] onfailure: function(int))
+network.get_binary(
+    url: str,
+    callback: function(ByteArray),
+    [опционально] onfailure: function(int, Bytearray),
+    [опционально] headers: table<str>
+)
 
 -- Выполняет POST запрос к указанному URL.
 -- На данный момент реализована поддержка только `Content-Type: application/json`
 -- После получения ответа, передаёт текст в функцию callback.
 -- В случае ошибки в onfailure будет передан HTTP-код ответа.
-network.post(url: str, data: table, callback: function(str), [опционально] onfailure: function(int))
+network.post(
+    url: str,
+    -- Тело запроса в виде таблицы, конвертируемой в JSON или строки
+    body: table|str,
+    -- Функция, вызываемая при получении ответа
+    callback: function(str),
+    -- Обработчик ошибок
+    [опционально] onfailure: function(int, str),
+    -- Список дополнительных заголовков запроса
+    [опционально] headers: table<str>
+)
 ```
 
 ## TCP-Соединения

doc/ru/scripting/builtins/libpathfinding.md

@@ -0,0 +1,66 @@
+# Библиотека *pathfinding*
+
+Библиотека *pathfinding* предоставляет функции для работы с системой поиска пути в игровом мире. Она позволяет создавать и управлять агентами, которые могут находить маршруты между точками в мире.
+
+При использовании в логике сущностей следует использовать компонент `core:pathfinding`.
+
+## Компонент `core:pathfinding`
+
+```lua
+local pf = entity:get_component("core:pathfinding")
+
+--- ...
+local x = ...
+local y = ...
+local z = ...
+
+--- Установка цели для агента
+pf.set_target({x, y, z})
+
+--- Получение текущей цели агента
+local target = pf.get_target() --> vec3 или nil
+--- ...
+
+--- Получение текущего маршрута агента
+local route = pf.get_route() --> table<vec3> или nil
+--- ...
+```
+
+## Функции библиотеки
+
+```lua
+--- Создание нового агента. Возвращает идентификатор созданного агента
+local agent = pathfinding.create_agent() --> int
+
+--- Удаление агента по идентификатору. Возвращает true, если агент существовал, иначе false
+pathfinding.remove_agent(agent: int) --> bool
+
+--- Установка состояния агента (включен/выключен)
+pathfinding.set_enabled(agent: int, enabled: bool)
+
+--- Проверка состояния агента. Возвращает true, если агент включен, иначе false
+pathfinding.is_enabled(agent: int) --> bool
+
+--- Создание маршрута на основе заданных точек. Возвращает массив точек маршрута
+pathfinding.make_route(start: vec3, target: vec3) --> table<vec3>
+
+--- Асинхронное создание маршрута на основе заданных точек.
+--- Функция позволяет выполнять поиск пути в фоновом режиме, не блокируя основной поток выполнения
+pathfinding.make_route_async(agent: int, start: vec3, target: vec3)
+
+--- Получение маршрута, который агент уже нашел. Используется для получения маршрута после асинхронного поиска.
+--- Если поиск ещё не завершён, возвращает nil. Если маршрут не найден, возвращает пустую таблицу.
+pathfinding.pull_route(agent: int) --> table<vec3> или nil
+
+--- Установка максимального количества посещенных блоков для агента. Используется для ограничения объема работы алгоритма поиска пути.
+pathfinding.set_max_visited(agent: int, max_visited: int)
+
+--- Добавление тега избегаемых блоков
+pathfinding.avoid_tag(
+    agent: int,
+    -- тег избегаемых блоков
+    tag: string, [опционально],
+    -- стоимость пересечения блока
+    cost: int = 10
+)
+```

doc/ru/scripting/builtins/libplayer.md

@@ -89,6 +89,13 @@ player.set_loading_chunks(playerid: int, bool)
 
 Геттер и сеттер свойства, определяющего, прогружает ли игрок чанки вокруг.
 
+```lua
+player.get_interaction_distance(playerid: int) -> float
+player.set_interaction_distance(playerid: int, distance: float)
+```
+
+Геттер и сеттер свойства, определяющего максимальную дистанцию взаимодействия.
+
 ```lua
 player.set_spawnpoint(playerid: int, x: number, y: number, z: number) 
 player.get_spawnpoint(playerid: int) -> number, number, number

doc/ru/scripting/builtins/librandom.md

@@ -0,0 +1,38 @@
+# Библиотека *random*
+
+Библиотека функций для генерации случайный чисел.
+
+## Недетерминированные числа
+
+```lua
+-- Генерирует случайное число в диапазоне [0..1)
+random.random() --> number
+
+-- Генерирует случайное целое число в диапазоне [0..n]
+random.random(n) --> number
+
+-- Генерирует случайное целое число в диапазоне [a..b]
+random.random(a, b) --> number
+
+-- Генерирует случайный массив байт длиной n
+random.bytes(n: number) -> Bytearray
+
+-- Генерирует UUID версии 4
+random.uuid() -> str
+```
+
+## Псевдослучайные числа
+
+Библиотека предоставляет класс Random - генератор с собственным изолированным состоянием.
+
+```lua
+local rng = random.Random()
+
+-- Используется аналогично math.random
+local a = rng:random() --> [0..1)
+local b = rng:random(10) --> [0..10]
+local c = rng:random(5, 20) --> [5..20]
+
+-- Устанавливает состояние генератора для генерации воспроизводимой последовательности случайных чисел
+rng:seed(42)
+```

doc/ru/scripting/builtins/libvecn.md

@@ -100,6 +100,13 @@ vecn.length(a: vector)
 
 ```
 
+#### Дистанция - *vecn.distance(...)*
+
+```lua
+-- возвращает расстояние между двумя векторами
+vecn.distance(a: vector, b: vector)
+```
+
 #### Абсолютное значение - *vecn.abs(...)*
 
 ```lua
@@ -136,6 +143,16 @@ vecn.pow(v: vector, exponent: number, dst: vector)
 vecn.dot(a: vector, b: vector)
 ```
 
+#### Смешивание - *vecn.mix(...)*
+
+```lua
+-- возвращает вектор a * (1.0 - t) + b * t
+vecn.mix(a: vector, b: vector, t: number)
+
+-- записывает в dst вектор a * (1.0 - t) + b * t
+vecn.mix(a: vector, b: vector, t: number, dst: vector)
+```
+
 #### Перевод в строку - *vecn.tostring(...)*
 > [!WARNING]
 > Возвращает только тогда, когда содержимым является вектор
@@ -160,6 +177,12 @@ vec2.angle(v: vec2)
 
 -- возвращает угол направления вектора {x, y} в градусах [0, 360]
 vec2.angle(x: number, y: number) 
+
+-- возвращает повернутый вектор на угол в градусах против часовой стрелки
+vec2.rotate(v: vec2, angle: number) -> vec2
+
+-- записывает повернутый вектор на угол в градусах против часовой стрелки в dst
+vec2.rotate(v: vec2, angle: number, dst: vec2) -> vec2
 ```
 
 
@@ -192,6 +215,10 @@ print("mul_scal: " .. vec3.tostring(result_mul_scal)) -- {6, 12, 12}
 local result_norm = vec3.normalize(v1_3d)
 print("norm: " .. vec3.tostring(result_norm)) -- {0.333, 0.667, 0.667}
 
+-- дистанция между векторами
+local result_distance = vec3.distance(v1_3d, v2_3d)
+print("distance: " .. result_distance) -- 43
+
 -- длина вектора
 local result_len = vec3.length(v1_3d)
 print("len: " .. result_len) -- 3
@@ -211,4 +238,9 @@ print("pow: " .. vec3.tostring(result_pow)) -- {1, 4, 4}
 -- скалярное произведение векторов
 local result_dot = vec3.dot(v1_3d, v2_3d)
 print("dot: " .. result_dot) -- 250
+
+-- смешивание векторов
+local result_mix = vec3.mix(v1_3d, v2_3d, 0.25)
+print("mix: " .. vec3.tostring(result_mix)) -- {3.25, 6.5, 11.5}
+
 ```

doc/ru/scripting/ecs.md

@@ -26,6 +26,8 @@ entity:get_uid() -> int
 entity:get_component(name: str) -> компонент или nil
 -- Проверяет наличие компонента по имени
 entity:has_component(name: str) -> bool
+-- Запрашивает компонент по имени. Бросает исключение при отсутствии
+entity:require_component(name: str) -> компонент
 
 -- Включает/выключает компонент по имени
 entity:set_enabled(name: str, enable: bool)
@@ -95,8 +97,10 @@ body:set_linear_damping(value: number)
 
 -- Проверяет, включено ли вертикальное затухание скорости
 body:is_vdamping() -> bool
--- Включает/выключает вертикальное затухание скорости
-body:set_vdamping(enabled: bool)
+-- Возвращает множитель вертикального затухания скорости
+body:get_vdamping() -> number
+-- Включает/выключает вертикальное затухание скорости / устанавливает значение множителя
+body:set_vdamping(enabled: bool | number)
 
 -- Проверяет, находится ли сущность на земле (приземлена)
 body:is_grounded() -> bool
@@ -188,6 +192,12 @@ function on_update(tps: int)
 
 Вызывается каждый такт сущностей (на данный момент - 20 раз в секунду).
 
+```lua
+function on_physics_update(delta: number)
+```
+
+Вызывается после каждого шага физики
+
 ```lua
 function on_render(delta: number)
 ```

doc/ru/scripting/events.md

@@ -46,6 +46,13 @@ function on_blocks_tick(tps: int)
 
 Вызывается tps (20) раз в секунду. Используйте 1/tps вместо `time.delta()`.
 
+```lua
+function on_block_tick(x, y, z, tps: number)
+```
+
+Вызывается tps (20 / tick-interval) раз в секунду для конкретного блока.
+Используйте 1/tps вместо `time.delta()`.
+
 ```lua
 function on_player_tick(playerid: int, tps: int)
 ```