From f7311e0d97cb89bcb197a3e6b89e039151bb510f Mon Sep 17 00:00:00 2001 From: SmallJoker Date: Wed, 23 Feb 2022 21:21:37 +0100 Subject: [PATCH] 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 | 50 ++++++++++++++++++------------ doc/world_format.txt | 14 ++++++++- src/script/lua_api/l_areastore.cpp | 49 +++++++++++++++-------------- 3 files changed, 68 insertions(+), 45 deletions(-) diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 543f00542..571ddf40e 100644 --- a/doc/lua_api.txt +++ b/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 -position or area. -Every area has a `data` string attribute to store additional information. -You can create an empty `AreaStore` by calling `AreaStore()`, or -`AreaStore(type_name)`. The mod decides where to save and load AreaStore. -If you chose the parameter-less constructor, a fast implementation will be -automatically chosen for you. +AreaStore is a data structure to calculate intersections of 3D cuboid volumes +and points. The `data` field (string) may be used to store and retrieve any +mod-relevant information to the specified area. + +Despite its name, mods must take care of persisting AreaStore data. They may +use the provided load and write functions for this. + ### 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)` - * Returns all areas that contain all nodes inside the area specified by `edge1` - and `edge2` (inclusive). +* `get_areas_in_area(corner1, corner2, accept_overlap, include_corners, include_data)` + * Returns all areas that contain all nodes inside the area specified by` + `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 - areas. - Only needed for efficiency, and only some implementations profit. +* `reserve(count)` + * Requires SpatialIndex, no-op function otherwise. + * 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 diff --git a/doc/world_format.txt b/doc/world_format.txt index 3035c4efb..17923df8e 100644 --- a/doc/world_format.txt +++ b/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_ = false - whether is to be loaded in this world - auth_backend = files - which DB backend to use for authentication data For load_mod_, the possible values are: @@ -145,6 +145,18 @@ For load_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 =================== diff --git a/src/script/lua_api/l_areastore.cpp b/src/script/lua_api/l_areastore.cpp index 45724e604..ec2656c4a 100644 --- a/src/script/lua_api/l_areastore.cpp +++ b/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 -static inline void get_data_and_border_flags(lua_State *L, u8 start_i, - bool *borders, bool *data) +static inline void get_data_and_corner_flags(lua_State *L, u8 start_i, + 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 &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 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 maxedge = check_v3s16(L, 3); + v3s16 minp = check_v3s16(L, 2); + 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(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 res; - ast->getAreasInArea(&res, minedge, maxedge, accept_overlap); - push_areas(L, res, include_borders, include_data); + ast->getAreasInArea(&res, minp, maxp, accept_overlap); + 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;