diff --git a/doc/lua_api.txt b/doc/lua_api.txt index d7f45fb1b..d6cdd80a1 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -3,8 +3,12 @@ Minetest Lua Modding API Reference * More information at * Developer Wiki: + + + 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//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