aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Ouellette <oue.paul18@gmail.com>2018-12-11 11:37:06 -0500
committerLoïc Blot <nerzhul@users.noreply.github.com>2018-12-11 17:37:06 +0100
commitce32a327ff6e4e6810a9377e67eaeb47940b7c4c (patch)
tree4698b4e475f6519a2f415d4784499754f8176b77
parenta8575295d5f577b245b932bac118ef077ea96c08 (diff)
downloadminetest-ce32a327ff6e4e6810a9377e67eaeb47940b7c4c.tar.gz
minetest-ce32a327ff6e4e6810a9377e67eaeb47940b7c4c.tar.bz2
minetest-ce32a327ff6e4e6810a9377e67eaeb47940b7c4c.zip
lua_api.txt: Various fixes and improvements (#7945)
* Add missing tables of registered things * Eliminate some duplication Registration functions in 'Registered definitions' section merged into 'Registration functions' section. * Misc. fixes * Add privilege definition table * Remove not-special soil group from special groups * Merge two registration functions sections * Move 'added to' information to tables section Also fix some capitalization and missing periods * Minor fixes * Split Registration functions into two subsections And update Registered definition tables to match order * Fixes
-rw-r--r--doc/lua_api.txt250
1 files changed, 131 insertions, 119 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index dc87eee0e..e845d8f2c 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -859,74 +859,19 @@ one player using `to_player = name,`
Registered definitions
======================
-Anything added using certain `minetest.register_*` functions gets added to
-the global `minetest.registered_*` tables.
-
-* `minetest.register_entity(name, entity definition)`
- * added to `minetest.registered_entities[name]`
-
-* `minetest.register_node(name, node definition)`
- * added to `minetest.registered_items[name]`
- * added to `minetest.registered_nodes[name]`
-
-* `minetest.register_tool(name, item definition)`
- * added to `minetest.registered_items[name]`
-
-* `minetest.register_craftitem(name, item definition)`
- * added to `minetest.registered_items[name]`
-
-* `minetest.unregister_item(name)`
- * Unregisters the item name from engine, and deletes the entry with key
- `name` from `minetest.registered_items` and from the associated item
- table according to its nature: `minetest.registered_nodes[]` etc
-
-* `minetest.register_biome(biome definition)`
- * returns an integer uniquely identifying the registered biome
- * added to `minetest.registered_biome` with the key of `biome.name`
- * if `biome.name` is nil, the key is the returned ID
-
-* `minetest.unregister_biome(name)`
- * Unregisters the biome name from engine, and deletes the entry with key
- `name` from `minetest.registered_biome`
-
-* `minetest.register_ore(ore definition)`
- * returns an integer uniquely identifying the registered ore
- * added to `minetest.registered_ores` with the key of `ore.name`
- * if `ore.name` is nil, the key is the returned ID
-
-* `minetest.register_decoration(decoration definition)`
- * returns an integer uniquely identifying the registered decoration
- * added to `minetest.registered_decorations` with the key of
- `decoration.name`.
- * if `decoration.name` is nil, the key is the returned ID
-
-* `minetest.register_schematic(schematic definition)`
- * returns an integer uniquely identifying the registered schematic
- * added to `minetest.registered_schematic` with the key of `schematic.name`
- * if `schematic.name` is nil, the key is the returned ID
- * if the schematic is loaded from a file, schematic.name is set to the
- filename.
- * if the function is called when loading the mod, and schematic.name is a
- relative path, then the current mod path will be prepended to the
- schematic filename.
-
-* `minetest.clear_registered_biomes()`
- * clears all biomes currently registered
-
-* `minetest.clear_registered_ores()`
- * clears all ores currently registered
-
-* `minetest.clear_registered_decorations()`
- * clears all decorations currently registered
-
-* `minetest.clear_registered_schematics()`
- * clears all schematics currently registered
+Anything added using certain [Registration functions] gets added to one or more
+of the global [Registered definition tables].
Note that in some cases you will stumble upon things that are not contained
in these tables (e.g. when a mod has been removed). Always check for
existence before trying to access the fields.
-Example: If you want to check the drawtype of a node, you could do:
+Example:
+
+All nodes register with `minetest.register_node` get added to the table
+`minetest.registered_nodes`.
+
+If you want to check the drawtype of a node, you could do:
local function get_nodedef_field(nodename, fieldname)
if not minetest.registered_nodes[nodename] then
@@ -1248,6 +1193,7 @@ Below are the specific uses for fields in each type; fields not listed for that
type are ignored.
### `image`
+
Displays an image on the HUD.
* `scale`: The scale of the image, with 1 being the original texture size.
@@ -1321,6 +1267,7 @@ For helper functions see [Spatial Vectors].
* `{type="object", ref=ObjectRef}`
Exact pointing location (currently only `Raycast` supports these fields):
+
* `pointed_thing.intersection_point`: The absolute world coordinates of the
point on the selection box which is pointed at. May be in the selection box
if the pointer is in the box too.
@@ -1546,7 +1493,6 @@ Special 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.
-* `soil`: saplings will grow on nodes in this group
* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
connect to each other
* `slippery`: Players and items will slide on the node.
@@ -1554,7 +1500,6 @@ Special groups
* `disable_repair`: If set to 1 for a tool, it cannot be repaired using the
`"toolrepair"` crafting recipe
-
Known damage and digging time defining groups
---------------------------------------------
@@ -1985,6 +1930,7 @@ Elements
* `<fontcolor>` tooltip font color as `ColorString` (optional)
### `tooltip[<X>,<Y>;<W>,<H>;<tooltip_text>;<bgcolor>;<fontcolor>]`
+
* Adds tooltip for an area. Other tooltips will take priority when present.
* `<bgcolor>` tooltip background color as `ColorString` (optional)
* `<fontcolor>` tooltip font color as `ColorString` (optional)
@@ -2097,9 +2043,9 @@ Elements
### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
-* `item name` is the registered name of an item/node,
- tooltip will be made out of its description
- to override it use tooltip element
+* `item name` is the registered name of an item/node
+* The item description will be used as the tooltip. This can be overridden with
+ a tooltip element.
### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
@@ -3020,7 +2966,6 @@ to be a table retrieved from `get_data()`.
Once the internal VoxelManip state has been modified to your liking, the
changes can be committed back to the map by calling `VoxelManip:write_to_map()`
-
### Flat array format
Let
@@ -3536,17 +3481,56 @@ Registration functions
Call these functions only at load time!
-* `minetest.register_entity(name, entity definition)`
-* `minetest.register_abm(abm definition)`
-* `minetest.register_lbm(lbm definition)`
+### Environment
+
* `minetest.register_node(name, node definition)`
-* `minetest.register_tool(name, item definition)`
* `minetest.register_craftitem(name, item definition)`
+* `minetest.register_tool(name, item definition)`
+* `minetest.override_item(name, redefinition)`
+ * Overrides fields of an item registered with register_node/tool/craftitem.
+ * Note: Item must already be defined, (opt)depend on the mod defining it.
+ * Example: `minetest.override_item("default:mese",
+ {light_source=minetest.LIGHT_MAX})`
* `minetest.unregister_item(name)`
+ * Unregisters the item from the engine, and deletes the entry with key
+ `name` from `minetest.registered_items` and from the associated item table
+ according to its nature: `minetest.registered_nodes`, etc.
+* `minetest.register_entity(name, entity definition)`
+* `minetest.register_abm(abm definition)`
+* `minetest.register_lbm(lbm definition)`
* `minetest.register_alias(name, convert_to)`
* Also use this to set the 'mapgen aliases' needed in a game for the core
- * mapgens. See [Mapgen aliases] section above.
+ mapgens. See [Mapgen aliases] section above.
* `minetest.register_alias_force(name, convert_to)`
+* `minetest.register_ore(ore definition)`
+ * Returns an integer uniquely identifying the registered ore on success.
+* `minetest.register_biome(biome definition)`
+ * Returns an integer uniquely identifying the registered biome on success.
+* `minetest.unregister_biome(name)`
+ * Unregisters the biome from the engine, and deletes the entry with key
+ `name` from `minetest.registered_biomes`.
+* `minetest.register_decoration(decoration definition)`
+ * Returns an integer uniquely identifying the registered decoration on
+ success.
+* `minetest.register_schematic(schematic definition)`
+ * Returns an integer uniquely identifying the registered schematic on
+ success.
+ * If the schematic is loaded from a file, the `name` field is set to the
+ filename.
+ * If the function is called when loading the mod, and `name` is a relative
+ path, then the current mod path will be prepended to the schematic
+ filename.
+* `minetest.clear_registered_ores()`
+ * Clears all ores currently registered.
+* `minetest.clear_registered_biomes()`
+ * Clears all biomes currently registered.
+* `minetest.clear_registered_decorations()`
+ * Clears all decorations currently registered.
+* `minetest.clear_registered_schematics()`
+ * Clears all schematics currently registered.
+
+### Gameplay
+
* `minetest.register_craft(recipe)`
* Check recipe table syntax for different types below.
* `minetest.clear_craft(recipe)`
@@ -3559,16 +3543,21 @@ Call these functions only at load time!
* **Warning**! The type field ("shaped", "cooking" or any other) will be
ignored if the recipe contains output. Erasing is then done independently
from the crafting method.
-* `minetest.register_ore(ore definition)`
-* `minetest.register_biome(biome definition)`
-* `minetest.register_decoration(decoration definition)`
-* `minetest.override_item(name, redefinition)`
- * Overrides fields of an item registered with register_node/tool/craftitem.
- * Note: Item must already be defined, (opt)depend on the mod defining it.
- * Example: `minetest.override_item("default:mese", {light_source=LIGHT_MAX})`
-* `minetest.clear_registered_ores()`
-* `minetest.clear_registered_biomes()`
-* `minetest.clear_registered_decorations()`
+* `minetest.register_chatcommand(cmd, chatcommand definition)`
+* `minetest.override_chatcommand(name, redefinition)`
+ * Overrides fields of a chatcommand registered with `register_chatcommand`.
+* `minetest.unregister_chatcommand(name)`
+ * Unregisters a chatcommands registered with `register_chatcommand`.
+* `minetest.register_privilege(name, definition)`
+ * `definition` can be a description or a definition table (see [Privilege
+ definition]).
+ * If it is a description, the priv will be granted to singleplayer and admin
+ by default.
+ * To allow players with `basic_privs` to grant, see the `basic_privs`
+ minetest.conf setting.
+* `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.
Global callback registration functions
--------------------------------------
@@ -3729,36 +3718,6 @@ Call these functions only at load time!
* You should have joined some channels to receive events.
* If message comes from a server mod, `sender` field is an empty string.
-Other registration functions
-----------------------------
-
-* `minetest.register_chatcommand(cmd, chatcommand definition)`
- * Adds definition to `minetest.registered_chatcommands`
-* `minetest.override_chatcommand(name, redefinition)`
- * Overrides fields of a chatcommand registered with `register_chatcommand`.
-* `minetest.unregister_chatcommand(name)`
- * Unregisters a chatcommands registered with `register_chatcommand`.
-* `minetest.register_privilege(name, definition)`
- * `definition`: `"description text"`
- * `definition`:
- `{description = "description text", give_to_singleplayer = boolean}`
- the default of `give_to_singleplayer` is true.
- * To allow players with `basic_privs` to grant, see `basic_privs`
- minetest.conf setting.
- * `on_grant(name, granter_name)`: Called when given to player `name` by
- `granter_name`.
- `granter_name` will be nil if the priv was granted by a mod.
- * `on_revoke(name, revoker_name)`: Called when taken from player `name` by
- `revoker_name`.
- `revoker_name` will be nil if the priv was revoked by a mod
- * 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(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
---------------
@@ -4713,6 +4672,8 @@ Global objects
Global tables
-------------
+### Registered definition tables
+
* `minetest.registered_items`
* Map of registered items, indexed by name
* `minetest.registered_nodes`
@@ -4727,14 +4688,35 @@ Global tables
* Map of object references, indexed by active object id
* `minetest.luaentities`
* Map of Lua entities, indexed by active object id
-* `minetest.registered_chatcommands`
- * Map of registered chat command definitions, indexed by name
+* `minetest.registered_abms`
+ * List of ABM definitions
+* `minetest.registered_lbms`
+ * List of LBM definitions
+* `minetest.registered_aliases`
+ * Map of registered aliases, indexed by name
* `minetest.registered_ores`
- * List of registered ore definitions.
+ * Map of registered ore definitions, indexed by the `name` field.
+ * If `name` is nil, the key is the ID returned by `minetest.register_ore`.
* `minetest.registered_biomes`
- * List of registered biome definitions.
+ * Map of registered biome definitions, indexed by the `name` field.
+ * If `name` is nil, the key is the ID returned by `minetest.register_biome`.
* `minetest.registered_decorations`
- * List of registered decoration definitions.
+ * Map of registered decoration definitions, indexed by the `name` field.
+ * If `name` is nil, the key is the ID returned by
+ `minetest.register_decoration`.
+* `minetest.registered_schematics`
+ * Map of registered schematic definitions, indexed by the `name` field.
+ * If `name` is nil, the key is the ID returned by
+ `minetest.register_schematic`.
+* `minetest.registered_chatcommands`
+ * Map of registered chat command definitions, indexed by name
+* `minetest.registered_privileges`
+ * Map of registered privilege definitions, indexed by name
+
+### Registered callback tables
+
+All callbacks registered with [Global callback registration functions] are added
+to corresponding `minetest.registered_*` tables.
@@ -6557,6 +6539,36 @@ Note that in params, use of symbols is as follows:
* `()` signifies grouping. For example, when param1 and param2 are both
required, or only param3 is required: `(<param1> <param2>) | <param3>`
+Privilege definition
+--------------------
+
+Used by `minetest.register_privilege`.
+
+ {
+ description = "Can teleport", -- Privilege description
+
+ give_to_singleplayer = false,
+ -- Whether to grant the privilege to singleplayer (default true).
+
+ give_to_admin = true,
+ -- Whether to grant the privilege to the server admin.
+ -- Uses value of 'give_to_singleplayer' by default.
+
+ on_grant = function(name, granter_name),
+ -- Called when given to player 'name' by 'granter_name'.
+ -- 'granter_name' will be nil if the priv was granted by a mod.
+
+ on_revoke = function(name, revoker_name),
+ -- Called when taken from player 'name' by 'revoker_name'.
+ -- 'revoker_name' will be nil if the priv was revoked by a mod.
+
+ -- 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.
+ }
+
Detached inventory callbacks
----------------------------