Skip to content

Commit

Permalink
lua_api.txt: Various fixes and improvements (#7945)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@p-ouellette @nerzhul
p-ouellette authored and nerzhul committed Dec 11, 2018
1 parent a857529 commit ce32a32
Showing 1 changed file with 131 additions and 119 deletions.
250 changes: 131 additions & 119 deletions doc/lua_api.txt
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -1546,15 +1493,13 @@ 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.
Slipperiness rises steadily with `slippery` value, starting at 1.
* `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
---------------------------------------------

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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>]`

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)`
Expand All @@ -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
--------------------------------------
Expand Down Expand Up @@ -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
---------------

Expand Down Expand Up @@ -4713,6 +4672,8 @@ Global objects
Global tables
-------------

### Registered definition tables

* `minetest.registered_items`
* Map of registered items, indexed by name
* `minetest.registered_nodes`
Expand All @@ -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.



Expand Down Expand Up @@ -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
----------------------------

Expand Down

0 comments on commit ce32a32

Please sign in to comment.