X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=59884621b66ef92b2346fe47a083de9e2999d699;hb=0bcc2f33ebe382a1dafbe6edaf00f476f2584b74;hp=ae0287c43d8d360a9282848c9fc36fcb5e377dab;hpb=6efb453cdb70c9cf5a8e382974542f29ef6ff893;p=dragonfireclient.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index ae0287c43..59884621b 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -53,7 +53,7 @@ Games are looked up from: where `gameid` is unique to each game. -The game directory contains the file `game.conf`, which contains these fields: +The game directory contains the file `game.conf`, which contains: name = @@ -61,6 +61,16 @@ e.g. name = Minetest +Optionally, game.conf can also contain: + + disallowed_mapgens = + +e.g. + + disallowed_mapgens = v5,v6,flat + +These mapgens are removed from the list of mapgens for the game. + The game directory can contain the file minetest.conf, which will be used to set default settings when running the particular game. It can also contain a settingtypes.txt in the same format as the one in builtin. @@ -2238,25 +2248,43 @@ The following functions provide escape sequences: Spatial Vectors --------------- -* `vector.new(a[, b, c])`: returns a vector: +For the following functions, `v`, `v1`, `v2` are vectors, `p1`, `p2` are positions: + +* `vector.new(a[, b, c])`: + * Returns a vector. * A copy of `a` if `a` is a vector. - * `{x = a, y = b, z = c}`, if all `a, b, c` are defined -* `vector.direction(p1, p2)`: returns a vector -* `vector.distance(p1, p2)`: returns a number -* `vector.length(v)`: returns a number -* `vector.normalize(v)`: returns a vector -* `vector.floor(v)`: returns a vector, each dimension rounded down -* `vector.round(v)`: returns a vector, each dimension rounded to nearest int -* `vector.apply(v, func)`: returns a vector -* `vector.equals(v1, v2)`: returns a boolean -* `vector.sort(v1, v2)`: returns minp, maxp vectors of the cuboid defined by v1 and v2 + * `{x = a, y = b, z = c}`, if all of `a`, `b`, `c` are defined numbers. +* `vector.direction(p1, p2)`: + * Returns a vector of length 1 with direction `p1` to `p2`. + * If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`. +* `vector.distance(p1, p2)`: + * Returns zero or a positive number, the distance between `p1` and `p2`. +* `vector.length(v)`: + * Returns zero or a positive number, the length of vector `v`. +* `vector.normalize(v)`: + * Returns a vector of length 1 with direction of vector `v`. + * If `v` has zero length, returns `{x = 0, y = 0, z = 0}`. +* `vector.floor(v)`: + * Returns a vector, each dimension rounded down. +* `vector.round(v)`: + * Returns a vector, each dimension rounded to nearest integer. +* `vector.apply(v, func)`: + * Returns a vector where the function `func` has been applied to each component. +* `vector.equals(v1, v2)`: + * Returns a boolean, `true` if the vectors are identical. +* `vector.sort(v1, v2)`: + * Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`. For the following functions `x` can be either a vector or a number: -* `vector.add(v, x)`: returns a vector -* `vector.subtract(v, x)`: returns a vector -* `vector.multiply(v, x)`: returns a scaled vector or Schur product -* `vector.divide(v, x)`: returns a scaled vector or Schur quotient +* `vector.add(v, x)`: + * Returns a vector. +* `vector.subtract(v, x)`: + * Returns a vector. +* `vector.multiply(v, x)`: + * Returns a scaled vector or Schur product. +* `vector.divide(v, x)`: + * Returns a scaled vector or Schur quotient. Helper functions ---------------- @@ -2382,7 +2410,7 @@ Strings that need to be translated can contain several escapes, preceded by `@`. when translation. Due to how translations are implemented, the original translation string **must** have its arguments in increasing order, without gaps or repetitions, starting from 1. * `@=` acts as a literal `=`. It is not required in strings given to `minetest.translate`, but is in translation - files to avoid begin confused with the `=` separating the original from the translation. + files to avoid being confused with the `=` separating the original from the translation. * `@\n` (where the `\n` is a literal newline) acts as a literal newline. As with `@=`, this escape is not required in strings given to `minetest.translate`, but is in translation files. * `@n` acts as a literal newline as well. @@ -2643,8 +2671,9 @@ Call these functions only at load time! * Note that the above two callbacks will be called twice if a player is responsible - once with the player name, and then with a nil player name. * Return true in the above callbacks to stop register_on_priv_grant or revoke being called. -* `minetest.register_authentication_handler(handler)` - * See `minetest.builtin_auth_handler` in `builtin.lua` for reference +* `minetest.register_authentication_handler(authentication handler definition)` + * Registers an auth handler that overrides the builtin one + * This function can be called by a single mod once only. ### Setting-related * `minetest.settings`: Settings object containing all of the settings from the @@ -2653,37 +2682,44 @@ Call these functions only at load time! parses it as a position (in the format `(1,2,3)`). Returns a position or nil. ### Authentication -* `minetest.notify_authentication_modified(name)` - * Should be called by the authentication handler if privileges changes. - * `name`: string, if omitted, everybody is reported -* `minetest.check_password_entry(name, entry, password)` - * Returns true if the "db entry" for a player with name matches given - * password, false otherwise. - * The "db entry" is the usually player-individual value that is derived - * from the player's chosen password and stored on the server in order to allow - * authentication whenever the player desires to log in. - * Only use this function for making it possible to log in via the password from - * via protocols like IRC, other uses for inside the game are frowned upon. -* `minetest.get_password_hash(name, raw_password)` - * Convert a name-password pair to a password hash that Minetest can use. - * The returned value alone is not a good basis for password checks based - * on comparing the password hash in the database with the password hash - * from the function, with an externally provided password, as the hash - * in the db might use the new SRP verifier format. - * For this purpose, use `minetest.check_password_entry` instead. * `minetest.string_to_privs(str)`: returns `{priv1=true,...}` * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."` * Convert between two privilege representations -* `minetest.set_player_password(name, password_hash)` -* `minetest.set_player_privs(name, {priv1=true,...})` * `minetest.get_player_privs(name) -> {priv1=true,...}` -* `minetest.auth_reload()` * `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs` * A quickhand for checking privileges. * `player_or_name`: Either a Player object or the name of a player. * `...` is either a list of strings, e.g. `"priva", "privb"` or a table, e.g. `{ priva = true, privb = true }`. -* `minetest.get_player_ip(name)`: returns an IP address string + +* `minetest.check_password_entry(name, entry, password)` + * Returns true if the "password entry" for a player with name matches given + password, false otherwise. + * The "password entry" is the password representation generated by the engine + as returned as part of a `get_auth()` call on the auth handler. + * Only use this function for making it possible to log in via password from + external protocols such as IRC, other uses are frowned upon. +* `minetest.get_password_hash(name, raw_password)` + * Convert a name-password pair to a password hash that Minetest can use. + * The returned value alone is not a good basis for password checks based + on comparing the password hash in the database with the password hash + from the function, with an externally provided password, as the hash + in the db might use the new SRP verifier format. + * For this purpose, use `minetest.check_password_entry` instead. +* `minetest.get_player_ip(name)`: returns an IP address string for the player `name` + * The player needs to be online for this to be successful. + +* `minetest.get_auth_handler()`: Return the currently active auth handler + * See the `Authentication handler definition` + * Use this to e.g. get the authentication data for a player: + `local auth_data = minetest.get_auth_handler().get_auth(playername)` +* `minetest.notify_authentication_modified(name)` + * Must be called by the authentication handler for privilege changes. + * `name`: string; if omitted, all auth data should be considered modified +* `minetest.set_player_password(name, password_hash)`: Set password hash of player `name` +* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player `name` +* `minetest.auth_reload()` + * See `reload()` in authentication handler definition `minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs` and `minetest.auth_reload` call the authentication handler. @@ -2840,13 +2876,12 @@ and `minetest.auth_reload` call the authentication handler. * parameter was absent) * `minetest.delete_area(pos1, pos2)` * delete all mapblocks in the area from pos1 to pos2, inclusive -* `minetest.line_of_sight(pos1, pos2, stepsize)`: returns `boolean, pos` - * Check if there is a direct line of sight between `pos1` and `pos2` +* `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos` + * Checks if there is anything other than air between pos1 and pos2. + * Returns false if something is blocking the sight. * Returns the position of the blocking node when `false` * `pos1`: First position * `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 @@ -3116,8 +3151,11 @@ These functions return the leftover itemstack. * `minetest.get_server_status()`: returns server status string * `minetest.get_server_uptime()`: returns the server uptime in seconds * `minetest.remove_player(name)`: remove player from database (if he is not connected). - * Does not remove player authentication data, minetest.player_exists will continue to return true. + * As auth data is not removed, minetest.player_exists will continue to return true. + Call the below method as well if you want to remove auth data too. * Returns a code (0: successful, 1: no such player, 2: player is connected) +* `minetest.remove_player_auth(name)`: remove player authentication data + * Returns boolean indicating success (false if player nonexistant) ### Bans * `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`) @@ -4110,7 +4148,9 @@ It can be created via `Settings(filename)`. #### Methods * `get(key)`: returns a value -* `get_bool(key)`: returns a boolean +* `get_bool(key, [default])`: returns a boolean + * `default` is the value returned if `key` is not found. + * Returns `nil` if `key` is not found and `default` not specified. * `get_np_group(key)`: returns a NoiseParams table * `set(key, value)` * Setting names can't contain whitespace or any of `="{}#`. @@ -4311,8 +4351,13 @@ Definition tables -- ^ For players: Defaults to `minetest.PLAYER_MAX_HP_DEFAULT` breath_max = 0, -- ^ For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT` - can_zoom = true, - -- ^ For players only. Enables the zoom feature. Defaults to true + zoom_fov = 0.0, + -- ^ For players only. Zoom FOV in degrees. + -- Note that zoom loads and/or generates world beyond the server's maximum + -- send and generate distances, so acts like a telescope. + -- Smaller zoomFOV values increase the distance loaded and/or generated. + -- Defaults to 15 in creative mode, 0 in survival mode. + -- zoom_fov = 0 disables zooming for the player. eye_height = 1.625, -- ^ For players only. Camera height above feet position in nodes. Defaults to 1.625 physical = true, @@ -4694,6 +4739,13 @@ Definition tables ^ interval. Default: nil. ^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]] + preserve_metadata = func(pos, oldnode, oldmeta, drops) --[[ + ^ Called when oldnode is about be converted to an item, but before the + node is deleted from the world or the drops are added. This is generally + the result of either the node being dug or an attached node becoming detached. + ^ drops is a table of ItemStacks, so any metadata to be preserved can be + added directly to one or more of the dropped items. See "ItemStackMetaRef". + ^ default: nil ]] after_place_node = func(pos, placer, itemstack, pointed_thing) --[[ ^ Called after constructing node when node was placed using minetest.item_place_node / minetest.place_node @@ -5202,3 +5254,30 @@ Definition tables -- ^ HTTP status code data = "response" } + +### Authentication handler definition + + { + get_auth = func(name), + -- ^ Get authentication data for existing player `name` (`nil` if player doesn't exist) + -- ^ returns following structure `{password=, privileges=, last_login=}` + create_auth = func(name, password), + -- ^ Create new auth data for player `name` + -- ^ Note that `password` is not plain-text but an arbitrary representation decided by the engine + delete_auth = func(name), + -- ^ Delete auth data of player `name`, returns boolean indicating success (false if player nonexistant) + set_password = func(name, password), + -- ^ Set password of player `name` to `password` + Auth data should be created if not present + set_privileges = func(name, privileges), + -- ^ Set privileges of player `name` + -- ^ `privileges` is in table form, auth data should be created if not present + reload = func(), + -- ^ Reload authentication data from the storage location + -- ^ Returns boolean indicating success + record_login = func(name), + -- ^ Called when player joins, used for keeping track of last_login + iterate = func(), + -- ^ Returns an iterator (use with `for` loops) for all player names currently in the auth database + } +