From e97cbcf34d6f50483a1097ad74d8a661d9433afb Mon Sep 17 00:00:00 2001 From: SmallJoker Date: Sun, 8 Sep 2019 18:43:49 +0200 Subject: [PATCH] Lua API documentation: Various fixes (#8914) Remove unusable 'minetest.setting_*' from client_lua_api.txt lua_api.txt: - Define the 'mod.conf' format - More precise 'settingtypes.txt' format reference - Document special sound files 'player_*damage' - Group, sort and add 'not_in_creative_inventory' special group - Define the 'Settings' format - Warning about incorrect byte saving in 'StorageRef' - Note about non-persistent player definitions fields - Better 'leveldiff' and 'level' group description --- doc/client_lua_api.txt | 3 -- doc/lua_api.txt | 97 ++++++++++++++++++++++++++++++++---------- 2 files changed, 75 insertions(+), 25 deletions(-) diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index 2c670645f..4bb53f403 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -111,9 +111,6 @@ The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on minetest calling the registered callbacks. -`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used -to read custom or existing settings at load time, if necessary. - ### `sounds` Media files (sounds) that will be transferred to the client and will be available for use by the mod. diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 76253300f..7fae20603 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -154,7 +154,7 @@ The location of this directory can be fetched by using ### mod.conf -A key-value store of mod details. +A `Settings` file that provides meta information about the mod. * `name`: The mod name. Allows Minetest to determine the mod name even if the folder is wrongly named. @@ -196,8 +196,9 @@ A file containing a description to be shown in the Mods tab of the main menu. ### `settingtypes.txt` -A file in the same format as the one in builtin. It will be parsed by the -settings menu and the settings will be displayed in the "Mods" category. +The format is documented in `builtin/settingtypes.txt`. +It is parsed by the main menu settings dialogue to list mod-specific +settings in the "Mods" category. ### `init.lua` @@ -856,6 +857,15 @@ A positional sound will only be heard by players that are within * e.g. `{name = "default_place_node", gain = 1.0, pitch = 1.0}` +Special sound files +------------------- + +These sound files are played back by the engine if provided. + + * `main_menu`: Looped sound in the main menu (gain = 1.0) + * `player_damage`: Played when the local player takes damage (gain = 0.5) + * `player_falling_damage`: Played when the local player takes + damage by falling (gain = 0.5) Registered definitions @@ -1537,36 +1547,59 @@ Another example: Make red wool from white wool and red dye: Special groups -------------- -* `immortal`: Skips all damage and breath handling for an object. This group - will also hide the integrated HUD status bars for players, and is - automatically set to all players when damage is disabled on the server. -* `punch_operable`: For entities; disables the regular damage mechanism for - players punching it by hand or a non-tool item, so that it can do something - else than take damage. -* `level`: Can be used to give an additional sense of progression in the game. - * A larger level will cause e.g. a weapon of a lower level make much less - damage, and get worn out much faster, or not be able to get drops - from destroyed nodes. - * `0` is something that is directly accessible at the start of gameplay - * There is no upper limit +The asterisk `(*)` after a group name describes that there is no engine +functionality bound to it, and implementation is left up as a suggestion +to games. + +### Node, item and tool groups + +* `not_in_creative_inventory`: (*) Special group for inventory mods to indicate + that the item should be hidden in item lists. + + +### Node-only groups + +* `attached_node`: if the node under it is not a walkable block the node will be + dropped as an item. If the node is wallmounted the wallmounted direction is + checked. +* `bouncy`: value is bounce speed in percent +* `connect_to_raillike`: makes nodes of raillike drawtype with same group value + connect to each other * `dig_immediate`: Player can always pick up node without reducing tool wear * `2`: the node always gets the digging time 0.5 seconds (rail, sign) * `3`: the node always gets the digging time 0 seconds (torch) * `disable_jump`: Player (and possibly other things) cannot jump from node * `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)` -* `bouncy`: value is bounce speed in percent * `falling_node`: if there is no walkable block under the node it will fall * `float`: the node will not fall through liquids -* `attached_node`: if the node under it is not a walkable block the node will be - dropped as an item. If the node is wallmounted the wallmounted direction is - checked. -* `connect_to_raillike`: makes nodes of raillike drawtype with same group value - connect to each other +* `level`: Can be used to give an additional sense of progression in the game. + * A larger level will cause e.g. a weapon of a lower level make much less + damage, and get worn out much faster, or not be able to get drops + from destroyed nodes. + * `0` is something that is directly accessible at the start of gameplay + * There is no upper limit + * See also: `leveldiff` in [Tools] * `slippery`: Players and items will slide on the node. Slipperiness rises steadily with `slippery` value, starting at 1. + + +### Tool-only groups + * `disable_repair`: If set to 1 for a tool, it cannot be repaired using the `"toolrepair"` crafting recipe + +### `ObjectRef` groups + +* `immortal`: Skips all damage and breath handling for an object. This group + will also hide the integrated HUD status bars for players, and is + automatically set to all players when damage is disabled on the server. +* `punch_operable`: For entities; disables the regular damage mechanism for + players punching it by hand or a non-tool item, so that it can do something + else than take damage. + + + Known damage and digging time defining groups --------------------------------------------- @@ -1656,6 +1689,8 @@ to implement this. Determines how many uses the tool has when it is used for digging a node, of this group, of the maximum level. For lower leveled nodes, the use count is multiplied by `3^leveldiff`. +`leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the +node's `level` group. The node cannot be dug if `leveldiff` is less than zero. * `uses=10, leveldiff=0`: actual uses: 10 * `uses=10, leveldiff=1`: actual uses: 30 @@ -5303,7 +5338,8 @@ Can be obtained via `item:get_meta()`. `MetaDataRef` ------------- -See [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], and [`PlayerMetaRef`]. +Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], +and [`PlayerMetaRef`]. ### Methods @@ -5828,12 +5864,26 @@ It can be created via `Settings(filename)`. * Writes changes to file. * `to_table()`: returns `{[key1]=value1,...}` +### Format + +The settings have the format `key = value`. Example: + + foo = example text + bar = """ + Multiline + value + """ + + `StorageRef` ------------ Mod metadata: per mod metadata, saved automatically. Can be obtained via `minetest.get_mod_storage()` during load time. +WARNING: This storage backend is incaptable to save raw binary data due +to restrictions of JSON. + ### Methods * All methods in MetaDataRef @@ -5848,6 +5898,9 @@ Object properties ----------------- Used by `ObjectRef` methods. Part of an Entity definition. +These properties are not persistent, but are applied automatically to the +corresponding Lua entity using the given registration fields. +Player properties need to be saved manually. { hp_max = 1, -- 2.25.1