# Сущности и компоненты ## Сущность Объект сущности доступен в компонентах как глобальная переменная **entity**. ```lua -- Удаляет сущность (сущность может продолжать существовать до завершения кадра, но не будет отображена в этом кадре) entity:despawn() -- Возвращает индекс определения сущности (числовой ID) entity:def_index() -> int -- Возвращает имя определения сущности (строковый ID) entity:def_name() -> str -- Возращает имя скелета сущности entity:get_skeleton() -> str -- Заменяет скелет сущности entity:set_skeleton(name: str | nil) -- Возращает уникальный идентификатор сущности 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 игрока, к которому привязана сущность, в ином же случае возвращает -1. -- Во время инициализации компонентов при спавне сущности так же возвращает -1, -- так как привязка происходит после инициализации. -- Возвращает nil, если сущность не существует. entity:get_player() -> int или nil ``` ### Сущность игрока Сущность, привязанная к игроку, служит его телом: позиция игрока берётся из её Transform, а хитбокс игрока - это её Rigidbody. Движок спавнит такую сущность автоматически по определению из параметра `player-entity` файла `config/defaults.toml` (в паке base - `base:player`) и привязывает её к игроку. ID сущности игрока возвращает `player.get_entity(playerid)`. `entity:get_player()` позволяет отличить сущность игрока от прочих сущностей и узнать, какому игроку она принадлежит. Например, компонент выпавшего предмета `base:drop` при касании другой сущности проверяет `other:get_player()`: игрок подбирает предмет, а другой выпавший предмет объединяется с ним в стопку. Чтобы выполнить код в момент привязки, используйте событие компонента [on_player_set](#события-компонента). ## Встроенные компоненты ### 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() -> number -- Устанавливает множитель гравитации body:set_gravity_scale(scale: number) -- Возвращает множитель затухания линейной скорости (используется для имитации сопротивления воздуха и трения) body:get_linear_damping() -> number -- Устанавливает множитель затухания линейной скорости body:set_linear_damping(value: number) -- Проверяет, включено ли вертикальное затухание скорости body:is_vdamping() -> bool -- Возвращает множитель вертикального затухания скорости body:get_vdamping() -> number -- Включает/выключает вертикальное затухание скорости / устанавливает значение множителя -- (true соответствует 1.0, false - 0.0) 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) -- Возвращает материал тела (то же, что и у блоков) body:get_material() -> str -- Устанавливает материал тела body:set_material(material: str) -- Возвращает массу тела body:get_mass() -> number -- Устанавливает массу тела body:set_mass(mass: number) -- Возвращает упругость тела body:get_elasticity() -> number -- Устанавливает упругость тела body:set_elasticity(elasticity: number) -- Возвращает скорость поверхности, на которой находится тело, либо {0,0,0} body:get_ground_vel() -> vec3 -- Проверяет свойство 'selectable' у сущности (непрозрачность для лучей) body:is_selectable() -> bool -- Устанавливает значение свойство 'selectable' у сущности body:set_selectable(flag: bool) ``` #### Затухание скорости После расчёта движения скорость тела за каждый кадр меняется так (`delta` - длительность кадра в секундах): ```lua -- псевдокод local k = body:is_grounded() and 10.0 or body:get_linear_damping() local ground_vel = body:get_ground_vel() vel.x = vel.x + (ground_vel.x - vel.x) * delta * k vel.z = vel.z + (ground_vel.z - vel.z) * delta * k if body:get_vdamping() > 0 then vel.y = vel.y / (1 + delta * k * body:get_vdamping()) end ``` **linear_damping** (по умолчанию 0.5) - скорость затухания горизонтальной скорости относительно поверхности, на которой находится тело. Значение не ограничено диапазоном 0..1: - 0 - затухания нет, тело в воздухе сохраняет горизонтальную скорость; - чем больше значение, тем быстрее затухание: горизонтальная скорость уменьшается примерно в e^(k*t) раз за t секунд. При 0.5 она падает вдвое примерно за 1.4 с, при 10 - примерно за 0.07 с; - при `delta * k = 1` (например, k = 60 при 60 FPS) скорость гасится за один кадр. Значения больше этого дают перескок через скорость поверхности, а при `delta * k > 2` скорость начинает расти. Пока тело стоит на земле (`body:is_grounded()`), вместо установленного значения используется фиксированное значение 10 (трение о поверхность), поэтому `set_linear_damping` влияет только на движение в воздухе. **vdamping** (по умолчанию 1.0) - множитель затухания вертикальной скорости относительно `k`. На горизонтальное затухание не влияет: - 0 (или `false`) - вертикальная скорость не затухает; - 1 (или `true`) - вертикальная скорость затухает так же быстро, как горизонтальная; - значения больше 1 усиливают вертикальное затухание, меньше 1 - ослабляют. Вертикальное затухание ограничивает скорость падения: при постоянной гравитации она стремится примерно к `g * gravity_scale / (k * vdamping)`, где `g` - ускорение свободного падения в мире. ### 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(status: bool) -- Устанавливает статус видимости кости по индексу rig:set_visible(index: int, status: bool) -- Возвращает цвет сущности rig:get_color() -> vec4 -- Возвращает цвет кости по индексу rig:get_color(index: int) -> vec4 -- Устанавливает цвет сущности rig:set_color(color: vec3 | vec4) -- Устанавливает цвет кости по индексу rig:set_color(color: vec3 | vec4, index: int) ``` ## Пользовательские компоненты Компонент описывается в виде скрипта `{пак}/scripts/components/{имя}.lua`. Компонент будет доступен для использования в описании сущности как `{пак}:{имя}`. Пример: `core:scripts/components/pathfinding.lua` -> `core:pathfinding`. Для **каждой** сущности, содержащей компонент, создаётся **отдельный экземпляр** со **своим пространством имен** внутри пространства имён пака. Глобальные переменные, объявляемые в нём, играют роль публичных полей компонента (как и глобальные функции). Компоненты сущности указываются через [список "components"](../entity-properties.md#cписок-компонентов---components) > [!WARNING] > При выходе сущности за пределы зоны прогрузки она удаляется, вызывая события. > При повторном попадании в зону прогрузки сущность спавнится заново. ## События компонента ```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_physics_update(delta: number) ``` Вызывается после каждого шага физики ```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 игрока передается в качестве аргумента. ```lua function on_player_set(playerid: int) ``` Вызывается при прикреплении сущности к игроку.