mirror of
https://github.com/minetest/minetest.git
synced 2024-11-27 10:03:45 +01:00
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
This commit is contained in:
parent
633e23bd65
commit
f7311e0d97
@ -6211,45 +6211,53 @@ Sorted alphabetically.
|
|||||||
`AreaStore`
|
`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
|
### 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.
|
* Returns the area information about the specified ID.
|
||||||
* Returned values are either of these:
|
* Returned values are either of these:
|
||||||
|
|
||||||
nil -- Area not found
|
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`
|
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.
|
* Returns all areas as table, indexed by the area ID.
|
||||||
* Table values: see `get_area`.
|
* 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
|
* `accept_overlap`: if `true`, areas are returned that have nodes in
|
||||||
common (intersect) with the specified area.
|
common (intersect) with the specified area.
|
||||||
* Returns the same values as `get_areas_for_pos`.
|
* 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.
|
* 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.
|
* `data` is a string stored with the area.
|
||||||
* `id` (optional): will be used as the internal area ID if it is an unique
|
* `id` (optional): will be used as the internal area ID if it is an unique
|
||||||
number between 0 and 2^32-2.
|
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
|
* `remove_area(id)`: removes the area with the given id from the store, returns
|
||||||
success.
|
success.
|
||||||
* `set_cache_params(params)`: sets params for the included prefiltering cache.
|
* `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
|
-- for more info) by using a '_' prefix
|
||||||
}
|
}
|
||||||
|
|
||||||
Collision info passed to `on_step`:
|
Collision info passed to `on_step` (`moveresult` argument):
|
||||||
|
|
||||||
{
|
{
|
||||||
touching_ground = boolean,
|
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
|
ABM (ActiveBlockModifier) definition
|
||||||
|
@ -129,9 +129,9 @@ Example content (added indentation and - explanations):
|
|||||||
backend = sqlite3 - which DB backend to use for blocks (sqlite3, dummy, leveldb, redis, postgresql)
|
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
|
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)
|
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
|
server_announce = false - whether the server is publicly announced or not
|
||||||
load_mod_<mod> = false - whether <mod> is to be loaded in this world
|
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:
|
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
|
* Other locations and absolute paths are not supported
|
||||||
* Note that `moddir` is the directory name, not the mod name specified in mod.conf.
|
* 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
|
Player File Format
|
||||||
===================
|
===================
|
||||||
|
@ -27,26 +27,26 @@ with this program; if not, write to the Free Software Foundation, Inc.,
|
|||||||
#include "filesys.h"
|
#include "filesys.h"
|
||||||
#include <fstream>
|
#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))
|
if (!lua_isboolean(L, start_i))
|
||||||
return;
|
return;
|
||||||
*borders = lua_toboolean(L, start_i);
|
*corners = lua_toboolean(L, start_i);
|
||||||
if (!lua_isboolean(L, start_i + 1))
|
if (!lua_isboolean(L, start_i + 1))
|
||||||
return;
|
return;
|
||||||
*data = lua_toboolean(L, start_i + 1);
|
*data = lua_toboolean(L, start_i + 1);
|
||||||
}
|
}
|
||||||
|
|
||||||
static void push_area(lua_State *L, const Area *a,
|
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);
|
lua_pushboolean(L, true);
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
lua_newtable(L);
|
lua_newtable(L);
|
||||||
if (include_borders) {
|
if (include_corners) {
|
||||||
push_v3s16(L, a->minedge);
|
push_v3s16(L, a->minedge);
|
||||||
lua_setfield(L, -2, "min");
|
lua_setfield(L, -2, "min");
|
||||||
push_v3s16(L, a->maxedge);
|
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,
|
static inline void push_areas(lua_State *L, const std::vector<Area *> &areas,
|
||||||
bool borders, bool data)
|
bool corners, bool data)
|
||||||
{
|
{
|
||||||
lua_newtable(L);
|
lua_newtable(L);
|
||||||
size_t cnt = areas.size();
|
size_t cnt = areas.size();
|
||||||
for (size_t i = 0; i < cnt; i++) {
|
for (size_t i = 0; i < cnt; i++) {
|
||||||
lua_pushnumber(L, areas[i]->id);
|
lua_pushnumber(L, areas[i]->id);
|
||||||
push_area(L, areas[i], borders, data);
|
push_area(L, areas[i], corners, data);
|
||||||
lua_settable(L, -3);
|
lua_settable(L, -3);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@ -94,7 +94,7 @@ int LuaAreaStore::gc_object(lua_State *L)
|
|||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
// get_area(id, include_borders, include_data)
|
// get_area(id, include_corners, include_data)
|
||||||
int LuaAreaStore::l_get_area(lua_State *L)
|
int LuaAreaStore::l_get_area(lua_State *L)
|
||||||
{
|
{
|
||||||
NO_MAP_LOCK_REQUIRED;
|
NO_MAP_LOCK_REQUIRED;
|
||||||
@ -104,9 +104,9 @@ int LuaAreaStore::l_get_area(lua_State *L)
|
|||||||
|
|
||||||
u32 id = luaL_checknumber(L, 2);
|
u32 id = luaL_checknumber(L, 2);
|
||||||
|
|
||||||
bool include_borders = true;
|
bool include_corners = true;
|
||||||
bool include_data = false;
|
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;
|
const Area *res;
|
||||||
|
|
||||||
@ -114,12 +114,12 @@ int LuaAreaStore::l_get_area(lua_State *L)
|
|||||||
if (!res)
|
if (!res)
|
||||||
return 0;
|
return 0;
|
||||||
|
|
||||||
push_area(L, res, include_borders, include_data);
|
push_area(L, res, include_corners, include_data);
|
||||||
|
|
||||||
return 1;
|
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)
|
int LuaAreaStore::l_get_areas_for_pos(lua_State *L)
|
||||||
{
|
{
|
||||||
NO_MAP_LOCK_REQUIRED;
|
NO_MAP_LOCK_REQUIRED;
|
||||||
@ -129,19 +129,19 @@ int LuaAreaStore::l_get_areas_for_pos(lua_State *L)
|
|||||||
|
|
||||||
v3s16 pos = check_v3s16(L, 2);
|
v3s16 pos = check_v3s16(L, 2);
|
||||||
|
|
||||||
bool include_borders = true;
|
bool include_corners = true;
|
||||||
bool include_data = false;
|
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;
|
std::vector<Area *> res;
|
||||||
|
|
||||||
ast->getAreasForPos(&res, pos);
|
ast->getAreasForPos(&res, pos);
|
||||||
push_areas(L, res, include_borders, include_data);
|
push_areas(L, res, include_corners, include_data);
|
||||||
|
|
||||||
return 1;
|
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)
|
int LuaAreaStore::l_get_areas_in_area(lua_State *L)
|
||||||
{
|
{
|
||||||
NO_MAP_LOCK_REQUIRED;
|
NO_MAP_LOCK_REQUIRED;
|
||||||
@ -149,25 +149,26 @@ int LuaAreaStore::l_get_areas_in_area(lua_State *L)
|
|||||||
LuaAreaStore *o = checkobject(L, 1);
|
LuaAreaStore *o = checkobject(L, 1);
|
||||||
AreaStore *ast = o->as;
|
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 include_data = false;
|
||||||
bool accept_overlap = false;
|
bool accept_overlap = false;
|
||||||
if (lua_isboolean(L, 4)) {
|
if (lua_isboolean(L, 4)) {
|
||||||
accept_overlap = readParam<bool>(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;
|
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;
|
return 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
// insert_area(edge1, edge2, data, id)
|
// insert_area(corner1, corner2, data, id)
|
||||||
int LuaAreaStore::l_insert_area(lua_State *L)
|
int LuaAreaStore::l_insert_area(lua_State *L)
|
||||||
{
|
{
|
||||||
NO_MAP_LOCK_REQUIRED;
|
NO_MAP_LOCK_REQUIRED;
|
||||||
|
Loading…
Reference in New Issue
Block a user