From 4952de471639455296dffb00ce6b057ba2eb2c56 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sat, 13 Jul 2024 10:51:21 +0300
Subject: [PATCH] add english version of the ecs.md

---
 doc/en/scripting.md     |   1 +
 doc/en/scripting/ecs.md | 131 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+)
 create mode 100644 doc/en/scripting/ecs.md

diff --git a/doc/en/scripting.md b/doc/en/scripting.md
index 5d4d8fc8..4d6620bb 100644
--- a/doc/en/scripting.md
+++ b/doc/en/scripting.md
@@ -7,6 +7,7 @@ Subsections:
 - [User input](scripting/user-input.md)
 - [Filesystem and serialization](scripting/filesystem.md)
 - [UI properties and methods](scripting/ui.md)
+- [Entities and components](scripting/ecs.md)
 - [Libraries](#)
     - [mat4](scripting/builtins/libmat4.md)
 - [Module core:bit_converter](scripting/modules/core_bit_converter.md)
diff --git a/doc/en/scripting/ecs.md b/doc/en/scripting/ecs.md
new file mode 100644
index 00000000..852f756e
--- /dev/null
+++ b/doc/en/scripting/ecs.md
@@ -0,0 +1,131 @@
+# 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)
+```