# Библиотека *block*

```lua
-- Возвращает строковый id блока по его числовому id.
block.name(blockid: int) -> str

-- Возвращает числовой id блока, принимая в качестве агрумента строковый
block.index(name: str) -> int

-- Возвращает id материала блока.
block.material(blockid: int) -> str

-- Таблица материалов по их полным именам (пример: base:carpet)
block.materials: table<string, table>

-- Таблица пользовательских свойств блоков (см. ../../block-properties.md)
block.properties: table<int, table<string, object>>

-- Возвращает название блока, отображаемое в интерфейсе.
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)

-- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах
-- от лица игрока, вызывая событие on_placed.
-- playerid не является обязательным
block.place(x: int, y: int, z: int, id: int, states: int, [optional] playerid: int)

-- Ломает блок на заданных координатах от лица игрока, вызывая событие on_broken.
-- playerid не является обязательным
block.destruct(x: int, y: int, z: int, playerid: int)

-- Собирает полное состояние в виде целого числа
block.compose_state(state: {rotation: int, segment: int, userbits: int}) -> int

-- Разбирает полное состояние на: вращение, сегмент, пользовательские биты
block.decompose_state(state: int) -> {int, int, 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

-- Возвращает индекс варианта блока
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

```lua
block.raycast(start: vec3, dir: vec3, max_distance: number, [опционально] dest: table, [опционально] filter: table) -> {
    block: int, -- id блока
    endpoint: vec3, -- точка касания луча
    iendpoint: vec3, -- позиция блока, которого касается луч
    length: number, -- длина луча
    normal: vec3, -- вектор нормали поверхности, которой касается луч
} или nil
```

Бросает луч из точки start в направлении dir. Max_distance указывает максимальную длину луча.

Аргумент `filter` позволяет указать какие блоки являются "прозрачными" для луча, прим.: {"base:glass","base:water"}. 
Для использования агрумент `dest` нужно чем-то заполнить(можно nil), это сделано для обратной совместимости

Функция возвращает таблицу с результатами или nil, если луч не касается блока.

Для результата будет использоваться целевая (dest) таблица вместо создания новой, если указан опциональный аргумент.

## Вращение

Следующие функции используется для учёта вращения блока при обращении к соседним блокам или других целей, где направление блока имеет решающее значение.


```lua
-- Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа).
-- Если поворот отсутствует, возвращает 1, 0, 0
block.get_X(x: int, y: int, z: int) -> int, int, int
block.get_X(id: int, rotation: int) -> int, int, int

-- То же, но для оси Y (по-умолчанию 0, 1, 0)
block.get_Y(x: int, y: int, z: int) -> int, int, int
block.get_Y(id: int, rotation: int) -> int, int, int

-- То же, но для оси Z (по-умолчанию 0, 0, 1)
block.get_Z(x: int, y: int, z: int) -> int, int, int
block.get_Z(id: int, rotation: 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

-- возвращает имя модели блока
block.model_name(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
```
