Lua_api.txt: Improve section titles, clarify sections (#7533)

This commit is contained in:
Paramat 2018-07-06 21:02:54 +01:00 committed by GitHub
parent 53dd781927
commit 55b6bc085b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -3,8 +3,12 @@ Minetest Lua Modding API Reference
* More information at <http://www.minetest.net/> * More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/> * Developer Wiki: <http://dev.minetest.net/>
Introduction Introduction
------------ ============
Content and functionality can be added to Minetest using Lua scripting Content and functionality can be added to Minetest using Lua scripting
in run-time loaded mods. in run-time loaded mods.
@ -44,8 +48,12 @@ Paths
* Linux: `$HOME/.minetest` * Linux: `$HOME/.minetest`
* Windows: `C:/users/<user>/AppData/minetest` (maybe) * Windows: `C:/users/<user>/AppData/minetest` (maybe)
Games Games
----- =====
Games are looked up from: Games are looked up from:
* `$path_share/games/gameid/` * `$path_share/games/gameid/`
@ -82,6 +90,12 @@ If you want to specify multiple images for one identifier, add additional
images named like `$identifier.$n.png`, with an ascending number $n starting images named like `$identifier.$n.png`, with an ascending number $n starting
with 1, and a random image will be chosen from the provided ones. with 1, and a random image will be chosen from the provided ones.
Mods
====
Mod load path Mod load path
------------- -------------
Generic: Generic:
@ -126,7 +140,7 @@ should be a mod, contains a file named `modpack.txt`. This file shall be
empty, except for lines starting with `#`, which are comments. empty, except for lines starting with `#`, which are comments.
Mod directory structure Mod directory structure
------------------------ -----------------------
mods mods
|-- modname |-- modname
@ -236,8 +250,12 @@ when registering it.
The `:` prefix can also be used for maintaining backwards compatibility. The `:` prefix can also be used for maintaining backwards compatibility.
Aliases Aliases
------- =======
Aliases can be added by using `minetest.register_alias(name, convert_to)` or Aliases can be added by using `minetest.register_alias(name, convert_to)` or
`minetest.register_alias_force(name, convert_to)`. `minetest.register_alias_force(name, convert_to)`.
@ -326,8 +344,12 @@ Dungeons:
"mapgen_mossycobble" "mapgen_mossycobble"
"mapgen_stair_desert_stone" "mapgen_stair_desert_stone"
Textures Textures
-------- ========
Mods should generally prefix their textures with `modname_`, e.g. given Mods should generally prefix their textures with `modname_`, e.g. given
the mod name `foomod`, a texture could be called: the mod name `foomod`, a texture could be called:
@ -719,8 +741,12 @@ Example (colored grass block):
palette = "default_foilage.png", palette = "default_foilage.png",
}) })
Sounds Sounds
------ ======
Only Ogg Vorbis files are supported. Only Ogg Vorbis files are supported.
For positional playing of sounds, only single-channel (mono) files are For positional playing of sounds, only single-channel (mono) files are
@ -790,8 +816,12 @@ one player using `to_player = name,`
* e.g. `{name = "default_place_node", gain = 1.0}` * e.g. `{name = "default_place_node", gain = 1.0}`
* e.g. `{name = "default_place_node", gain = 1.0, pitch = 1.0}` * e.g. `{name = "default_place_node", gain = 1.0, pitch = 1.0}`
Registered definitions of stuff Registered definitions of stuff
------------------------------- ===============================
Anything added using certain `minetest.register_*` functions get added to Anything added using certain `minetest.register_*` functions get added to
the global `minetest.registered_*` tables. the global `minetest.registered_*` tables.
@ -879,8 +909,12 @@ Example: `minetest.get_item_group(name, group)` has been implemented as:
return minetest.registered_items[name].groups[group] return minetest.registered_items[name].groups[group]
end end
Nodes Nodes
----- =====
Nodes are the bulk data of the world: cubes and other things that take the Nodes are the bulk data of the world: cubes and other things that take the
space of a cube. Huge amounts of them are handled efficiently, but they space of a cube. Huge amounts of them are handled efficiently, but they
are quite static. are quite static.
@ -1149,6 +1183,10 @@ A box of a regular node would look like:
HUD
===
HUD element types HUD element types
----------------- -----------------
The position field is used for all element types. The position field is used for all element types.
@ -1226,8 +1264,11 @@ Displays distance to selected world position.
text. text.
* `world_pos`: World position of the waypoint. * `world_pos`: World position of the waypoint.
Representations of simple things Representations of simple things
-------------------------------- ================================
### Position/vector ### Position/vector
@ -1240,8 +1281,12 @@ For helper functions see "Spatial Vectors".
* `{type="node", under=pos, above=pos}` * `{type="node", under=pos, above=pos}`
* `{type="object", ref=ObjectRef}` * `{type="object", ref=ObjectRef}`
Flag Specifier Format Flag Specifier Format
--------------------- =====================
Flags using the standardized flag specifier format can be specified in either Flags using the standardized flag specifier format can be specified in either
of two ways, by string or table. of two ways, by string or table.
@ -1273,8 +1318,11 @@ or even
since, by default, no schematic attributes are set. since, by default, no schematic attributes are set.
Items Items
----- =====
### Item types ### Item types
There are three kinds of items: nodes, tools and craftitems. There are three kinds of items: nodes, tools and craftitems.
@ -1334,8 +1382,11 @@ When an item must be passed to a function, it can usually be in any of
these formats. these formats.
Groups Groups
------ ======
In a number of places, there is a group table. Groups define the In a number of places, there is a group table. Groups define the
properties of a thing (item, node, armor of entity, capabilities of properties of a thing (item, node, armor of entity, capabilities of
tool) in such a way that the engine and other mods can can interact with tool) in such a way that the engine and other mods can can interact with
@ -1474,6 +1525,12 @@ Tools define their properties by a list of parameters for groups. They
cannot dig other groups; thus it is important to use a standard bunch of cannot dig other groups; thus it is important to use a standard bunch of
groups to enable interaction with tools. groups to enable interaction with tools.
Tools
=====
#### Tools definition #### Tools definition
Tools define: Tools define:
@ -1566,8 +1623,12 @@ Table of resulting tool uses:
easy nodes to be quickly breakable. easy nodes to be quickly breakable.
* At `level > 2`, the node is not diggable, because it's `level > maxlevel` * At `level > 2`, the node is not diggable, because it's `level > maxlevel`
Entity damage mechanism Entity damage mechanism
----------------------- =======================
Damage calculation: Damage calculation:
damage = 0 damage = 0
@ -1616,6 +1677,12 @@ To punch an entity/object in Lua, call:
* If `direction` equals `nil` and `puncher` does not equal `nil`, `direction` * If `direction` equals `nil` and `puncher` does not equal `nil`, `direction`
will be automatically filled in based on the location of `puncher`. will be automatically filled in based on the location of `puncher`.
Metadata
========
Node Metadata Node Metadata
------------- -------------
The instance of a node in the world normally only contains the three values The instance of a node in the world normally only contains the three values
@ -1680,8 +1747,12 @@ Example stuff:
meta:set_string("key", "value") meta:set_string("key", "value")
print(dump(meta:to_table())) print(dump(meta:to_table()))
Formspec Formspec
-------- ========
Formspec defines a menu. Currently not much else than inventories are Formspec defines a menu. Currently not much else than inventories are
supported. It is a string, with a somewhat strange format. supported. It is a string, with a somewhat strange format.
@ -2050,6 +2121,12 @@ appearing when you don't expect them to. See `no_prepend[]`
**Note**: do _not_ use a element name starting with `key_`; those names are **Note**: do _not_ use a element name starting with `key_`; those names are
reserved to pass key press events to formspec! reserved to pass key press events to formspec!
Inventory
=========
Inventory locations Inventory locations
------------------- -------------------
* `"context"`: Selected node metadata (deprecated: `"current_name"`) * `"context"`: Selected node metadata (deprecated: `"current_name"`)
@ -2065,6 +2142,12 @@ Player Inventory lists
* `craftpreview`: list containing the craft output * `craftpreview`: list containing the craft output
* `hand`: list containing an override for the empty hand * `hand`: list containing an override for the empty hand
Colours
=======
`ColorString` `ColorString`
------------- -------------
`#RGB` defines a color in hexadecimal format. `#RGB` defines a color in hexadecimal format.
@ -2091,8 +2174,12 @@ numerical form, the raw integer value of an ARGB8 quad:
or string form, a ColorString (defined above): or string form, a ColorString (defined above):
`colorspec = "green"` `colorspec = "green"`
Escape sequences Escape sequences
---------------- ================
Most text can contain escape sequences, that can for example color the text. Most text can contain escape sequences, that can for example color the text.
There are a few exceptions: tab headers, dropdowns and vertical labels can't. There are a few exceptions: tab headers, dropdowns and vertical labels can't.
The following functions provide escape sequences: The following functions provide escape sequences:
@ -2116,8 +2203,12 @@ The following functions provide escape sequences:
* `minetest.strip_colors(str)` * `minetest.strip_colors(str)`
* Removes all color escape sequences. * Removes all color escape sequences.
Spatial Vectors Spatial Vectors
--------------- ===============
For the following functions, `v`, `v1`, `v2` are vectors, For the following functions, `v`, `v1`, `v2` are vectors,
`p1`, `p2` are positions: `p1`, `p2` are positions:
@ -2158,8 +2249,12 @@ For the following functions `x` can be either a vector or a number:
* `vector.divide(v, x)`: * `vector.divide(v, x)`:
* Returns a scaled vector or Schur quotient. * Returns a scaled vector or Schur quotient.
Helper functions Helper functions
---------------- ================
* `dump2(obj, name, dumped)`: returns a string which makes `obj` * `dump2(obj, name, dumped)`: returns a string which makes `obj`
human-readable, handles reference loops. human-readable, handles reference loops.
* `obj`: arbitrary variable * `obj`: arbitrary variable
@ -2222,8 +2317,11 @@ Helper functions
position. position.
* returns the exact position on the surface of a pointed node * returns the exact position on the surface of a pointed node
Translations Translations
------------ ============
Texts can be translated client-side with the help of `minetest.translate` and Texts can be translated client-side with the help of `minetest.translate` and
translation files. translation files.
@ -2311,8 +2409,12 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
`minetest.translate`, but is in translation files. `minetest.translate`, but is in translation files.
* `@n` acts as a literal newline as well. * `@n` acts as a literal newline as well.
Perlin noise Perlin noise
------------ ============
Perlin noise creates a continuously-varying value depending on the input values. Perlin noise creates a continuously-varying value depending on the input values.
Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes. Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes.
The result is used during map generation to create the terrain shape, vary heat The result is used during map generation to create the terrain shape, vary heat
@ -2460,6 +2562,12 @@ For 2D or 3D perlin noise or perlin noise maps:
For 2D noise the Z component of `spread` is still defined but is ignored. For 2D noise the Z component of `spread` is still defined but is ignored.
A single noise parameter table can be used for 2D or 3D noise. A single noise parameter table can be used for 2D or 3D noise.
Ores
====
Ore types Ore types
--------- ---------
These tell in what manner the ore is generated. These tell in what manner the ore is generated.
@ -2587,8 +2695,12 @@ this attribute set, puff ore generation will instead generate the absolute
difference in noise displacement values. This flag has no effect for ore types difference in noise displacement values. This flag has no effect for ore types
other than `puff`. other than `puff`.
Decoration types Decoration types
---------------- ================
The varying types of decorations that can be placed. The varying types of decorations that can be placed.
### `simple` ### `simple`
@ -2605,6 +2717,12 @@ Can specify a probability of a node randomly appearing when placed.
This decoration type is intended to be used for multi-node sized discrete This decoration type is intended to be used for multi-node sized discrete
structures, such as trees, cave spikes, rocks, and so on. structures, such as trees, cave spikes, rocks, and so on.
Schematics
==========
Schematic specifier Schematic specifier
-------------------- --------------------
A schematic specifier identifies a schematic by either a filename to a A schematic specifier identifies a schematic by either a filename to a
@ -2650,8 +2768,12 @@ Currently supported flags: `place_center_x`, `place_center_y`, `place_center_z`,
* `force_placement`: Schematic nodes other than "ignore" will replace existing * `force_placement`: Schematic nodes other than "ignore" will replace existing
nodes. nodes.
Lua Voxel Manipulator Lua Voxel Manipulator
--------------------- =====================
### About VoxelManip ### About VoxelManip
VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator'
facility. The purpose of this object is for fast, low-level, bulk access to facility. The purpose of this object is for fast, low-level, bulk access to
@ -2933,8 +3055,12 @@ The coordinates are *inclusive*, like most other things in Minetest.
`[z [y [x]]]`. `[z [y [x]]]`.
* `iterp(minp, maxp)`: same as above, except takes a vector * `iterp(minp, maxp)`: same as above, except takes a vector
Mapgen objects Mapgen objects
-------------- ==============
A mapgen object is a construct used in map generation. Mapgen objects can be A mapgen object is a construct used in map generation. Mapgen objects can be
used by an `on_generate` callback to speed up operations by avoiding used by an `on_generate` callback to speed up operations by avoiding
unnecessary recalculations, these can be retrieved using the unnecessary recalculations, these can be retrieved using the
@ -2986,8 +3112,12 @@ Possible fields of the table returned are:
Decorations have a key in the format of `"decoration#id"`, where `id` is the Decorations have a key in the format of `"decoration#id"`, where `id` is the
numeric unique decoration ID. numeric unique decoration ID.
Registered entities Registered entities
------------------- ===================
* Functions receive a "luaentity" as `self`: * Functions receive a "luaentity" as `self`:
* It has the member `.name`, which is the registered name `("mod:thing")` * It has the member `.name`, which is the registered name `("mod:thing")`
* It has the member `.object`, which is an `ObjectRef` pointing to the * It has the member `.object`, which is an `ObjectRef` pointing to the
@ -3027,8 +3157,11 @@ Registered entities
* Should return a string that will be passed to `on_activate` when * Should return a string that will be passed to `on_activate` when
the object is instantiated the next time. the object is instantiated the next time.
L-system trees L-system trees
-------------- ==============
### Tree definition ### Tree definition
@ -3099,8 +3232,10 @@ Spawn a small apple tree:
minetest.spawn_tree(pos,apple_tree) minetest.spawn_tree(pos,apple_tree)
`minetest` namespace reference
------------------------------
'minetest' namespace reference
==============================
### Utilities ### Utilities
@ -4353,8 +4488,12 @@ These functions return the leftover itemstack.
* List of registered decoration definitions. * List of registered decoration definitions.
Class reference Class reference
--------------- ===============
Sorted alphabetically.
### `AreaStore` ### `AreaStore`
A fast access data structure to store areas, and find areas near a given A fast access data structure to store areas, and find areas near a given
@ -4975,8 +5114,10 @@ Can be obtained via `minetest.get_mod_storage()` during load time.
* All methods in MetaDataRef * All methods in MetaDataRef
Definition tables Definition tables
----------------- =================
### Object Properties ### Object Properties