Merge pull request #862 from MihailRis/update-raycast

add advanced raycast function

doc/en/scripting/builtins/libblock.md

@@ -159,6 +159,8 @@ The function returns a table with the results or nil if the ray does not hit any
 
 The result will use the destination table instead of creating a new one if the optional argument specified.
 
+Use `world.raycast(...)` for more detailed configuration.
+
 ## Model and physics
 
 ```lua

doc/en/scripting/builtins/libentities.md

@@ -71,3 +71,5 @@ entities.raycast(start: vec3, dir: vec3, max_distance: number, ignore: int, [opt
 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.
+
+Use `world.raycast(...)` for more detailed configuration.

doc/en/scripting/builtins/libworld.md

@@ -70,4 +70,45 @@ world.save_chunk_data(
     -- compressed chunk data
     data: Bytearray
 )
+
+-- Casts a ray from the start point in the dir direction.
+world.raycast(
+    params: table {
+        [==[ required parameters ]==]
+        -- starting point
+        start: vec3,
+        -- ray direction vector
+        dir: vec3,
+        -- maximum distance
+        distance: number,
+
+        [==[ additional parameters (entities) ]==]
+        -- consider entities
+        entities: bool = true,
+        -- uid of the ignored entity
+        ignore_uid: number = 0 (ENTITY_NONE),
+        -- id of the entity types used for filtering
+        filter_entities: table<string|number> = nil,
+        -- exclusion filtering mode:
+        --   if true, filter_entities defines the list of ignored entity types
+        entities_exclusion: bool = false,
+
+        [==[ additional parameters (blocks) ]==]
+        -- id of the block types used for filtering
+        filter_blocks: table<string|number> = nil,
+        -- exclusion filtering mode:
+        --   if true, filter_blocks defines the list Ignored
+        blocks_exclusion: bool = true,
+        -- include blocks with selectable=false
+        nonselect_blocks: bool = false;
+    }
+) -> {
+    block: int or nil, -- block id
+    entity: int or nil, -- entity uid
+    endpoint: vec3, -- ray touchpoint
+    iendpoint: vec3, -- position of the block touched by the ray
+    length: number, -- ray length
+    normal: vec3, -- normal vector of the surface touched by the ray
+} or nil if the ray did not touch a block or entity
+```
 ```

doc/ru/scripting/builtins/libblock.md

@@ -115,6 +115,8 @@ block.raycast(start: vec3, dir: vec3, max_distance: number, [опциональ
 
 Для результата будет использоваться целевая (dest) таблица вместо создания новой, если указан опциональный аргумент.
 
+Для более тонкой настройки используйте `world.raycast(...)`.
+
 ## Вращение
 
 ```lua
@@ -209,4 +211,4 @@ block.get_field(
     name: string, 
     [опционально] index: int = 0
 ) -> any | nil
-```
+```

doc/ru/scripting/builtins/libentities.md

@@ -69,4 +69,6 @@ entities.raycast(start: vec3, dir: vec3, max_distance: number, ignore: int, [opt
 
 Функция является расширенным вариантом [block.raycast](libblock.md#raycast). Возвращает таблицу с результатами если луч касается блока, либо сущности.
 
-Соответственно это повлияет на наличие полей *entity* и *block*.
+Соответственно это повлияет на наличие полей *entity* и *block*.
+
+Для более тонкой настройки используйте `world.raycast(...)`.

doc/ru/scripting/builtins/libworld.md

@@ -69,4 +69,44 @@ world.save_chunk_data(
     -- сжатые данные чанка
     data: Bytearray
 )
-```
+
+-- Бросает луч из точки start в направлении dir.
+world.raycast(
+    params: table {
+        [==[ обязательные параметры ]==]
+        -- стартовая точка
+        start: vec3,
+        -- вектор направления луча
+        dir: vec3,
+        -- максимальное расстояние
+        distance: number,
+
+        [==[ дополнительные параметры (сущности) ]==]
+        -- учитывать сущности
+        entities: bool = true,
+        -- uid игнорируемой сущности
+        ignore_uid: number = 0 (ENTITY_NONE),
+        -- id типов сущностей используемых для фильтрации
+        filter_entities: table<string|number> = nil,
+        -- исключающий режим фильтрации:
+        --   при значении (true) filter_entities определяет список игнорируемых
+        entities_exclusion: bool = false,
+        
+        [==[ дополнительные параметры (блоки) ]==]
+        -- id типов блоков используемых для фильтрации
+        filter_blocks: table<string|number> = nil,
+        -- исключающий режим фильтрации:
+        --   при значении (true) filter_blocks определяет список игнорируемых
+        blocks_exclusion: bool = true,
+        -- учитывать блоки с selectable=false
+        nonselect_blocks: bool = false;
+    }
+) -> {
+    block: int или nil, -- id блока
+    entity: int или nil, -- uid сущности
+    endpoint: vec3, -- точка касания луча
+    iendpoint: vec3, -- позиция блока, которого касается луч
+    length: number, -- длина луча
+    normal: vec3, -- вектор нормали поверхности, которой касается луч
+} или nil если луч не коснулся блока или сущности
+```