From 1b83b0acfde26e1689202bb99659934ed598d705 Mon Sep 17 00:00:00 2001 From: Wuzzy Date: Fri, 2 Jun 2017 14:15:49 +0200 Subject: [PATCH] Lua_api.txt: Various edits and Markdown syntax improvements Add minor bits of missing Lua API documentation. Remove L-system lighting bug warning. Clarify 2 lines in node timer documentation. Fix many Markdown syntax errors in lua_api.txt. --- doc/lua_api.txt | 255 ++++++++++++++++++++++++++---------------------- 1 file changed, 137 insertions(+), 118 deletions(-) diff --git a/doc/lua_api.txt b/doc/lua_api.txt index e6d856368..e4ffa7bbe 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -186,7 +186,11 @@ Naming convention for registered textual names ---------------------------------------------- Registered names should generally be in this format: - "modname:" ( can have characters a-zA-Z0-9_) + `modname:` + +`` can have these characters: + + a-zA-Z0-9_ This is to prevent conflicting names from corrupting maps and is enforced by the mod loader. @@ -209,7 +213,7 @@ 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). +`minetest.register_alias_force(name, convert_to)`. This will make Minetest to convert things called name to things called `convert_to`. @@ -309,10 +313,10 @@ Example: default_sandstone.png^[resize:16x16 #### `[opacity:` - Makes the base image transparent according to the given ratio. - r must be between 0 and 255. - 0 means totally transparent. - 255 means totally opaque. +Makes the base image transparent according to the given ratio. + +`r` must be between 0 and 255. +0 means totally transparent. 255 means totally opaque. Example: @@ -676,7 +680,7 @@ the global `minetest.registered_*` tables. * `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 + * table according to its nature: `minetest.registered_nodes[]` etc * `minetest.register_biome(biome definition)` * returns an integer uniquely identifying the registered biome @@ -754,9 +758,9 @@ They are represented by a table: {name="name", param1=num, param2=num} -`param1` and `param2` are 8-bit integers. The engine uses them for certain -automated functions. If you don't use these functions, you can use them to -store arbitrary values. +`param1` and `param2` are 8-bit integers ranging from 0 to 255. The engine uses +them for certain automated functions. If you don't use these functions, you can +use them to store arbitrary values. The functions of `param1` and `param2` are determined by certain fields in the node definition: @@ -825,15 +829,6 @@ node definition: ^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes. param2 defines 64 levels of internal liquid. Liquid texture is defined using `special_tiles = {"modname_tilename.png"},` - collision_box = { - type = "fixed", - fixed = { - {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, - }, - }, - ^ defines list of collision boxes for the node. If empty, collision boxes - will be the same as nodeboxes, in case of any other nodes will be full cube - as in the example above. Nodes can also contain extra data. See "Node Metadata". @@ -984,6 +979,7 @@ If no flags are specified (or defaults is), 2D noise is eased and 3D noise is no Accumulates the absolute value of each noise gradient result. Noise parameters format example for 2D or 3D perlin noise or perlin noise maps: + np_terrain = { offset = 0, scale = 1, @@ -994,8 +990,8 @@ Noise parameters format example for 2D or 3D perlin noise or perlin noise maps: lacunarity = 2.0, flags = "defaults, absvalue" } - ^ A single noise parameter table can be used to get 2D or 3D noise, - when getting 2D noise spread.z is ignored. + ^ A single noise parameter table can be used to get 2D or 3D noise, + when getting 2D noise spread.z is ignored. Ore types @@ -1067,14 +1063,15 @@ to small changes. The following is a decent set of parameters to work from: }, noise_threshold = 1.6 -WARNING: Use this ore type *very* sparingly since it is ~200x more +**WARNING**: Use this ore type *very* sparingly since it is ~200x more computationally expensive than any other ore. Ore attributes -------------- See section "Flag Specifier Format". -Currently supported flags: `absheight` +Currently supported flags: +`absheight`, `puff_cliffs`, `puff_additive_composition`. ### `absheight` Also produce this same ore between the height range of `-y_max` and `-y_min`. @@ -1130,6 +1127,7 @@ in the form of a table. This table specifies the following fields: previous contents (default: false) About probability values: + * A probability value of `0` or `1` means that node will never appear (0% chance). * A probability value of `254` or `255` means the node will always appear (100% chance). * If the probability value `p` is greater than `1`, then there is a @@ -1284,16 +1282,32 @@ There are three kinds of items: nodes, tools and craftitems. things according to `tool_capabilities`. * Craftitem (`register_craftitem`): A miscellaneous item. +### Amount and wear +All item stacks have an amount between 0 to 65535. It is 1 by +default. Tool item stacks can not have an amount greater than 1. + +Tools use a wear (=damage) value ranging from 0 to 65535. The +value 0 is the default and used is for unworn tools. The values +1 to 65535 are used for worn tools, where a higher value stands for +a higher wear. Non-tools always have a wear value of 0. + ### Item formats Items and item stacks can exist in three formats: Serializes, table format and `ItemStack`. #### Serialized -This is called "stackstring" or "itemstring": +This is called "stackstring" or "itemstring". It is a simple string with +1-3 components: the full item identifier, an optional amount and an optional +wear value. Syntax: + + [[ ]] -* e.g. `'default:dirt 5'` -* e.g. `'default:pick_wood 21323'` -* e.g. `'default:apple'` +Examples: + +* `'default:apple'`: 1 apple +* `'default:dirt 5'`: 5 dirt +* `'default:pick_stone'`: a new stone pickaxe +* `'default:pick_wood 1 21323'`: a wooden pickaxe, ca. 1/3 worn out #### Table format Examples: @@ -1387,6 +1401,9 @@ Another example: Make red wool from white wool and red dye: ### Special groups * `immortal`: Disables the group damage system for an entity +* `punch_operable`: For entities; disables the regular damage mechanism for + players punching it by hand or a non-tool item, so that it can do something + else than take damage. * `level`: Can be used to give an additional sense of progression in the game. * A larger level will cause e.g. a weapon of a lower level make much less damage, and get worn out much faster, or not be able to get drops @@ -1425,6 +1442,7 @@ Another example: Make red wool from white wool and red dye: ### Examples of custom groups Item groups are often used for defining, well, _groups of items_. + * `meat`: any meat-kind of a thing (rating might define the size or healing ability or be irrelevant -- it is not defined as of yet) * `eatable`: anything that can be eaten. Rating might define HP gain in half @@ -1645,7 +1663,7 @@ Item metadata only contains a key-value store. Some of the values in the key-value store are handled specially: -* `description`: Set the itemstack's description. Defaults to idef.description +* `description`: Set the item stack's description. Defaults to `idef.description` * `color`: A `ColorString`, which sets the stack's color. * `palette_index`: If the item has a palette, this is used to get the current color from the palette. @@ -1707,7 +1725,7 @@ examples. #### `container[,]` * Start of a container block, moves all physical elements in the container by (X, Y) -* Must have matching container_end +* Must have matching `container_end` * Containers can be nested, in which case the offsets are added (child containers are relative to parent containers) @@ -1792,7 +1810,7 @@ examples. #### `field[,;,;;