# Сущности и компоненты

## Обозначения типов, используемые далее

- vec3 - 3D вектор (массив из трех чисел)
- mat4 - матрица 4x4 (массив из 16 чисел)

Аннотации типов добавлены в целях документации и не являются частью синтаксиса
Lua.

## Сущность

Объект сущности доступен в компонентах как глобальная переменная **entity**.

```lua
-- Удаляет сущность (сущность может продолжать существовать до завершения кадра, но не будет отображена в этом кадре)
entity:despawn()

-- Возращает имя скелета сущности
entity:get_skeleton() -> str
-- Заменяет скелет сущности
entity:set_skeleton(name: str)

-- Возращает уникальный идентификатор сущности
entity:get_uid() -> int

-- Возвращает компонент по имени
entity:get_component(name: str) -> компонент или nil
-- Проверяет наличие компонента по имени
entity:has_component(name: str) -> bool
```

## Встроенные компоненты

### Transform

Компонент отвечает за позицию, масштаб и вращение сущности.

```lua
-- Сокращение
local tsf = entity.transform

-- Возвращает позицию сущности
tsf:get_pos() -> vec3
-- Устанавливает позицию сущности
tsf:set_pos(pos: vec3)

-- Возвращает масштаб сущности
tsf:get_size() -> vec3
-- Устанавливает масштаб сущности
tsf:set_size(size: vec3)

-- Возвращает вращение сущности
tsf:get_rot() -> mat4
-- Устанавливает вращение сущности
tsf:set_rot(size: mat4)
```

### Rigidbody

Компонент отвечает за физическое тело сущности.

```lua
-- Сокращение
local body = entity.rigidbody

-- Проверяет, включен ли рассчет физики тела
body:is_enabled() -> bool
-- Включает/выключает рассчет физики тела
body:set_enabled(enabled: bool)

-- Возвращает линейную скорость
body:get_vel() -> vec3
-- Устанавливает линейную скорость
body:set_vel(vel: vec3)

-- Возвращает размер хитбокса
body:get_size() -> vec3
-- Устанавливает размер хитбокса
body:set_size(size: vec3)

-- Возвращает множитель гравитации
body:get_gravity_scale() -> vec3
-- Устанавливает множитель гравитации
body:set_gravity_scale(scale: vec3)

-- Возвращает множитель затухания линейной скорости (используется для имитации сопротивления воздуха и трения)
body:get_linear_damping() -> number
-- Устанавливает множитель затухания линейной скорости
body:set_linear_damping(value: number)

-- Проверяет, включено ли вертикальное затухание скорости
body:is_vdamping() -> bool
-- Включает/выключает вертикальное затухание скорости
body:set_vdamping(enabled: bool)

-- Проверяет, находится ли сущность на земле (приземлена)
body:is_grounded() -> bool

-- Проверяет, находится ли сущность в "крадущемся" состоянии (не может упасть с блоков)
body:is_crouching() -> bool
-- Включает/выключает "крадущееся" состояние
body:set_crouching(enabled: bool)

-- Возвращает тип физического тела (dynamic/kinematic)
body:get_body_type() -> str
-- Устанавливает тип физического тела
body:set_body_type(type: str)
```

### Skeleton

Компонент отвечает за скелет сущности. См. [риггинг](../rigging.md).

```lua
-- Сокращение
local rig = entity.skeleton

-- Возвращает имя модели, назначенной на кость с указанным индексом
rig:get_model(index: int) -> str

-- Переназначает модель кости с указанным индексом
-- Сбрасывает до изначальной, если не указывать имя
rig:set_model(index: int, name: str)

-- Возвращает матрицу трансформации кости с указанным индексом
rig:get_matrix(index: int) -> mat4
-- Устанавливает матрицу трансформации кости с указанным индексом
rig:set_matrix(index: int, matrix: mat4)

-- Возвращает текстуру по ключу (динамически назначаемые текстуры - '$имя')
rig:get_texture(key: str) -> str

-- Назначает текстуру по ключу
rig:set_texture(key: str, value: str)

-- Возвращает индекс кости по имени или nil
rig:index(name: str) -> int

-- Проверяет статус видимости кости по индесу 
-- или всего скелета, если индекс не указан
rig:is_visible([optional] index: int) -> bool

-- Устанавливает статус видимости кости по индексу
-- или всего скелета, если индекс не указан
rig:set_visible([optional] index: int, status: bool)
```