mirror of
https://github.com/minetest/minetest.git
synced 2024-11-23 16:13:46 +01:00
Lua_api.txt: Improve section titles, clarify sections (#7533)
This commit is contained in:
Paramat
GitHub
parent
53dd781927
commit
55b6bc085b
197
doc/lua_api.txt
197
doc/lua_api.txt
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user