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

## Сущность

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

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

-- Возвращает индекс определения сущности (числовой ID)
entity:def_index() -> int

-- Возвращает имя определения сущности (строковый ID)
entity:def_name() -> str

-- Возращает имя скелета сущности
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
-- Запрашивает компонент по имени. Бросает исключение при отсутствии
entity:require_component(name: str) -> компонент

-- Включает/выключает компонент по имени
entity:set_enabled(name: str, enable: bool)

-- Возвращает id игрока, к которому привязана сущность
entity:get_player() -> int или nil
```

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

### 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(rotation: 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:get_vdamping() -> number
-- Включает/выключает вертикальное затухание скорости / устанавливает значение множителя
body:set_vdamping(enabled: bool | number)

-- Проверяет, находится ли сущность на земле (приземлена)
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)

-- Возвращает цвет сущности
rig:get_color() -> vec3

-- Устанавливает цвет сущности
rig:set_color(color: vec3)
```

## События компонента

```lua
function on_despawn()
```

Вызывается при удалении сущности.

```lua
function on_grounded(force: number)
```

Вызывается при приземлении. В качестве первого аргумента передается сила удара. (На данный момент - модуль скорости).

```lua
function on_fall()
```

Вызывается при начале падения.

```lua
function on_save()
```

Вызывается перед сохранением данных компонентов. Здесь можно записать данные, которые нужно сохранить, в таблицу *SAVED_DATA*, которая доступна весь срок жизни компонента.

```lua
function on_update(tps: int)
```

Вызывается каждый такт сущностей (на данный момент - 20 раз в секунду).

```lua
function on_render(delta: number)
```

Вызывается каждый кадр перед рендером сущности.

```lua
function on_sensor_enter(index: int, entity: int)
```

Вызывается при попадании другой сущности в сенсор с индексом, передаваемым первым аргументом. UID сущности, попавшей в сенсор, передается вторым аргументом.

```lua
function on_sensor_exit(index: int, entity: int)
```

Вызывается при выходе другой сущности из сенсора с индексом, передаваемым первым аргументом. UID сущности, покинувшей сенсор, передается вторым аргументом.

```lua
function on_aim_on(playerid: int)
```

Вызывается при наведении прицела игрока на сущность. ID игрока передается в качестве аргумента.

```lua
function on_aim_off(playerid: int)
```

Вызывается когда игрок уводит прицел с сущности. ID игрока передается в качестве аргумента.

```lua
function on_attacked(attackerid: int, playerid: int)
```

Вызывается при атаке на сущность (ЛКМ по сущности). Первым аргументом передается UID атакующей сущности. ID атакующего игрока передается вторым аргументом. Если сущность была атакована не игроком, значение второго аргумента будет равно -1.


```lua
function on_used(playerid: int)
```

Вызывается при использовании сущности (ПКМ по сущности). ID игрока передается в качестве аргумента.

