Lua API documentation: Various fixes (#12059)

Change 1: Clarify when on_step collision information is provided
Change 2: Document PostgreSQL and Redis settings
Change 3: Overall AreaStore documentation improvements including consistent parameter naming based on community suggestions

doc/lua_api.txt

@@ -6211,45 +6211,53 @@ Sorted alphabetically.
 `AreaStore`
 -----------
 
-A fast access data structure to store areas, and find areas near a given
+AreaStore is a data structure to calculate intersections of 3D cuboid volumes
-position or area.
+and points. The `data` field (string) may be used to store and retrieve any
-Every area has a `data` string attribute to store additional information.
+mod-relevant information to the specified area.
-You can create an empty `AreaStore` by calling `AreaStore()`, or
+
-`AreaStore(type_name)`. The mod decides where to save and load AreaStore.
+Despite its name, mods must take care of persisting AreaStore data. They may
-If you chose the parameter-less constructor, a fast implementation will be
+use the provided load and write functions for this.
-automatically chosen for you.
+
 
 ### Methods
 
-* `get_area(id, include_borders, include_data)`
+* `AreaStore(type_name)`
+    * Returns a new AreaStore instance
+    * `type_name`: optional, forces the internally used API.
+        * Possible values: `"LibSpatial"` (default).
+        * When other values are specified, or SpatialIndex is not available,
+          the custom Minetest functions are used.
+* `get_area(id, include_corners, include_data)`
     * Returns the area information about the specified ID.
     * Returned values are either of these:
 
             nil  -- Area not found
-            true -- Without `include_borders` and `include_data`
+            true -- Without `include_corners` and `include_data`
             {
-                min = pos, max = pos -- `include_borders == true`
+                min = pos, max = pos -- `include_corners == true`
                 data = string        -- `include_data == true`
             }
 
-* `get_areas_for_pos(pos, include_borders, include_data)`
+* `get_areas_for_pos(pos, include_corners, include_data)`
     * Returns all areas as table, indexed by the area ID.
     * Table values: see `get_area`.
-* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`
+* `get_areas_in_area(corner1, corner2, accept_overlap, include_corners, include_data)`
-    * Returns all areas that contain all nodes inside the area specified by `edge1`
+    * Returns all areas that contain all nodes inside the area specified by`
-      and `edge2` (inclusive).
+      `corner1 and `corner2` (inclusive).
     * `accept_overlap`: if `true`, areas are returned that have nodes in
       common (intersect) with the specified area.
     * Returns the same values as `get_areas_for_pos`.
-* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store.
+* `insert_area(corner1, corner2, data, [id])`: inserts an area into the store.
     * Returns the new area's ID, or nil if the insertion failed.
-    * The (inclusive) positions `edge1` and `edge2` describe the area.
+    * The (inclusive) positions `corner1` and `corner2` describe the area.
     * `data` is a string stored with the area.
     * `id` (optional): will be used as the internal area ID if it is an unique
       number between 0 and 2^32-2.
-* `reserve(count)`: reserves resources for at most `count` many contained
+* `reserve(count)`
-  areas.
+    * Requires SpatialIndex, no-op function otherwise.
-  Only needed for efficiency, and only some implementations profit.
+    * Reserves resources for `count` many contained areas to improve
+      efficiency when working with many area entries. Additional areas can still
+      be inserted afterwards at the usual complexity.
 * `remove_area(id)`: removes the area with the given id from the store, returns
   success.
 * `set_cache_params(params)`: sets params for the included prefiltering cache.
@@ -7362,7 +7370,7 @@ Used by `minetest.register_entity`.
         -- for more info) by using a '_' prefix
     }
 
-Collision info passed to `on_step`:
+Collision info passed to `on_step` (`moveresult` argument):
 
     {
         touching_ground = boolean,
@@ -7379,6 +7387,8 @@ Collision info passed to `on_step`:
             },
             ...
         }
+        -- `collisions` does not contain data of unloaded mapblock collisions
+        -- or when the velocity changes are negligibly small
     }
 
 ABM (ActiveBlockModifier) definition

doc/world_format.txt

@@ -129,9 +129,9 @@ Example content (added indentation and - explanations):
   backend = sqlite3             - which DB backend to use for blocks (sqlite3, dummy, leveldb, redis, postgresql)
   player_backend = sqlite3      - which DB backend to use for player data
   readonly_backend = sqlite3    - optionally readonly seed DB (DB file _must_ be located in "readonly" subfolder)
+  auth_backend = files          - which DB backend to use for authentication data
   server_announce = false       - whether the server is publicly announced or not
   load_mod_<mod> = false        - whether <mod> is to be loaded in this world
-  auth_backend = files          - which DB backend to use for authentication data
 
 For load_mod_<mod>, the possible values are:
 
@@ -145,6 +145,18 @@ For load_mod_<mod>, the possible values are:
     * Other locations and absolute paths are not supported
     * Note that `moddir` is the directory name, not the mod name specified in mod.conf.
 
+PostgreSQL backend specific settings:
+  pgsql_connection = host=127.0.0.1 port=5432 user=mt_user password=mt_password dbname=minetest
+  pgsql_player_connection = (same parameters as above)
+  pgsql_readonly_connection = (same parameters as above)
+  pgsql_auth_connection = (same parameters as above)
+
+Redis backend specific settings:
+  redis_address = 127.0.0.1  - Redis server address
+  redis_hash = foo           - Database hash
+  redis_port = 6379          - (optional) connection port
+  redis_password = hunter2   - (optional) server password
+
 
 Player File Format
 ===================

src/script/lua_api/l_areastore.cpp

@@ -27,26 +27,26 @@ with this program; if not, write to the Free Software Foundation, Inc.,
 #include "filesys.h"
 #include <fstream>
 
-static inline void get_data_and_border_flags(lua_State *L, u8 start_i,
+static inline void get_data_and_corner_flags(lua_State *L, u8 start_i,
-		bool *borders, bool *data)
+		bool *corners, bool *data)
 {
 	if (!lua_isboolean(L, start_i))
 		return;
-	*borders = lua_toboolean(L, start_i);
+	*corners = lua_toboolean(L, start_i);
 	if (!lua_isboolean(L, start_i + 1))
 		return;
 	*data = lua_toboolean(L, start_i + 1);
 }
 
 static void push_area(lua_State *L, const Area *a,
-		bool include_borders, bool include_data)
+		bool include_corners, bool include_data)
 {
-	if (!include_borders && !include_data) {
+	if (!include_corners && !include_data) {
 		lua_pushboolean(L, true);
 		return;
 	}
 	lua_newtable(L);
-	if (include_borders) {
+	if (include_corners) {
 		push_v3s16(L, a->minedge);
 		lua_setfield(L, -2, "min");
 		push_v3s16(L, a->maxedge);
@@ -59,13 +59,13 @@ static void push_area(lua_State *L, const Area *a,
 }
 
 static inline void push_areas(lua_State *L, const std::vector<Area *> &areas,
-		bool borders, bool data)
+		bool corners, bool data)
 {
 	lua_newtable(L);
 	size_t cnt = areas.size();
 	for (size_t i = 0; i < cnt; i++) {
 		lua_pushnumber(L, areas[i]->id);
-		push_area(L, areas[i], borders, data);
+		push_area(L, areas[i], corners, data);
 		lua_settable(L, -3);
 	}
 }
@@ -94,7 +94,7 @@ int LuaAreaStore::gc_object(lua_State *L)
 	return 0;
 }
 
-// get_area(id, include_borders, include_data)
+// get_area(id, include_corners, include_data)
 int LuaAreaStore::l_get_area(lua_State *L)
 {
 	NO_MAP_LOCK_REQUIRED;
@@ -104,9 +104,9 @@ int LuaAreaStore::l_get_area(lua_State *L)
 
 	u32 id = luaL_checknumber(L, 2);
 
-	bool include_borders = true;
+	bool include_corners = true;
 	bool include_data = false;
-	get_data_and_border_flags(L, 3, &include_borders, &include_data);
+	get_data_and_corner_flags(L, 3, &include_corners, &include_data);
 
 	const Area *res;
 
@@ -114,12 +114,12 @@ int LuaAreaStore::l_get_area(lua_State *L)
 	if (!res)
 		return 0;
 
-	push_area(L, res, include_borders, include_data);
+	push_area(L, res, include_corners, include_data);
 
 	return 1;
 }
 
-// get_areas_for_pos(pos, include_borders, include_data)
+// get_areas_for_pos(pos, include_corners, include_data)
 int LuaAreaStore::l_get_areas_for_pos(lua_State *L)
 {
 	NO_MAP_LOCK_REQUIRED;
@@ -129,19 +129,19 @@ int LuaAreaStore::l_get_areas_for_pos(lua_State *L)
 
 	v3s16 pos = check_v3s16(L, 2);
 
-	bool include_borders = true;
+	bool include_corners = true;
 	bool include_data = false;
-	get_data_and_border_flags(L, 3, &include_borders, &include_data);
+	get_data_and_corner_flags(L, 3, &include_corners, &include_data);
 
 	std::vector<Area *> res;
 
 	ast->getAreasForPos(&res, pos);
-	push_areas(L, res, include_borders, include_data);
+	push_areas(L, res, include_corners, include_data);
 
 	return 1;
 }
 
-// get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)
+// get_areas_in_area(corner1, corner2, accept_overlap, include_corners, include_data)
 int LuaAreaStore::l_get_areas_in_area(lua_State *L)
 {
 	NO_MAP_LOCK_REQUIRED;
@@ -149,25 +149,26 @@ int LuaAreaStore::l_get_areas_in_area(lua_State *L)
 	LuaAreaStore *o = checkobject(L, 1);
 	AreaStore *ast = o->as;
 
-	v3s16 minedge = check_v3s16(L, 2);
+	v3s16 minp = check_v3s16(L, 2);
-	v3s16 maxedge = check_v3s16(L, 3);
+	v3s16 maxp = check_v3s16(L, 3);
+	sortBoxVerticies(minp, maxp);
 
-	bool include_borders = true;
+	bool include_corners = true;
 	bool include_data = false;
 	bool accept_overlap = false;
 	if (lua_isboolean(L, 4)) {
 		accept_overlap = readParam<bool>(L, 4);
-		get_data_and_border_flags(L, 5, &include_borders, &include_data);
+		get_data_and_corner_flags(L, 5, &include_corners, &include_data);
 	}
 	std::vector<Area *> res;
 
-	ast->getAreasInArea(&res, minedge, maxedge, accept_overlap);
+	ast->getAreasInArea(&res, minp, maxp, accept_overlap);
-	push_areas(L, res, include_borders, include_data);
+	push_areas(L, res, include_corners, include_data);
 
 	return 1;
 }
 
-// insert_area(edge1, edge2, data, id)
+// insert_area(corner1, corner2, data, id)
 int LuaAreaStore::l_insert_area(lua_State *L)
 {
 	NO_MAP_LOCK_REQUIRED;