add entities.raycast & update docs structure

doc/ru/scripting/builtins/libblock.md

@@ -0,0 +1,143 @@
+# Библиотека *block*
+
+```lua
+-- Возвращает строковый id блока по его числовому id.
+block.name(blockid: int) -> str
+
+-- Возвращает числовой id блока, принимая в качестве агрумента строковый
+block.index(name: str) -> int
+
+-- Возвращает id материала блока.
+block.material(blockid: int) -> str
+
+-- Возвращает название блока, отображаемое в интерфейсе.
+block.caption(blockid: int) -> str
+
+-- Возвращает числовой id блока на указанных координатах.
+-- Если чанк на указанных координатах не загружен, возвращает -1.
+block.get(x: int, y: int, z: int) -> int
+
+-- Возвращает состояние (поворот + доп. информация) в виде целого числа
+block.get_states(x: int, y: int, z: int) -> int
+
+-- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах.
+block.set(x: int, y: int, z: int, id: int, states: int)
+```
+
+> [!WARNING]
+> `block.set` не вызывает событие on_placed.
+
+```lua
+-- Проверяет, является ли блок на указанных координатах полным
+block.is_solid_at(x: int, y: int, z: int) -> bool
+
+-- Проверяет, можно ли на заданных координатах поставить блок 
+-- (примеры: воздух, трава, цветы, вода)
+block.is_replaceable_at(x: int, y: int, z: int) -> bool
+
+-- Возвращает количество id доступных в загруженном контенте блоков
+block.defs_count() -> int
+
+-- Возвращает числовой id предмета, указанного в свойстве *picking-item*.
+block.get_picking_item(id: int) -> int
+```
+
+### Raycast
+
+```lua
+block.raycast(start: vec3, dir: vec3, max_distance: number, [опционально] dest: table) -> {
+    block: int, -- id блока
+    endpoint: vec3, -- точка касания луча
+    iendpoint: vec3, -- позиция блока, которого касается луч
+    length: number, -- длина луча
+    normal: vec3 -- вектор нормали поверхности, которой касается луч
+} или nil
+```
+
+Бросает луч из точки start в направлении dir. Max_distance указывает максимальную длину луча.
+
+Функция возвращает таблицу с результатами или nil, если луч не касается блока.
+
+Для результата будет использоваться целевая (dest) таблица вместо создания новой, если указан опциональный аргумент.
+
+## Вращение
+
+Следующие функции используется для учёта вращения блока при обращении к соседним блокам или других целей, где направление блока имеет решающее значение.
+
+
+```lua
+-- Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа).
+-- Если поворот отсутствует, возвращает 1, 0, 0
+block.get_X(x: int, y: int, z: int) -> int, int, int
+
+-- То же, но для оси Y (по-умолчанию 0, 1, 0)
+block.get_Y(x: int, y: int, z: int) -> int, int, int
+
+-- То же, но для оси Z (по-умолчанию 0, 0, 1)
+block.get_Z(x: int, y: int, z: int) -> int, int, int
+
+-- Возвращает индекс поворота блока в его профиле вращения (не превышает 7).
+block.get_rotation(x: int, y: int, z: int) -> int
+
+-- Устанавливает вращение блока по индексу в его профиле вращения.
+block.set_rotation(x: int, y: int, z: int, rotation: int)
+
+-- Возвращает имя профиля вращения (none/pane/pipe)
+block.get_rotation_profile(id: int) -> str
+```
+
+## Расширенные блоки
+
+Расширенные блоки - те, размер которых превышает 1x1x1
+
+```lua
+-- Проверяет, является ли блок расширенным.
+block.is_extended(id: int) -> bool
+
+-- Возвращает размер блока.
+block.get_size(id: int) -> int, int, int
+
+-- Проверяет является ли блок сегментом расширенного блока, не являющимся главным.
+block.is_segment(x: int, y: int, z: int) -> bool
+
+-- Возвращает позицию главного сегмента расширенного блока или исходную позицию,
+-- если блок не является расширенным.
+block.seek_origin(x: int, y: int, z: int) -> int, int, int
+```
+
+## Пользовательские биты
+
+Выделенная под использования в скриптах часть поля `voxel.states` хранящего доп-информацию о вокселе, такую как вращение блока. На данный момент выделенная часть составляет 8 бит.
+
+```lua
+-- Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа
+block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
+
+-- Записывает указанное число бит значения value в user bits по выбранному смещению
+block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
+```
+
+
+## Физика
+
+Информация свойствах блока, используемых физическим движком.
+
+```lua
+-- Возвращает массив из двух векторов (массивов из 3 чисел):
+-- 1. Минимальная точка хитбокса
+-- 2. Размер хитбокса
+-- rotation_index - индекс поворота блока
+block.get_hitbox(id: int, rotation_index: int) -> {vec3, vec3}
+```
+
+## Модель
+
+Информация о модели блока.
+
+```lua
+-- возвращает тип модели блока (block/aabb/custom/...)
+block.get_model(id: int) -> str
+
+-- возвращает массив из 6 текстур, назначенных на стороны блока
+block.get_textures(id: int) -> таблица строк
+```