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/>
* Developer Wiki: <http://dev.minetest.net/>
Introduction
------------
============
Content and functionality can be added to Minetest using Lua scripting
in run-time loaded mods.
@ -44,8 +48,12 @@ Paths
* Linux: `$HOME/.minetest`
* Windows: `C:/users/<user>/AppData/minetest` (maybe)
Games
-----
=====
Games are looked up from:
* `$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
with 1, and a random image will be chosen from the provided ones.
Mods
====
Mod load path
-------------
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.
Mod directory structure
------------------------
-----------------------
mods
|-- modname
@ -236,8 +250,12 @@ when registering it.
The `:` prefix can also be used for maintaining backwards compatibility.
Aliases
-------
=======
Aliases can be added by using `minetest.register_alias(name, convert_to)` or
`minetest.register_alias_force(name, convert_to)`.
@ -326,8 +344,12 @@ Dungeons:
"mapgen_mossycobble"
"mapgen_stair_desert_stone"
Textures
--------
========
Mods should generally prefix their textures with `modname_`, e.g. given
the mod name `foomod`, a texture could be called:
@ -719,8 +741,12 @@ Example (colored grass block):
palette = "default_foilage.png",
})
Sounds
------
======
Only Ogg Vorbis files are supported.
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, pitch = 1.0}`
Registered definitions of stuff
-------------------------------
===============================
Anything added using certain `minetest.register_*` functions get added to
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]
end
Nodes
-----
=====
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
are quite static.
@ -1149,6 +1183,10 @@ A box of a regular node would look like:
HUD
===
HUD element types
-----------------
The position field is used for all element types.
@ -1226,8 +1264,11 @@ Displays distance to selected world position.
text.
* `world_pos`: World position of the waypoint.
Representations of simple things
--------------------------------
================================
### Position/vector
@ -1240,8 +1281,12 @@ For helper functions see "Spatial Vectors".
* `{type="node", under=pos, above=pos}`
* `{type="object", ref=ObjectRef}`
Flag Specifier Format
---------------------
=====================
Flags using the standardized flag specifier format can be specified in either
of two ways, by string or table.
@ -1273,8 +1318,11 @@ or even
since, by default, no schematic attributes are set.
Items
-----
=====
### Item types
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.
Groups
------
======
In a number of places, there is a group table. Groups define the
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
@ -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
groups to enable interaction with tools.
Tools
=====
#### Tools definition
Tools define:
@ -1566,8 +1623,12 @@ Table of resulting tool uses:
easy nodes to be quickly breakable.
* At `level > 2`, the node is not diggable, because it's `level > maxlevel`
Entity damage mechanism
-----------------------
=======================
Damage calculation:
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`
will be automatically filled in based on the location of `puncher`.
Metadata
========
Node Metadata
-------------
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")
print(dump(meta:to_table()))
Formspec
--------
========
Formspec defines a menu. Currently not much else than inventories are
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
reserved to pass key press events to formspec!
Inventory
=========
Inventory locations
-------------------
* `"context"`: Selected node metadata (deprecated: `"current_name"`)
@ -2065,6 +2142,12 @@ Player Inventory lists
* `craftpreview`: list containing the craft output
* `hand`: list containing an override for the empty hand
Colours
=======
`ColorString`
-------------
`#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):
`colorspec = "green"`
Escape sequences
----------------
================
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.
The following functions provide escape sequences:
@ -2116,8 +2203,12 @@ The following functions provide escape sequences:
* `minetest.strip_colors(str)`
* Removes all color escape sequences.
Spatial Vectors
---------------
===============
For the following functions, `v`, `v1`, `v2` are vectors,
`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)`:
* Returns a scaled vector or Schur quotient.
Helper functions
----------------
================
* `dump2(obj, name, dumped)`: returns a string which makes `obj`
human-readable, handles reference loops.
* `obj`: arbitrary variable
@ -2222,8 +2317,11 @@ Helper functions
position.
* returns the exact position on the surface of a pointed node
Translations
------------
============
Texts can be translated client-side with the help of `minetest.translate` and
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.
* `@n` acts as a literal newline as well.
Perlin noise
------------
============
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.
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.
A single noise parameter table can be used for 2D or 3D noise.
Ores
====
Ore types
---------
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
other than `puff`.
Decoration types
----------------
================
The varying types of decorations that can be placed.
### `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
structures, such as trees, cave spikes, rocks, and so on.
Schematics
==========
Schematic specifier
--------------------
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
nodes.
Lua Voxel Manipulator
---------------------
=====================
### About VoxelManip
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
@ -2933,8 +3055,12 @@ The coordinates are *inclusive*, like most other things in Minetest.
`[z [y [x]]]`.
* `iterp(minp, maxp)`: same as above, except takes a vector
Mapgen objects
--------------
==============
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
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
numeric unique decoration ID.
Registered entities
-------------------
===================
* Functions receive a "luaentity" as `self`:
* It has the member `.name`, which is the registered name `("mod:thing")`
* 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
the object is instantiated the next time.
L-system trees
--------------
==============
### Tree definition
@ -3099,8 +3232,10 @@ Spawn a small apple tree:
minetest.spawn_tree(pos,apple_tree)
`minetest` namespace reference
------------------------------
'minetest' namespace reference
==============================
### Utilities
@ -4353,8 +4488,12 @@ These functions return the leftover itemstack.
* List of registered decoration definitions.
Class reference
---------------
===============
Sorted alphabetically.
### `AreaStore`
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
Definition tables
-----------------
=================
### Object Properties