voxelcore/doc/ru/scripting/ecs.md
ostermine 8a3bdc504b docs: explain player entity and velocity damping in ecs.md
Describe what the entity bound to a player is and what
entity:get_player() is used for. Document how linear_damping and
vdamping affect the body velocity (formula from PhysicsSolver),
value ranges, defaults, bool values of set_vdamping and the fixed
damping used while the body is grounded.

Closes #867
2026-10-10 15:54:14 +03:00

17 KiB
Raw Blame History

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

Сущность

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

-- Удаляет сущность (сущность может продолжать существовать до завершения кадра, но не будет отображена в этом кадре)
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

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

-- Сокращение
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

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

-- Сокращение
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 — длительность кадра в секундах):

-- псевдокод
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

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

-- Сокращение
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"

Warning

При выходе сущности за пределы зоны прогрузки она удаляется, вызывая события. При повторном попадании в зону прогрузки сущность спавнится заново.

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

function on_despawn()

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

function on_grounded(force: number)

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

function on_fall()

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

function on_save()

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

function on_update(tps: int)

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

function on_physics_update(delta: number)

Вызывается после каждого шага физики

function on_render(delta: number)

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

function on_sensor_enter(index: int, entity: int)

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

function on_sensor_exit(index: int, entity: int)

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

function on_aim_on(playerid: int)

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

function on_aim_off(playerid: int)

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

function on_attacked(attackerid: int, playerid: int)

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

function on_used(playerid: int)

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

function on_player_set(playerid: int)

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