From e4e95e47afa86b7c522d5b5e64c6ed10094108ff Mon Sep 17 00:00:00 2001 From: Paramat Date: Tue, 26 Jun 2018 02:34:27 +0100 Subject: [PATCH] Lua_api.txt: Re-order some sections. Alphabeticise class reference (#7487) --- doc/lua_api.txt | 3797 ++++++++++++++++++++++++----------------------- 1 file changed, 1899 insertions(+), 1898 deletions(-) diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 47931eb00..9fb22556b 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -1147,1509 +1147,1957 @@ A box of a regular node would look like: {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, -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 -and humidity to distribute biomes, vary the density of decorations or vary the -structure of ores. -### Structure of perlin noise -An 'octave' is a simple noise generator that outputs a value between -1 and 1. -The smooth wavy noise it generates has a single characteristic scale, almost -like a 'wavelength', so on its own does not create fine detail. -Due to this perlin noise combines several octaves to create variation on -multiple scales. Each additional octave has a smaller 'wavelength' than the -previous. -This combination results in noise varying very roughly between -2.0 and 2.0 and -with an average value of 0.0, so `scale` and `offset` are then used to multiply -and offset the noise variation. +HUD element types +----------------- +The position field is used for all element types. -The final perlin noise variation is created as follows: +To account for differing resolutions, the position coordinates are the +percentage of the screen, ranging in value from `0` to `1`. -noise = offset + scale * (octave1 + - octave2 * persistence + - octave3 * persistence ^ 2 + - octave4 * persistence ^ 3 + - ...) +The name field is not yet used, but should contain a description of what the +HUD element represents. The direction field is the direction in which something +is drawn. -Noise Parameters ----------------- -Noise Parameters are commonly called `NoiseParams`. +`0` draws from left to right, `1` draws from right to left, `2` draws from +top to bottom, and `3` draws from bottom to top. -### `offset` -After the multiplication by `scale` this is added to the result and is the final -step in creating the noise value. -Can be positive or negative. +The `alignment` field specifies how the item will be aligned. It ranges from +`-1` to `1`, with `0` being the center. `-1` is moved to the left/up, and `1` +is to the right/down. Fractional values can be used. -### `scale` -Once all octaves have been combined, the result is multiplied by this. -Can be positive or negative. +The `offset` field specifies a pixel offset from the position. Contrary to +position, the offset is not scaled to screen size. This allows for some +precisely positioned items in the HUD. -### `spread` -For octave1, this is roughly the change of input value needed for a very large -variation in the noise value generated by octave1. It is almost like a -'wavelength' for the wavy noise variation. -Each additional octave has a 'wavelength' that is smaller than the previous -octave, to create finer detail. `spread` will therefore roughly be the typical -size of the largest structures in the final noise variation. +**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling +factor! -`spread` is a vector with values for x, y, z to allow the noise variation to be -stretched or compressed in the desired axes. -Values are positive numbers. +Below are the specific uses for fields in each type; fields not listed for that +type are ignored. -### `seed` -This is a whole number that determines the entire pattern of the noise -variation. Altering it enables different noise patterns to be created. -With other parameters equal, different seeds produce different noise patterns -and identical seeds produce identical noise patterns. +### `image` +Displays an image on the HUD. -For this parameter you can randomly choose any whole number. Usually it is -preferable for this to be different from other seeds, but sometimes it is useful -to be able to create identical noise patterns. +* `scale`: The scale of the image, with 1 being the original texture size. + Only the X coordinate scale is used (positive values). + Negative values represent that percentage of the screen it + should take; e.g. `x=-100` means 100% (width). +* `text`: The name of the texture that is displayed. +* `alignment`: The alignment of the image. +* `offset`: offset in pixels from position. -When used in mapgen this is actually a 'seed offset', it is added to the -'world seed' to create the seed used by the noise, to ensure the noise has a -different pattern in different worlds. +### `text` +Displays text on the HUD. -### `octaves` -The number of simple noise generators that are combined. -A whole number, 1 or more. -Each additional octave adds finer detail to the noise but also increases the -noise calculation load. -3 is a typical minimum for a high quality, complex and natural-looking noise -variation. 1 octave has a slight 'gridlike' appearence. +* `scale`: Defines the bounding rectangle of the text. + A value such as `{x=100, y=100}` should work. +* `text`: The text to be displayed in the HUD element. +* `number`: An integer containing the RGB value of the color used to draw the + text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. +* `alignment`: The alignment of the text. +* `offset`: offset in pixels from position. -Choose the number of octaves according to the `spread` and `lacunarity`, and the -size of the finest detail you require. For example: -if `spread` is 512 nodes, `lacunarity` is 2.0 and finest detail required is 16 -nodes, octaves will be 6 because the 'wavelengths' of the octaves will be -512, 256, 128, 64, 32, 16 nodes. -Warning: If the 'wavelength' of any octave falls below 1 an error will occur. +### `statbar` +Displays a horizontal bar made up of half-images. -### `persistence` -Each additional octave has an amplitude that is the amplitude of the previous -octave multiplied by `persistence`, to reduce the amplitude of finer details, -as is often helpful and natural to do so. -Since this controls the balance of fine detail to large-scale detail -`persistence` can be thought of as the 'roughness' of the noise. +* `text`: The name of the texture that is used. +* `number`: The number of half-textures that are displayed. + If odd, will end with a vertically center-split texture. +* `direction` +* `offset`: offset in pixels from position. +* `size`: If used, will force full-image size to this value (override texture + pack image size) -A positive or negative non-zero number, often between 0.3 and 1.0. -A common medium value is 0.5, such that each octave has half the amplitude of -the previous octave. -This may need to be tuned when altering `lacunarity`; when doing so consider -that a common medium value is 1 / lacunarity. +### `inventory` +* `text`: The name of the inventory list to be displayed. +* `number`: Number of items in the inventory to be displayed. +* `item`: Position of item that is selected. +* `direction` +* `offset`: offset in pixels from position. -### `lacunarity` -Each additional octave has a 'wavelength' that is the 'wavelength' of the -previous octave multiplied by 1 / lacunarity, to create finer detail. -'lacunarity' is often 2.0 so 'wavelength' often halves per octave. +### `waypoint` +Displays distance to selected world position. -A positive number no smaller than 1.0. -Values below 2.0 create higher quality noise at the expense of requiring more -octaves to cover a paticular range of 'wavelengths'. +* `name`: The name of the waypoint. +* `text`: Distance suffix. Can be blank. +* `number:` An integer containing the RGB value of the color used to draw the + text. +* `world_pos`: World position of the waypoint. -### `flags` -Leave this field unset for no special handling. -Currently supported are `defaults`, `eased` and `absvalue`: +Representations of simple things +-------------------------------- -#### `defaults` -Specify this if you would like to keep auto-selection of eased/not-eased while -specifying some other flags. +### Position/vector -#### `eased` -Maps noise gradient values onto a quintic S-curve before performing -interpolation. This results in smooth, rolling noise. -Disable this (`noeased`) for sharp-looking noise with a slightly gridded -appearence. -If no flags are specified (or defaults is), 2D noise is eased and 3D noise is -not eased. -Easing a 3D noise significantly increases the noise calculation load, so use -with restraint. + {x=num, y=num, z=num} -#### `absvalue` -The absolute value of each octave's noise variation is used when combining the -octaves. The final perlin noise variation is created as follows: +For helper functions see "Spatial Vectors". -noise = offset + scale * (abs(octave1) + - abs(octave2) * persistence + - abs(octave3) * persistence ^ 2 + - abs(octave4) * persistence ^ 3 + - ...) +### `pointed_thing` +* `{type="nothing"}` +* `{type="node", under=pos, above=pos}` +* `{type="object", ref=ObjectRef}` -###Format example -For 2D or 3D perlin noise or perlin noise maps: +Flag Specifier Format +--------------------- +Flags using the standardized flag specifier format can be specified in either +of two ways, by string or table. - np_terrain = { - offset = 0, - scale = 1, - spread = {x = 500, y = 500, z = 500}, - seed = 571347, - octaves = 5, - persist = 0.63, - lacunarity = 2.0, - flags = "defaults, absvalue", - } +The string format is a comma-delimited set of flag names; whitespace and +unrecognized flag fields are ignored. Specifying a flag in the string sets the +flag, and specifying a flag prefixed by the string `"no"` explicitly +clears the flag from whatever the default may be. -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. +In addition to the standard string flag format, the schematic flags field can +also be a table of flag names to boolean values representing whether or not the +flag is set. Additionally, if a field with the flag name prefixed with `"no"` +is present, mapped to a boolean of any value, the specified flag is unset. -Ore types ---------- -These tell in what manner the ore is generated. +E.g. A flag field of value -All default ores are of the uniformly-distributed scatter type. + {place_center_x = true, place_center_y=false, place_center_z=true} -### `scatter` -Randomly chooses a location and generates a cluster of ore. +is equivalent to -If `noise_params` is specified, the ore will be placed if the 3D perlin noise -at that point is greater than the `noise_threshold`, giving the ability to -create a non-equal distribution of ore. + {place_center_x = true, noplace_center_y=true, place_center_z=true} -### `sheet` -Creates a sheet of ore in a blob shape according to the 2D perlin noise -described by `noise_params` and `noise_threshold`. This is essentially an -improved version of the so-called "stratus" ore seen in some unofficial mods. +which is equivalent to -This sheet consists of vertical columns of uniform randomly distributed height, -varying between the inclusive range `column_height_min` and `column_height_max`. -If `column_height_min` is not specified, this parameter defaults to 1. -If `column_height_max` is not specified, this parameter defaults to `clust_size` -for reverse compatibility. New code should prefer `column_height_max`. + "place_center_x, noplace_center_y, place_center_z" -The `column_midpoint_factor` parameter controls the position of the column at -which ore emanates from. -If 1, columns grow upward. If 0, columns grow downward. If 0.5, columns grow -equally starting from each direction. -`column_midpoint_factor` is a decimal number ranging in value from 0 to 1. If -this parameter is not specified, the default is 0.5. +or even -The ore parameters `clust_scarcity` and `clust_num_ores` are ignored for this -ore type. + "place_center_x, place_center_z" -### `puff` -Creates a sheet of ore in a cloud-like puff shape. +since, by default, no schematic attributes are set. -As with the `sheet` ore type, the size and shape of puffs are described by -`noise_params` and `noise_threshold` and are placed at random vertical -positions within the currently generated chunk. +Items +----- -The vertical top and bottom displacement of each puff are determined by the -noise parameters `np_puff_top` and `np_puff_bottom`, respectively. +### Item types +There are three kinds of items: nodes, tools and craftitems. -### `blob` -Creates a deformed sphere of ore according to 3d perlin noise described by -`noise_params`. The maximum size of the blob is `clust_size`, and -`clust_scarcity` has the same meaning as with the `scatter` type. +* Node (`register_node`): A node from the world. +* Tool (`register_tool`): A tool/weapon that can dig and damage + things according to `tool_capabilities`. +* Craftitem (`register_craftitem`): A miscellaneous item. -### `vein` -Creates veins of ore varying in density by according to the intersection of two -instances of 3d perlin noise with different seeds, both described by -`noise_params`. - -`random_factor` varies the influence random chance has on placement of an ore -inside the vein, which is `1` by default. Note that modifying this parameter -may require adjusting `noise_threshold`. +### 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. -The parameters `clust_scarcity`, `clust_num_ores`, and `clust_size` are ignored -by this ore type. +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. -This ore type is difficult to control since it is sensitive to small changes. -The following is a decent set of parameters to work from: +### Item formats +Items and item stacks can exist in three formats: Serializes, table format +and `ItemStack`. - noise_params = { - offset = 0, - scale = 3, - spread = {x=200, y=200, z=200}, - seed = 5390, - octaves = 4, - persist = 0.5, - lacunarity = 2.0, - flags = "eased", - }, - noise_threshold = 1.6 +#### Serialized +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: -**WARNING**: Use this ore type *very* sparingly since it is ~200x more -computationally expensive than any other ore. + [[ ]] -### `stratum` -Creates a single undulating ore stratum that is continuous across mapchunk -borders and horizontally spans the world. +Examples: -The 2D perlin noise described by `noise_params` defines the Y co-ordinate of -the stratum midpoint. The 2D perlin noise described by `np_stratum_thickness` -defines the stratum's vertical thickness (in units of nodes). Due to being -continuous across mapchunk borders the stratum's vertical thickness is -unlimited. +* `'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 -If the noise parameter `noise_params` is omitted the ore will occur from y_min -to y_max in a simple horizontal stratum. +#### Table format +Examples: -A parameter `stratum_thickness` can be provided instead of the noise parameter -`np_stratum_thickness`, to create a constant thickness. +5 dirt nodes: -Leaving out one or both noise parameters makes the ore generation less -intensive, useful when adding multiple strata. + {name="default:dirt", count=5, wear=0, metadata=""} -`y_min` and `y_max` define the limits of the ore generation and for performance -reasons should be set as close together as possible but without clipping the -stratum's Y variation. +A wooden pick about 1/3 worn out: -Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a -solid-ore stratum would require a `clust_scarcity` of 1. + {name="default:pick_wood", count=1, wear=21323, metadata=""} -The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and -`random_factor` are ignored by this ore type. +An apple: -Ore attributes --------------- -See section "Flag Specifier Format". + {name="default:apple", count=1, wear=0, metadata=""} -Currently supported flags: -`puff_cliffs`, `puff_additive_composition`. +#### `ItemStack` +A native C++ format with many helper methods. Useful for converting +between formats. See the Class reference section for details. -### `puff_cliffs` -If set, puff ore generation will not taper down large differences in -displacement when approaching the edge of a puff. This flag has no effect for -ore types other than `puff`. +When an item must be passed to a function, it can usually be in any of +these formats. -### `puff_additive_composition` -By default, when noise described by `np_puff_top` or `np_puff_bottom` results -in a negative displacement, the sub-column at that point is not generated. With -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. +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 +the thing without actually knowing what the thing is. -### `simple` -Creates a 1 times `H` times 1 column of a specified node (or a random node from -a list, if a decoration list is specified). Can specify a certain node it must -spawn next to, such as water or lava, for example. Can also generate a -decoration of random height between a specified lower and upper bound. -This type of decoration is intended for placement of grass, flowers, cacti, -papyri, waterlilies and so on. +### Usage +Groups are stored in a table, having the group names with keys and the +group ratings as values. For example: -### `schematic` -Copies a box of `MapNodes` from a specified schematic file (or raw description). -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. + groups = {crumbly=3, soil=1} + -- ^ Default dirt + groups = {crumbly=2, soil=1, level=2, outerspace=1} + -- ^ A more special dirt-kind of thing -Schematic specifier --------------------- -A schematic specifier identifies a schematic by either a filename to a -Minetest Schematic file (`.mts`) or through raw data supplied through Lua, -in the form of a table. This table specifies the following fields: +Groups always have a rating associated with them. If there is no +useful meaning for a rating for an enabled group, it shall be `1`. -* The `size` field is a 3D vector containing the dimensions of the provided - schematic. (required) -* The `yslice_prob` field is a table of {ypos, prob} which sets the `ypos`th - vertical slice of the schematic to have a `prob / 256 * 100` chance of - occurring. (default: 255) -* The `data` field is a flat table of MapNode tables making up the schematic, - in the order of `[z [y [x]]]`. (required) - Each MapNode table contains: - * `name`: the name of the map node to place (required) - * `prob` (alias `param1`): the probability of this node being placed - (default: 255) - * `param2`: the raw param2 value of the node being placed onto the map - (default: 0) - * `force_place`: boolean representing if the node should forcibly overwrite - any previous contents (default: false) +When not defined, the rating of a group defaults to `0`. Thus when you +read groups, you must interpret `nil` and `0` as the same value, `0`. -About probability values: +You can read the rating of a group for an item or a node by using -* 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 - `(p / 256 * 100)` percent chance that node will appear when the schematic is - placed on the map. + minetest.get_item_group(itemname, groupname) +### Groups of items +Groups of items can define what kind of an item it is (e.g. wool). -Schematic attributes --------------------- -See section "Flag Specifier Format". +### Groups of nodes +In addition to the general item things, groups are used to define whether +a node is destroyable and how long it takes to destroy by a tool. -Currently supported flags: `place_center_x`, `place_center_y`, `place_center_z`, - `force_placement`. +### Groups of entities +For entities, groups are, as of now, used only for calculating damage. +The rating is the percentage of damage caused by tools with this damage group. +See "Entity damage mechanism". -* `place_center_x`: Placement of this decoration is centered along the X axis. -* `place_center_y`: Placement of this decoration is centered along the Y axis. -* `place_center_z`: Placement of this decoration is centered along the Z axis. -* `force_placement`: Schematic nodes other than "ignore" will replace existing - nodes. + object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) + object.set_armor_groups({fleshy=30, cracky=80}) +### Groups of tools +Groups in tools define which groups of nodes and entities they are +effective towards. -HUD element types ------------------ -The position field is used for all element types. +### Groups in crafting recipes +An example: Make meat soup from any meat, any water and any bowl: -To account for differing resolutions, the position coordinates are the -percentage of the screen, ranging in value from `0` to `1`. + { + output = 'food:meat_soup_raw', + recipe = { + {'group:meat'}, + {'group:water'}, + {'group:bowl'}, + }, + -- preserve = {'group:bowl'}, -- Not implemented yet (TODO) + } -The name field is not yet used, but should contain a description of what the -HUD element represents. The direction field is the direction in which something -is drawn. +Another example: Make red wool from white wool and red dye: -`0` draws from left to right, `1` draws from right to left, `2` draws from -top to bottom, and `3` draws from bottom to top. + { + type = 'shapeless', + output = 'wool:red', + recipe = {'wool:white', 'group:dye,basecolor_red'}, + } -The `alignment` field specifies how the item will be aligned. It ranges from -`-1` to `1`, with `0` being the center. `-1` is moved to the left/up, and `1` -is to the right/down. Fractional values can be used. +### 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 + from destroyed nodes. + * `0` is something that is directly accessible at the start of gameplay + * There is no upper limit +* `dig_immediate`: (player can always pick up node without reducing tool wear) + * `2`: the node always gets the digging time 0.5 seconds (rail, sign) + * `3`: the node always gets the digging time 0 seconds (torch) +* `disable_jump`: Player (and possibly other things) cannot jump from node +* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)` +* `bouncy`: value is bounce speed in percent +* `falling_node`: if there is no walkable block under the node it will fall +* `attached_node`: if the node under it is not a walkable block the node will be + dropped as an item. If the node is wallmounted the wallmounted direction is + checked. +* `soil`: saplings will grow on nodes in this group +* `connect_to_raillike`: makes nodes of raillike drawtype with same group value + connect to each other +* `slippery`: Players and items will slide on the node. + Slipperiness rises steadily with `slippery` value, starting at 1. -The `offset` field specifies a pixel offset from the position. Contrary to -position, the offset is not scaled to screen size. This allows for some -precisely positioned items in the HUD. -**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling -factor! +### Known damage and digging time defining groups +* `crumbly`: dirt, sand +* `cracky`: tough but crackable stuff like stone. +* `snappy`: something that can be cut using fine tools; e.g. leaves, small + plants, wire, sheets of metal +* `choppy`: something that can be cut using force; e.g. trees, wooden planks +* `fleshy`: Living things like animals and the player. This could imply + some blood effects when hitting. +* `explody`: Especially prone to explosions +* `oddly_breakable_by_hand`: + Can be added to nodes that shouldn't logically be breakable by the + hand but are. Somewhat similar to `dig_immediate`, but times are more + like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the + speed of a tool if the tool can dig at a faster speed than this + suggests for the hand. -Below are the specific uses for fields in each type; fields not listed for that -type are ignored. +### Examples of custom groups +Item groups are often used for defining, well, _groups of items_. -### `image` -Displays an image on the HUD. +* `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 + hearts. +* `flammable`: can be set on fire. Rating might define the intensity of the + fire, affecting e.g. the speed of the spreading of an open fire. +* `wool`: any wool (any origin, any color) +* `metal`: any metal +* `weapon`: any weapon +* `heavy`: anything considerably heavy -* `scale`: The scale of the image, with 1 being the original texture size. - Only the X coordinate scale is used (positive values). - Negative values represent that percentage of the screen it - should take; e.g. `x=-100` means 100% (width). -* `text`: The name of the texture that is displayed. -* `alignment`: The alignment of the image. -* `offset`: offset in pixels from position. +### Digging time calculation specifics +Groups such as `crumbly`, `cracky` and `snappy` are used for this +purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies +faster digging time. -### `text` -Displays text on the HUD. +The `level` group is used to limit the toughness of nodes a tool can dig +and to scale the digging times / damage to a greater extent. -* `scale`: Defines the bounding rectangle of the text. - A value such as `{x=100, y=100}` should work. -* `text`: The text to be displayed in the HUD element. -* `number`: An integer containing the RGB value of the color used to draw the - text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. -* `alignment`: The alignment of the text. -* `offset`: offset in pixels from position. +**Please do understand this**, otherwise you cannot use the system to it's +full potential. -### `statbar` -Displays a horizontal bar made up of half-images. +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. -* `text`: The name of the texture that is used. -* `number`: The number of half-textures that are displayed. - If odd, will end with a vertically center-split texture. -* `direction` -* `offset`: offset in pixels from position. -* `size`: If used, will force full-image size to this value (override texture - pack image size) +#### Tools definition +Tools define: -### `inventory` -* `text`: The name of the inventory list to be displayed. -* `number`: Number of items in the inventory to be displayed. -* `item`: Position of item that is selected. -* `direction` -* `offset`: offset in pixels from position. +* Full punch interval +* Maximum drop level +* For an arbitrary list of groups: + * Uses (until the tool breaks) + * Maximum level (usually `0`, `1`, `2` or `3`) + * Digging times + * Damage groups -### `waypoint` -Displays distance to selected world position. +#### Full punch interval +When used as a weapon, the tool will do full damage if this time is spent +between punches. If e.g. half the time is spent, the tool will do half +damage. -* `name`: The name of the waypoint. -* `text`: Distance suffix. Can be blank. -* `number:` An integer containing the RGB value of the color used to draw the - text. -* `world_pos`: World position of the waypoint. +#### Maximum drop level +Suggests the maximum level of node, when dug with the tool, that will drop +it's useful item. (e.g. iron ore to drop a lump of iron). -Representations of simple things --------------------------------- +This is not automated; it is the responsibility of the node definition +to implement this. -### Position/vector +#### Uses +Determines how many uses the tool has when it is used for digging a node, +of this group, of the maximum level. For lower leveled nodes, the use count +is multiplied by `3^leveldiff`. - {x=num, y=num, z=num} +* `uses=10, leveldiff=0`: actual uses: 10 +* `uses=10, leveldiff=1`: actual uses: 30 +* `uses=10, leveldiff=2`: actual uses: 90 -For helper functions see "Spatial Vectors". +#### Maximum level +Tells what is the maximum level of a node of this group that the tool will +be able to dig. -### `pointed_thing` -* `{type="nothing"}` -* `{type="node", under=pos, above=pos}` -* `{type="object", ref=ObjectRef}` +#### Digging times +List of digging times for different ratings of the group, for nodes of the +maximum level. -Flag Specifier Format ---------------------- -Flags using the standardized flag specifier format can be specified in either -of two ways, by string or table. +For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would +result in the tool to be able to dig nodes that have a rating of `2` or `3` +for this group, and unable to dig the rating `1`, which is the toughest. +Unless there is a matching group that enables digging otherwise. -The string format is a comma-delimited set of flag names; whitespace and -unrecognized flag fields are ignored. Specifying a flag in the string sets the -flag, and specifying a flag prefixed by the string `"no"` explicitly -clears the flag from whatever the default may be. +If the result digging time is 0, a delay of 0.15 seconds is added between +digging nodes; If the player releases LMB after digging, this delay is set to 0, +i.e. players can more quickly click the nodes away instead of holding LMB. -In addition to the standard string flag format, the schematic flags field can -also be a table of flag names to boolean values representing whether or not the -flag is set. Additionally, if a field with the flag name prefixed with `"no"` -is present, mapped to a boolean of any value, the specified flag is unset. +#### Damage groups +List of damage for groups of entities. See "Entity damage mechanism". -E.g. A flag field of value +#### Example definition of the capabilities of a tool - {place_center_x = true, place_center_y=false, place_center_z=true} + tool_capabilities = { + full_punch_interval=1.5, + max_drop_level=1, + groupcaps={ + crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} + } + damage_groups = {fleshy=2}, + } -is equivalent to +This makes the tool be able to dig nodes that fulfil both of these: - {place_center_x = true, noplace_center_y=true, place_center_z=true} +* Have the `crumbly` group +* Have a `level` group less or equal to `2` -which is equivalent to +Table of resulting digging times: - "place_center_x, noplace_center_y, place_center_z" + crumbly 0 1 2 3 4 <- level + -> 0 - - - - - + 1 0.80 1.60 1.60 - - + 2 0.60 1.20 1.20 - - + 3 0.40 0.80 0.80 - - -or even + level diff: 2 1 0 -1 -2 - "place_center_x, place_center_z" +Table of resulting tool uses: -since, by default, no schematic attributes are set. + -> 0 - - - - - + 1 180 60 20 - - + 2 180 60 20 - - + 3 180 60 20 - - -Items ------ +**Notes**: -### Item types -There are three kinds of items: nodes, tools and craftitems. +* At `crumbly==0`, the node is not diggable. +* At `crumbly==3`, the level difference digging time divider kicks in and makes + easy nodes to be quickly breakable. +* At `level > 2`, the node is not diggable, because it's `level > maxlevel` -* Node (`register_node`): A node from the world. -* Tool (`register_tool`): A tool/weapon that can dig and damage - things according to `tool_capabilities`. -* Craftitem (`register_craftitem`): A miscellaneous item. +Entity damage mechanism +----------------------- +Damage calculation: -### 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. + damage = 0 + foreach group in cap.damage_groups: + damage += cap.damage_groups[group] * limit(actual_interval / + cap.full_punch_interval, 0.0, 1.0) + * (object.armor_groups[group] / 100.0) + -- Where object.armor_groups[group] is 0 for inexistent values + return damage -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. +Client predicts damage based on damage groups. Because of this, it is able to +give an immediate response when an entity is damaged or dies; the response is +pre-defined somehow (e.g. by defining a sprite animation) (not implemented; +TODO). +Currently a smoke puff will appear when an entity dies. -### Item formats -Items and item stacks can exist in three formats: Serializes, table format -and `ItemStack`. +The group `immortal` completely disables normal damage. -#### Serialized -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: +Entities can define a special armor group, which is `punch_operable`. This +group 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. - [[ ]] +On the Lua side, every punch calls: -Examples: + entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage) -* `'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 +This should never be called directly, because damage is usually not handled by +the entity itself. -#### Table format -Examples: +* `puncher` is the object performing the punch. Can be `nil`. Should never be + accessed unless absolutely required, to encourage interoperability. +* `time_from_last_punch` is time from last punch (by `puncher`) or `nil`. +* `tool_capabilities` can be `nil`. +* `direction` is a unit vector, pointing from the source of the punch to + the punched object. +* `damage` damage that will be done to entity +Return value of this function will determine if damage is done by this function +(retval true) or shall be done by engine (retval false) -5 dirt nodes: +To punch an entity/object in Lua, call: - {name="default:dirt", count=5, wear=0, metadata=""} + object:punch(puncher, time_from_last_punch, tool_capabilities, direction) -A wooden pick about 1/3 worn out: +* Return value is tool wear. +* Parameters are equal to the above callback. +* If `direction` equals `nil` and `puncher` does not equal `nil`, `direction` + will be automatically filled in based on the location of `puncher`. - {name="default:pick_wood", count=1, wear=21323, metadata=""} +Node Metadata +------------- +The instance of a node in the world normally only contains the three values +mentioned in "Nodes". However, it is possible to insert extra data into a +node. It is called "node metadata"; See `NodeMetaRef`. -An apple: +Node metadata contains two things: - {name="default:apple", count=1, wear=0, metadata=""} +* A key-value store +* An inventory -#### `ItemStack` -A native C++ format with many helper methods. Useful for converting -between formats. See the Class reference section for details. +Some of the values in the key-value store are handled specially: -When an item must be passed to a function, it can usually be in any of -these formats. +* `formspec`: Defines a right-click inventory menu. See "Formspec". +* `infotext`: Text shown on the screen when the node is pointed at +Example stuff: -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 -the thing without actually knowing what the thing is. - -### Usage -Groups are stored in a table, having the group names with keys and the -group ratings as values. For example: + local meta = minetest.get_meta(pos) + meta:set_string("formspec", + "size[8,9]".. + "list[context;main;0,0;8,4;]".. + "list[current_player;main;0,5;8,4;]") + meta:set_string("infotext", "Chest"); + local inv = meta:get_inventory() + inv:set_size("main", 8*4) + print(dump(meta:to_table())) + meta:from_table({ + inventory = { + main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", + [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", + [10] = "", [11] = "", [12] = "", [13] = "", + [14] = "default:cobble", [15] = "", [16] = "", [17] = "", + [18] = "", [19] = "", [20] = "default:cobble", [21] = "", + [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", + [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", + [32] = ""} + }, + fields = { + formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", + infotext = "Chest" + } + }) - groups = {crumbly=3, soil=1} - -- ^ Default dirt +Item Metadata +------------- +Item stacks can store metadata too. See `ItemStackMetaRef`. - groups = {crumbly=2, soil=1, level=2, outerspace=1} - -- ^ A more special dirt-kind of thing +Item metadata only contains a key-value store. -Groups always have a rating associated with them. If there is no -useful meaning for a rating for an enabled group, it shall be `1`. +Some of the values in the key-value store are handled specially: -When not defined, the rating of a group defaults to `0`. Thus when you -read groups, you must interpret `nil` and `0` as the same value, `0`. +* `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. -You can read the rating of a group for an item or a node by using +Example stuff: - minetest.get_item_group(itemname, groupname) + local meta = stack:get_meta() + meta:set_string("key", "value") + print(dump(meta:to_table())) -### Groups of items -Groups of items can define what kind of an item it is (e.g. wool). +Formspec +-------- +Formspec defines a menu. Currently not much else than inventories are +supported. It is a string, with a somewhat strange format. -### Groups of nodes -In addition to the general item things, groups are used to define whether -a node is destroyable and how long it takes to destroy by a tool. +Spaces and newlines can be inserted between the blocks, as is used in the +examples. -### Groups of entities -For entities, groups are, as of now, used only for calculating damage. -The rating is the percentage of damage caused by tools with this damage group. -See "Entity damage mechanism". +WARNING: Minetest allows you to add elements to every single formspec instance +using player:set_formspec_prepend(), which may be the reason backgrounds are +appearing when you don't expect them to. See `no_prepend[]` - object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) - object.set_armor_groups({fleshy=30, cracky=80}) +### Examples -### Groups of tools -Groups in tools define which groups of nodes and entities they are -effective towards. +#### Chest -### Groups in crafting recipes -An example: Make meat soup from any meat, any water and any bowl: + size[8,9] + list[context;main;0,0;8,4;] + list[current_player;main;0,5;8,4;] - { - output = 'food:meat_soup_raw', - recipe = { - {'group:meat'}, - {'group:water'}, - {'group:bowl'}, - }, - -- preserve = {'group:bowl'}, -- Not implemented yet (TODO) - } +#### Furnace -Another example: Make red wool from white wool and red dye: + size[8,9] + list[context;fuel;2,3;1,1;] + list[context;src;2,1;1,1;] + list[context;dst;5,1;2,2;] + list[current_player;main;0,5;8,4;] - { - type = 'shapeless', - output = 'wool:red', - recipe = {'wool:white', 'group:dye,basecolor_red'}, - } +#### Minecraft-like player inventory -### 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 - from destroyed nodes. - * `0` is something that is directly accessible at the start of gameplay - * There is no upper limit -* `dig_immediate`: (player can always pick up node without reducing tool wear) - * `2`: the node always gets the digging time 0.5 seconds (rail, sign) - * `3`: the node always gets the digging time 0 seconds (torch) -* `disable_jump`: Player (and possibly other things) cannot jump from node -* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)` -* `bouncy`: value is bounce speed in percent -* `falling_node`: if there is no walkable block under the node it will fall -* `attached_node`: if the node under it is not a walkable block the node will be - dropped as an item. If the node is wallmounted the wallmounted direction is - checked. -* `soil`: saplings will grow on nodes in this group -* `connect_to_raillike`: makes nodes of raillike drawtype with same group value - connect to each other -* `slippery`: Players and items will slide on the node. - Slipperiness rises steadily with `slippery` value, starting at 1. + size[8,7.5] + image[1,0.6;1,2;player.png] + list[current_player;main;0,3.5;8,4;] + list[current_player;craft;3,0;3,3;] + list[current_player;craftpreview;7,1;1,1;] +### Elements -### Known damage and digging time defining groups -* `crumbly`: dirt, sand -* `cracky`: tough but crackable stuff like stone. -* `snappy`: something that can be cut using fine tools; e.g. leaves, small - plants, wire, sheets of metal -* `choppy`: something that can be cut using force; e.g. trees, wooden planks -* `fleshy`: Living things like animals and the player. This could imply - some blood effects when hitting. -* `explody`: Especially prone to explosions -* `oddly_breakable_by_hand`: - Can be added to nodes that shouldn't logically be breakable by the - hand but are. Somewhat similar to `dig_immediate`, but times are more - like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the - speed of a tool if the tool can dig at a faster speed than this - suggests for the hand. +#### `size[,,]` +* Define the size of the menu in inventory slots +* `fixed_size`: `true`/`false` (optional) +* deprecated: `invsize[,;]` -### Examples of custom groups -Item groups are often used for defining, well, _groups of items_. +#### `position[,]` +* Must be used after `size` element. +* Defines the position on the game window of the formspec's `anchor` point. +* For X and Y, 0.0 and 1.0 represent opposite edges of the game window, + for example: + * [0.0, 0.0] sets the position to the top left corner of the game window. + * [1.0, 1.0] sets the position to the bottom right of the game window. +* Defaults to the center of the game window [0.5, 0.5]. -* `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 - hearts. -* `flammable`: can be set on fire. Rating might define the intensity of the - fire, affecting e.g. the speed of the spreading of an open fire. -* `wool`: any wool (any origin, any color) -* `metal`: any metal -* `weapon`: any weapon -* `heavy`: anything considerably heavy +#### `anchor[,]` +* Must be used after both `size` and `position` (if present) elements. +* Defines the location of the anchor point within the formspec. +* For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, + for example: + * [0.0, 1.0] sets the anchor to the bottom left corner of the formspec. + * [1.0, 0.0] sets the anchor to the top right of the formspec. +* Defaults to the center of the formspec [0.5, 0.5]. -### Digging time calculation specifics -Groups such as `crumbly`, `cracky` and `snappy` are used for this -purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies -faster digging time. +* `position` and `anchor` elements need suitable values to avoid a formspec + extending off the game window due to particular game window sizes. -The `level` group is used to limit the toughness of nodes a tool can dig -and to scale the digging times / damage to a greater extent. +#### `no_prepend[]` +* Must be used after the `size`, `position`, and `anchor` elements (if present). +* Disables player:set_formspec_prepend() from applying to this formspec. -**Please do understand this**, otherwise you cannot use the system to it's -full potential. +#### `container[,]` +* Start of a container block, moves all physical elements in the container by + (X, Y). +* Must have matching `container_end` +* Containers can be nested, in which case the offsets are added + (child containers are relative to parent containers) -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. +#### `container_end[]` +* End of a container, following elements are no longer relative to this + container. -#### Tools definition -Tools define: +#### `list[;;,;,;]` +* Show an inventory list -* Full punch interval -* Maximum drop level -* For an arbitrary list of groups: - * Uses (until the tool breaks) - * Maximum level (usually `0`, `1`, `2` or `3`) - * Digging times - * Damage groups +#### `list[;;,;,;]` +* Show an inventory list -#### Full punch interval -When used as a weapon, the tool will do full damage if this time is spent -between punches. If e.g. half the time is spent, the tool will do half -damage. +#### `listring[;]` +* Allows to create a ring of inventory lists +* Shift-clicking on items in one element of the ring + will send them to the next inventory list inside the ring +* The first occurrence of an element inside the ring will + determine the inventory where items will be sent to -#### Maximum drop level -Suggests the maximum level of node, when dug with the tool, that will drop -it's useful item. (e.g. iron ore to drop a lump of iron). +#### `listring[]` +* Shorthand for doing `listring[;]` + for the last two inventory lists added by list[...] -This is not automated; it is the responsibility of the node definition -to implement this. +#### `listcolors[;]` +* Sets background color of slots as `ColorString` +* Sets background color of slots on mouse hovering -#### Uses -Determines how many uses the tool has when it is used for digging a node, -of this group, of the maximum level. For lower leveled nodes, the use count -is multiplied by `3^leveldiff`. +#### `listcolors[;;]` +* Sets background color of slots as `ColorString` +* Sets background color of slots on mouse hovering +* Sets color of slots border -* `uses=10, leveldiff=0`: actual uses: 10 -* `uses=10, leveldiff=1`: actual uses: 30 -* `uses=10, leveldiff=2`: actual uses: 90 +#### `listcolors[;;;;]` +* Sets background color of slots as `ColorString` +* Sets background color of slots on mouse hovering +* Sets color of slots border +* Sets default background color of tooltips +* Sets default font color of tooltips -#### Maximum level -Tells what is the maximum level of a node of this group that the tool will -be able to dig. +#### `tooltip[;;;]` +* Adds tooltip for an element +* `` tooltip background color as `ColorString` (optional) +* `` tooltip font color as `ColorString` (optional) -#### Digging times -List of digging times for different ratings of the group, for nodes of the -maximum level. +#### `image[,;,;]` +* Show an image +* Position and size units are inventory slots -For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would -result in the tool to be able to dig nodes that have a rating of `2` or `3` -for this group, and unable to dig the rating `1`, which is the toughest. -Unless there is a matching group that enables digging otherwise. +#### `item_image[,;,;]` +* Show an inventory image of registered item/node +* Position and size units are inventory slots -If the result digging time is 0, a delay of 0.15 seconds is added between -digging nodes; If the player releases LMB after digging, this delay is set to 0, -i.e. players can more quickly click the nodes away instead of holding LMB. +#### `bgcolor[;]` +* Sets background color of formspec as `ColorString` +* If `true`, the background color is drawn fullscreen (does not effect the size + of the formspec). -#### Damage groups -List of damage for groups of entities. See "Entity damage mechanism". +#### `background[,;,;]` +* Use a background. Inventory rectangles are not drawn then. +* Position and size units are inventory slots +* Example for formspec 8x4 in 16x resolution: image shall be sized + 8 times 16px times 4 times 16px. -#### Example definition of the capabilities of a tool +#### `background[,;,;;]` +* Use a background. Inventory rectangles are not drawn then. +* Position and size units are inventory slots +* Example for formspec 8x4 in 16x resolution: + image shall be sized 8 times 16px times 4 times 16px +* If `true` the background is clipped to formspec size + (`x` and `y` are used as offset values, `w` and `h` are ignored) - tool_capabilities = { - full_punch_interval=1.5, - max_drop_level=1, - groupcaps={ - crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} - } - damage_groups = {fleshy=2}, - } +#### `pwdfield[,;,;;