132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
# Entities and components
|
|
|
|
## Types notation used below
|
|
|
|
- vec3 - 3D vector (array of three numbers)
|
|
- mat4 - 4x4 matrix (array of 16 numbers)
|
|
|
|
Type annotations are added for documentation purposes and are not part of the Lua syntax.
|
|
|
|
## Entity
|
|
|
|
The entity object is available in components as a global variable **entity**.
|
|
|
|
```lua
|
|
-- Deletes an entity (the entity may continue to exist until the frame ends, but will not be displayed in that frame)
|
|
entity:despawn()
|
|
|
|
-- Returns the name of the entity skeleton
|
|
entity:get_skeleton() -> str
|
|
-- Replaces the entity skeleton
|
|
entity:set_skeleton(name: str)
|
|
|
|
-- 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
|
|
```
|
|
|
|
## Built-in components
|
|
|
|
### Transform
|
|
|
|
The component is responsible for the position, scale and rotation of the entity.
|
|
|
|
```lua
|
|
-- 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(size: mat4)
|
|
```
|
|
|
|
### Rigidbody
|
|
|
|
The component is responsible for the physical body of the entity.
|
|
|
|
```lua
|
|
-- 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() -> vec3
|
|
-- Sets the gravity multiplier
|
|
body:set_gravity_scale(scale: vec3)
|
|
|
|
-- 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 velocity attenuation is enabled
|
|
body:is_vdamping() -> bool
|
|
-- Enables/disables vertical velocity attenuation
|
|
body:set_vdamping(enabled: bool)
|
|
|
|
-- 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 (dynamic/kinematic)
|
|
body:get_body_type() -> str
|
|
-- Sets the physical body type
|
|
body:set_body_type(type: str)
|
|
```
|
|
|
|
### Skeleton
|
|
|
|
The component is responsible for the entity skeleton. See [rigging](../rigging.md).
|
|
|
|
```lua
|
|
-- Alias
|
|
local rig = entity.skeleton
|
|
|
|
-- Returns the model name assigned to the bone at the specified index
|
|
rig:get_model(index: int) -> 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)
|
|
```
|