add entities.raycast & update docs structure

2024-07-15 05:42:09 +03:00
parent 23cfe4a4cf
commit 9cdf3e29cc
9 changed files with 389 additions and 348 deletions
@@ -82,12 +82,12 @@ Block is not a physical obstacle if **false**
 An array of 6 numbers describing an offset an size of a block hitbox.

 Array *\[0.25, 0.0, 0.5,  0.75, 0.4, 0.3\]* describes hitbox width:
- 0.75m width (from east to west)
- 0.4m height
- 0.3m length (from south to north)
 - offset 0.25m east
 - offset 0.0m up
 - offset 0.5m north
+- 0.75m width (from east to west)
+- 0.4m height
+- 0.3m length (from south to north)

 ### *grounded*

@@ -9,6 +9,8 @@ Subsections:
 - [UI properties and methods](scripting/ui.md)
 - [Entities and components](scripting/ecs.md)
 - [Libraries](#)
+    - [block](scripting/builtins/libblock.md)
+    - [entities](scripting/builtins/libentities.md)
    - [mat4](scripting/builtins/libmat4.md)
 - [Module core:bit_converter](scripting/modules/core_bit_converter.md)
 - [Module core:data_buffer](scripting/modules/core_data_buffer.md)
@@ -337,167 +339,6 @@ inventory.move(invA: int, slotA: int, invB: int, slotB: int)
 Move item from slotA of invA to slotB of invB. invA may be the same as invB.
 If slotB will be chosen automaticly if argument is not specified.

-## *block* library
-
-```python
-block.name(blockid: int) -> str
-```
-
-Returns block string ID (name) by index.
-
-```python
-block.index(name: str) -> int
-```
-
-Returns block integer ID (index) by name.
-
-```python
-block.material(blockid: int) -> str
-```
-
-Returns the id of the block material.
-
-```python
-block.caption(blockid: int) -> str
-```
-
-Returns the block name displayed in the interface.
-
-```python
-block.get(x: int, y: int, z: int) -> int
-```
-
-Returns integer ID by block position
-
-```python
-block.get_states(x: int, y: int, z: int) -> int
-```
-
-Returns block state (rotation + additional information) as an integer.
-
-```python
-block.set(x: int, y: int, z: int, id: int, states: int)
-```
-
-Set block with specified integer ID and state (default - 0) at specified position.
-
-> [!WARNING]
-> `block.set` does not trigger on_placed.
-
-```python
-block.is_solid_at(x: int, y: int, z: int) -> bool
-```
-
-Check if block at the specified position is solid.
-
-```python
-block.is_replaceable_at(x: int, y: int, z: int) -> bool
-```
-Check if block may be placed at specified position. (Examples: air, water, grass, flower)
-
-```python
-block.defs_count() -> int
-```
-
-Returns count of available block IDs.
-
-Following three functions return direction vectors based on block rotation.
-
-
-```python
-block.get_X(x: int, y: int, z: int) -> int, int, int
-```
-
-Returns X: integer direction vector of the block at specified coordinates.
-Example: no rotation: 1, 0, 0
-
-```python
-block.get_Y(x: int, y: int, z: int) -> int, int, int
-```
-
-Returns Y: integer direction vector of the block at specified coordinates.
-Example: no rotation: 0, 1, 0
-
-```python
-block.get_Z(x: int, y: int, z: int) -> int, int, int
-```
-
-Returns Z: integer direction vector of the block at specified coordinates.
-Example: no rotation: 0, 0, 1
-
-
-```python
-block.get_rotation(x: int, y: int, z: int) -> int
-```
-
-Returns block rotation index based on used profile.
-
-```python
-block.set_rotation(x: int, y: int, z: int, rotation: int)
-```
-
-Set block rotation by index.
-
-### Extended blocks
-
-Extended blocks are blocks with size greather than 1x1x1
-
-```python
-block.is_extended(id: int) -> bool
-```
-
-Checks whether the block is extended.
-
-```python
-block.get_size(id: int) -> int, int, int
-```
-
-Returns the block size.
-
-```python
-block.is_segment(x: int, y: int, z: int) -> bool
-```
-
-Checks whether the block is a non-origin segment of an extended block.
-
-```python
-block.seek_origin(x: int, y: int, z: int) -> int, int, int
-```
-
-Returns the position of the main segment of an extended block or the original position,
-if the block is not extended.
-
-### User bits
-
-Part of a voxel data used for scripting. Size: 8 bit.
-
-```python
-block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
-``` 
-
-Get specified bits as an unsigned integer.
-
-```python
-block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
-```
-Set specified bits.
-
-```lua
-block.raycast(start: vec3, dir: vec3, max_distance: number, [optional] dest: table) -> {
-    block: int, -- block id
-    endpoint: vec3, -- point of the ray hit point
-    iendpoint: vec3, -- position of the block hit by the ray
-    length: number, -- ray length
-    normal: vec3 -- normal vector of the surface hit by the ray
-} or nil
-```
-
-Casts a ray from the start point in the direction of *dir*. Max_distance specifies the maximum ray length.
-
-The function returns a table with the results or nil if the ray does not hit any block.
-
-The result will use the destination table instead of creating a new one if the optional argument specified.
-
 ## *item* library

 ```python
@@ -0,0 +1,115 @@
+# *block* library
+
+```lua
+-- Returns block string ID (name) by index.
+block.name(blockid: int) -> str
+
+-- Returns block integer ID (index) by name.
+block.index(name: str) -> int
+
+-- Returns the id of the block material.
+block.material(blockid: int) -> str
+
+-- Returns the block name displayed in the UI.
+block.caption(blockid: int) -> str
+
+-- Returns integer ID by block position
+block.get(x: int, y: int, z: int) -> int
+
+-- Returns block state (rotation + additional information) as an integer.
+-- Used to save complete block information.
+block.get_states(x: int, y: int, z: int) -> int
+
+-- Set block with specified integer ID and state (default - 0) at specified position.
+block.set(x: int, y: int, z: int, id: int, states: int)
+```
+
+> [!WARNING]
+> `block.set` does not trigger on_placed.
+
+```lua
+-- Check if block at the specified position is solid.
+block.is_solid_at(x: int, y: int, z: int) -> bool
+
+-- Check if block may be placed at specified position.
+-- (Examples: air, water, grass, flower)
+block.is_replaceable_at(x: int, y: int, z: int) -> bool
+
+-- Returns count of available block IDs.
+block.defs_count() -> int
+```
+
+## Rotation
+
+Following three functions return direction vectors based on block rotation.
+
+
+```lua
+-- Returns X: integer direction vector of the block at specified coordinates.
+-- Example: no rotation: 1, 0, 0.
+block.get_X(x: int, y: int, z: int) -> int, int, int
+
+-- Same for axis Y. Default: 0, 1, 0.
+block.get_Y(x: int, y: int, z: int) -> int, int, int
+
+-- Same for axis Z. Default: 0, 0, 1.
+block.get_Z(x: int, y: int, z: int) -> int, int, int
+
+-- Returns block rotation index based on used profile.
+block.get_rotation(x: int, y: int, z: int) -> int
+
+-- Set block rotation by index.
+block.set_rotation(x: int, y: int, z: int, rotation: int)
+```
+
+## Extended blocks
+
+Extended blocks are blocks with size greather than 1x1x1
+
+```lua
+-- Checks whether the block is extended.
+block.is_extended(id: int) -> bool
+
+-- Returns the block size.
+block.get_size(id: int) -> int, int, int
+
+-- Checks whether the block is a non-origin segment of an extended block.
+block.is_segment(x: int, y: int, z: int) -> bool
+
+-- Returns the position of the main segment of an extended block
+-- or the original position, if the block is not extended.
+block.seek_origin(x: int, y: int, z: int) -> int, int, int
+```
+
+## User bits
+
+Part of a voxel data used for scripting. Size: 8 bit.
+
+```python
+block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
+``` 
+
+Get specified bits as an unsigned integer.
+
+```python
+block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
+```
+Set specified bits.
+
+## Raycast
+
+```lua
+block.raycast(start: vec3, dir: vec3, max_distance: number, [optional] dest: table) -> {
+    block: int, -- block id
+    endpoint: vec3, -- point of the ray hit point
+    iendpoint: vec3, -- position of the block hit by the ray
+    length: number, -- ray length
+    normal: vec3 -- normal vector of the surface hit by the ray
+} or nil
+```
+
+Casts a ray from the start point in the direction of *dir*. Max_distance specifies the maximum ray length.
+
+The function returns a table with the results or nil if the ray does not hit any block.
+
+The result will use the destination table instead of creating a new one if the optional argument specified.
@@ -0,0 +1,26 @@
+# Library *entities*
+
+The library is designed to work with a registry of entities.
+
+```lua
+-- Returns an entity by unique identifier
+-- The table returned is the same one available in the entity components.
+entities.get(uid: int) -> table
+
+-- Creates the specified entity.
+-- args - table of component parameter tables (ARGS variable)
+-- args is optional
+entities.spawn(name: str, pos: vec3, [optional] args: table)
+
+-- Checks the existence of an entity by a unique identifier.
+entities.exists(uid: int) -> bool
+```
+
+```lua
+entities.raycast(start: vec3, dir: vec3, max_distance: number,
+ ignore: int, [optional] destination: table) -> table or nil
+```
+
+The function is an extended version of [block.raycast](libblock.md#raycast). Returns a table with the results if the ray touches a block or entity.
+
+Accordingly, this will affect the presence of the *entity* and *block* fields.