Expose getPointedThing to Lua

This commit introduces Raycast, a Lua user object, which can be
used to perform a raycast on the map. The ray is continuable, so one can
also get hidden nodes (for example to see trough glass).

1 files changed, 26 insertions, 0 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 63d090ebe..56f8dbaae 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2557,6 +2557,12 @@ and `minetest.auth_reload` call the authetification handler.
     * `pos2`: Second position
     * `stepsize`: smaller gives more accurate results but requires more computing
       time. Default is `1`.
+* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast`
+    * Creates a `Raycast` object.
+    * `pos1`: start of the ray
+    * `pos2`: end of the ray
+    * `objects` : if false, only nodes will be returned. Default is `true`.
+    * `liquids' : if false, liquid nodes won't be returned. Default is `false`.
 * `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)`
     * returns table containing path
     * returns a table of 3D points representing a path from `pos1` to `pos2` or `nil`
@@ -3755,6 +3761,26 @@ It can be created via `Settings(filename)`.
     * Writes changes to file.
 * `to_table()`: returns `{[key1]=value1,...}`
 
+### `Raycast`
+A raycast on the map. It works with selection boxes.
+Can be used as an iterator in a for loop.
+
+The map is loaded as the ray advances. If the
+map is modified after the `Raycast` is created,
+the changes may or may not have an effect on
+the object.
+
+It can be created via `Raycast(pos1, pos2, objects, liquids)` or
+`minetest.raycast(pos1, pos2, objects, liquids)` where:
+    * `pos1`: start of the ray
+    * `pos2`: end of the ray
+    * `objects` : if false, only nodes will be returned. Default is true.
+    * `liquids' : if false, liquid nodes won't be returned. Default is false.
+
+#### Methods
+* `next()`: returns a `pointed_thing`
+    * Returns the next thing pointed by the ray or nil.
+
 Mapgen objects
 --------------
 A mapgen object is a construct used in map generation. Mapgen objects can be used