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
11 KiB
Entities and components
Entity
The entity object is available in components as a global variable entity.
-- Deletes an entity (the entity may continue to exist until the frame ends, but will not be displayed in that frame)
entity:despawn()
-- Returns entity definition index (integer ID)
entity:def_index() -> int
-- Returns entity definition name (string ID)
entity:def_name() -> str
-- Returns the name of the entity skeleton
entity:get_skeleton() -> str
-- Replaces the entity skeleton
entity:set_skeleton(name: str | nil)
-- Returns the unique entity identifier
entity:get_uid() -> int
-- Returns the component by name
entity:get_component(name: str) -> component or nil
-- Checks for the presence of a component by name
entity:has_component(name: str) -> bool
-- Retrieves a component by name. Throws an exception if it does not exist
entity:require_component(name: str) -> component
-- Enables/disables the component
entity:set_enabled(name: str, enable: bool)
-- Returns id of player the entity is bound, otherwise -1 is returned.
-- At components initialization -1 is also returned,
-- since the binding occurs after initialization.
-- Returns nil if the entity does not exist.
entity:get_player() -> int or nil
-- Checks the 'selectable' property of an entity (raycast opacity)
body:is_selectable() -> bool
-- Sets the value of the 'selectable' property of an entity
body:set_selectable(flag: bool)
Player entity
An entity bound to a player serves as the player's body: the player position
is taken from its Transform, and the player hitbox is its Rigidbody. The engine
spawns this entity automatically from the definition set by the player-entity
parameter of config/defaults.toml (base:player in the base pack) and binds
it to the player. player.get_entity(playerid) returns the player entity ID.
entity:get_player() lets you tell the player entity apart from other entities
and find out which player it belongs to. For example, the dropped item component
base:drop checks other:get_player() when touching another entity: a player
picks the item up, while another dropped item gets merged into one stack.
Use the on_player_set component event to run code when the binding happens.
Custom Components
A component is defined as a script in {pack}/scripts/components/{name}.lua.
The component will be available for use in the entity definition as {pack}:{name}.
Example: core:scripts/components/pathfinding.lua -> core:pathfinding.
For each entity containing a component, a separate instance is created with its own namespace within the pack namespace. Global variables declared in it act as public fields of the component (same for global functions).
Entity components are specified via the "components" list
Built-in components
Transform
The component is responsible for the position, scale and rotation of the entity.
-- Alias
local tsf = entity.transform
-- Returns the position of the entity
tsf:get_pos() -> vec3
-- Sets the entity position
tsf:set_pos(pos:vec3)
-- Returns the entity scale
tsf:get_size() -> vec3
-- Sets the entity scale
tsf:set_size(size: vec3)
-- Returns the entity rotation
tsf:get_rot() -> mat4
-- Sets entity rotation
tsf:set_rot(rotation: mat4)
Rigidbody
The component is responsible for the physical body of the entity.
-- Alias
local body = entity.rigidbody
-- Checks if body physics calculation is enabled
body:is_enabled() -> bool
-- Enables/disables body physics calculation
body:set_enabled(enabled: bool)
-- Returns linear velocity
body:get_vel() -> vec3
-- Sets linear velocity
body:set_vel(vel: vec3)
-- Returns the size of the hitbox
body:get_size() -> vec3
-- Sets the hitbox size
body:set_size(size: vec3)
-- Returns the gravity multiplier
body:get_gravity_scale() -> number
-- Sets the gravity multiplier
body:set_gravity_scale(scale: number)
-- Returns the linear velocity attenuation multiplier (used to simulate air resistance and friction)
body:get_linear_damping() -> number
-- Sets the linear velocity attenuation multiplier
body:set_linear_damping(value: number)
-- Checks if vertical damping is enabled
body:is_vdamping() -> bool
-- Returns the vertical damping multiplier
body:get_vdamping() -> number
-- Enables/disables vertical damping / sets vertical damping multiplier
-- (true is 1.0, false is 0.0)
body:set_vdamping(enabled: bool | number)
-- Checks if the entity is on the ground
body:is_grounded() -> bool
-- Checks if the entity is in a "crouching" state (cannot fall from blocks)
body:is_crouching() -> bool
-- Enables/disables the "crouching" state
body:set_crouching(enabled: bool)
-- Returns the type of physical body (static/dynamic/kinematic)
body:get_body_type() -> str
-- Sets the physical body type
body:set_body_type(type: str)
-- Returns the body material (same as for blocks)
body:get_material() -> str
-- Sets the body material
body:set_material(material: str)
-- Returns the body's mass
body:get_mass() -> number
-- Sets the body's mass
body:set_mass(mass: number)
-- Returns the body's elasticity
body:get_elasticity() -> number
-- Sets the body's elasticity
body:set_elasticity(elasticity: number)
-- Returns the velocity of the surface the body is on, or {0,0,0}
body:get_ground_vel() -> vec3
Velocity damping
After the movement is calculated, the body velocity changes every frame
as follows (delta is the frame duration in seconds):
-- pseudocode
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 by default) is the decay rate of the horizontal velocity relative to the surface the body is on. The value is not limited to the 0..1 range:
- 0 - no damping, the body keeps its horizontal velocity in the air;
- the greater the value, the faster the damping: the horizontal velocity decreases roughly e^(k*t) times in t seconds. At 0.5 it halves in about 1.4 s, at 10 - in about 0.07 s;
- at
delta * k = 1(e.g. k = 60 at 60 FPS) the velocity is cancelled in one frame. Greater values overshoot the surface velocity, and atdelta * k > 2the velocity starts to grow.
While the body is on the ground (body:is_grounded()), the fixed value 10
(surface friction) is used instead of the set one, so set_linear_damping
only affects movement in the air.
vdamping (1.0 by default) is the vertical velocity damping multiplier
relative to k. It does not affect horizontal damping:
- 0 (or
false) - the vertical velocity is not damped; - 1 (or
true) - the vertical velocity is damped as fast as the horizontal one; - values above 1 strengthen vertical damping, values below 1 weaken it.
Vertical damping limits the falling speed: under constant gravity it tends
to about g * gravity_scale / (k * vdamping), where g is the world
gravity acceleration.
Skeleton
The component is responsible for the entity skeleton. See rigging.
-- Alias
local rig = entity.skeleton
-- Returns the model name assigned to the bone at the specified index
rig:get_model(index: int) -> str
-- Reassigns the bone model at the specified index
-- Resets to original if name is not specified
rig:set_model(index: int, name: str)
-- Returns the bone transformation matrix at the specified index
rig:get_matrix(index: int) -> mat4
-- Sets the bone transformation matrix at the specified index
rig:set_matrix(index: int, matrix: mat4)
-- Returns the texture by key (dynamically assigned textures - '$name')
rig:get_texture(key: str) -> str
-- Assigns texture by key
rig:set_texture(key: str, value: str)
-- Returns the bone index by name or nil
rig:index(name: str) -> int
-- Checks the visibility status of a bone by index
-- or the skeleton if no index is specified
rig:is_visible([optional] index: int) -> bool
-- Sets the visibility status of the skeleton
rig:set_visible(status: bool)
-- Sets the visibility status of a bone by index
rig:set_visible(index: int, status: bool)
-- Returns the color of the entity
rig:get_color() -> vec4
-- Return the color of the bone by index
rig:get_color(index: int) -> vec4
-- Sets the color of the entity
rig:set_color(color: vec3 | vec4)
-- Sets the color of the bone by index
rig:set_color(color: vec3 | vec4, index: int)
Warning
When an entity moves outside the loaded area, it is removed, triggering the event. When it re-enters the loaded area, the entity is spawned again.
Component events
function on_despawn()
Called when the entity is despawned.
function on_grounded(force: number)
Called on landing. The first argument is the impact force (Speed module).
function on_fall()
Called when the entity starts to fall.
function on_save()
Called before component data is saved. Here you can write the data you want to save into the SAVED_DATA table, which is available for the entire life of the component.
function on_update(tps: int)
Called every entities tick (currently 20 times per second).
function on_physics_update(delta: number)
Called after each physics step
function on_render(delta: number)
Called every frame before the entity is rendered.
function on_sensor_enter(index: int, entity: int)
Called when another entity hits the sensor with the index passed as the first argument. The UID of the entity that entered the sensor is passed as the second argument.
function on_sensor_exit(index: int, entity: int)
Called when another entity exits the sensor with the index passed as the first argument. The UID of the entity that left the sensor is passed as the second argument.
function on_aim_on(playerid: int)
Called when the player aims at the entity. The player ID is passed as an argument.
function on_aim_off(playerid: int)
Called when the player takes aim away from the entity. The player ID is passed as an argument.
function on_attacked(attackerid: int, playerid: int)
Called when an entity is attacked (LMB on the entity). The first argument is the UID of the attacking entity. The attacking player ID is passed as the second argument. If the entity was not attacked by a player, the value of the second argument will be -1.
function on_used(playerid: int)
Called when an entity is used (RMB by entity). The player ID is passed as an argument.
function on_player_set(playerid: int)
Called when an entity is attached to a player.