X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=de0517d42d6a75b41875d8b08d8dbe0d58ddb6fd;hb=ab1fe80150a8031fb702b9ff776db2db4dea89a4;hp=029c53616e2f20bcc095bcecf1d86b2275ec89c8;hpb=0f25fa7af655b98fa401176a523f269c843d1943;p=minetest.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 029c53616..de0517d42 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -35,19 +35,16 @@ the `init.lua` scripts in a shared environment. Paths ----- -* `RUN_IN_PLACE=1` (Windows release, local build) - * `$path_user`: `` - * `$path_share`: `` -* `RUN_IN_PLACE=0`: (Linux release) - * `$path_share`: - * Linux: `/usr/share/minetest` - * Windows: `/minetest-0.4.x` - * `$path_user`: - * Linux: `$HOME/.minetest` - * Windows: `C:/users//AppData/minetest` (maybe) - +Minetest keeps and looks for files mostly in two paths. `path_share` or `path_user`. +`path_share` contains possibly read-only content for the engine (incl. games and mods). +`path_user` contains mods or games installed by the user but also the users +worlds or settings. +With a local build (`RUN_IN_PLACE=1`) `path_share` and `path_user` both point to +the build directory. For system-wide builds on Linux the share path is usually at +`/usr/share/minetest` while the user path resides in `.minetest` in the home directory. +Paths on other operating systems will differ. Games ===== @@ -62,7 +59,8 @@ Where `` is unique to each game. The game directory can contain the following files: * `game.conf`, with the following keys: - * `name`: Required, a human readable title to address the game, e.g. `name = Minetest`. + * `title`: Required, a human-readable title to address the game, e.g. `title = Minetest Game`. + * `name`: (Deprecated) same as title. * `description`: Short description to be shown in the content tab * `allowed_mapgens = ` e.g. `allowed_mapgens = v5,v6,flat` @@ -87,6 +85,8 @@ The game directory can contain the following files: (this does not work for `enable_server`). Only these settings are supported: `enable_damage`, `creative_mode`, `enable_server`. + * `map_persistent`: Specifies whether newly created worlds should use + a persistent map backend. Defaults to `true` (= "sqlite3") * `author`: The author of the game. It only appears when downloaded from ContentDB. * `release`: Ignore this: Should only ever be set by ContentDB, as it is @@ -213,8 +213,6 @@ A `Settings` file that provides meta information about the mod. internal ID used to track versions. * `title`: A human-readable title to address the mod. -Note: to support 0.4.x, please also provide depends.txt. - ### `screenshot.png` A screenshot shown in the mod manager within the main menu. It should @@ -303,8 +301,8 @@ Any mod can redefine `experimental:tnt` by using the name :experimental:tnt -when registering it. That mod is required to have `experimental` as a -dependency. +when registering it. For this to work correctly, that mod must have +`experimental` as a dependency. @@ -345,9 +343,9 @@ of the game's nodes are to be used for core mapgen generation. For example: #### Essential aliases -* mapgen_stone -* mapgen_water_source -* mapgen_river_water_source +* `mapgen_stone` +* `mapgen_water_source` +* `mapgen_river_water_source` `mapgen_river_water_source` is required for mapgens with sloping rivers where it is necessary to have a river liquid node with a short `liquid_range` and @@ -355,50 +353,56 @@ it is necessary to have a river liquid node with a short `liquid_range` and #### Optional aliases -* mapgen_lava_source +* `mapgen_lava_source` Fallback lava node used if cave liquids are not defined in biome definitions. -Deprecated for non-V6 mapgens, define cave liquids in biome definitions instead. +Deprecated, define cave liquids in biome definitions instead. -* mapgen_cobble +* `mapgen_cobble` Fallback node used if dungeon nodes are not defined in biome definitions. -Deprecated for non-V6 mapgens, define dungeon nodes in biome definitions instead. - -### Aliases needed for Mapgen V6 - -* mapgen_stone -* mapgen_water_source -* mapgen_lava_source -* mapgen_dirt -* mapgen_dirt_with_grass -* mapgen_sand -* mapgen_gravel -* mapgen_desert_stone -* mapgen_desert_sand -* mapgen_dirt_with_snow -* mapgen_snowblock -* mapgen_snow -* mapgen_ice - -* mapgen_tree -* mapgen_leaves -* mapgen_apple -* mapgen_jungletree -* mapgen_jungleleaves -* mapgen_junglegrass -* mapgen_pine_tree -* mapgen_pine_needles - -* mapgen_cobble -* mapgen_stair_cobble -* mapgen_mossycobble -* mapgen_stair_desert_stone +Deprecated, define dungeon nodes in biome definitions instead. + +### Aliases for Mapgen V6 + +#### Essential + +* `mapgen_stone` +* `mapgen_water_source` +* `mapgen_lava_source` +* `mapgen_dirt` +* `mapgen_dirt_with_grass` +* `mapgen_sand` + +* `mapgen_tree` +* `mapgen_leaves` +* `mapgen_apple` + +* `mapgen_cobble` + +#### Optional + +* `mapgen_gravel` (falls back to stone) +* `mapgen_desert_stone` (falls back to stone) +* `mapgen_desert_sand` (falls back to sand) +* `mapgen_dirt_with_snow` (falls back to dirt_with_grass) +* `mapgen_snowblock` (falls back to dirt_with_grass) +* `mapgen_snow` (not placed if missing) +* `mapgen_ice` (falls back to water_source) + +* `mapgen_jungletree` (falls back to tree) +* `mapgen_jungleleaves` (falls back to leaves) +* `mapgen_junglegrass` (not placed if missing) +* `mapgen_pine_tree` (falls back to tree) +* `mapgen_pine_needles` (falls back to leaves) + +* `mapgen_stair_cobble` (falls back to cobble) +* `mapgen_mossycobble` (falls back to cobble) +* `mapgen_stair_desert_stone` (falls back to desert_stone) ### Setting the node used in Mapgen Singlenode -By default the world is filled with air nodes. To set a different node use, for -example: +By default the world is filled with air nodes. To set a different node use e.g.: minetest.register_alias("mapgen_singlenode", "default:stone") @@ -419,6 +423,9 @@ stripping out the file extension: * e.g. `foomod_foothing.png` * e.g. `foomod_foothing` +Supported texture formats are PNG (`.png`), JPEG (`.jpg`), Bitmap (`.bmp`) +and Targa (`.tga`). +Since better alternatives exist, the latter two may be removed in the future. Texture modifiers ----------------- @@ -753,6 +760,17 @@ appropriate `paramtype2`: first (= 0 + 1) pixel will be picked from the palette. * `param2 = 35` is 1 * 32 + 3, so the rotation is 3 and the second (= 1 + 1) pixel will be picked from the palette. +* `paramtype2 = "color4dir"` for nodes which use the first + six bits of `param2` for palette indexing. The remaining + two bits are describing rotation, as in `4dir` paramtype2. + Division by 4 yields the palette index (without stretching the + palette). These nodes can have 64 different colors, and the + palette should contain 64 pixels. + Examples: + * `param2 = 17` is 4 * 4 + 1, so the rotation is 1 and the + fifth (= 4 + 1) pixel will be picked from the palette. + * `param2 = 35` is 8 * 4 + 3, so the rotation is 3 and the + ninth (= 8 + 1) pixel will be picked from the palette. To colorize a node on the map, set its `param2` value (according to the node's paramtype2). @@ -903,13 +921,13 @@ Examples of sound parameter tables: { pos = {x = 1, y = 2, z = 3}, gain = 1.0, -- default - max_hear_distance = 32, -- default, uses an euclidean metric + max_hear_distance = 32, -- default, uses a Euclidean metric } -- Play connected to an object, looped { object = , gain = 1.0, -- default - max_hear_distance = 32, -- default, uses an euclidean metric + max_hear_distance = 32, -- default, uses a Euclidean metric loop = true, } -- Play at a location, heard by anyone *but* the given player @@ -963,7 +981,7 @@ These sound files are played back by the engine if provided. * `player_falling_damage`: Played when the local player takes damage by falling (gain = 0.5) * `player_jump`: Played when the local player jumps - * `default_dig_`: Default node digging sound + * `default_dig_`: Default node digging sound (gain = 0.5) (see node sound definition for details) Registered definitions @@ -978,18 +996,13 @@ existence before trying to access the fields. Example: -All nodes register with `minetest.register_node` get added to the table +All nodes registered with `minetest.register_node` get added to the table `minetest.registered_nodes`. -If you want to check the drawtype of a node, you could do: +If you want to check the drawtype of a node, you could do it like this: - local function get_nodedef_field(nodename, fieldname) - if not minetest.registered_nodes[nodename] then - return nil - end - return minetest.registered_nodes[nodename][fieldname] - end - local drawtype = get_nodedef_field(nodename, "drawtype") + local def = minetest.registered_nodes[nodename] + local drawtype = def and def.drawtype @@ -1058,18 +1071,39 @@ The function of `param2` is determined by `paramtype2` in node definition. * Supported drawtypes: "torchlike", "signlike", "plantlike", "plantlike_rooted", "normal", "nodebox", "mesh" * The rotation of the node is stored in `param2` + * Node is 'mounted'/facing towards one of 6 directions * You can make this value by using `minetest.dir_to_wallmounted()` * Values range 0 - 5 * The value denotes at which direction the node is "mounted": 0 = y+, 1 = y-, 2 = x+, 3 = x-, 4 = z+, 5 = z- + * By default, on placement the param2 is automatically set to the + appropriate rotation, depending on which side was pointed at * `paramtype2 = "facedir"` * Supported drawtypes: "normal", "nodebox", "mesh" - * The rotation of the node is stored in `param2`. Furnaces and chests are - rotated this way. Can be made by using `minetest.dir_to_facedir()`. + * The rotation of the node is stored in `param2`. + * Node is rotated around face and axis; 24 rotations in total. + * Can be made by using `minetest.dir_to_facedir()`. + * Chests and furnaces can be rotated that way, and also 'flipped' * Values range 0 - 23 * facedir / 4 = axis direction: 0 = y+, 1 = z+, 2 = z-, 3 = x+, 4 = x-, 5 = y- - * facedir modulo 4 = rotation around that axis + * The node is rotated 90 degrees around the X or Z axis so that its top face + points in the desired direction. For the y- direction, it's rotated 180 + degrees around the Z axis. + * facedir modulo 4 = left-handed rotation around the specified axis, in 90° steps. + * By default, on placement the param2 is automatically set to the + horizontal direction the player was looking at (values 0-3) + * Special case: If the node is a connected nodebox, the nodebox + will NOT rotate, only the textures will. +* `paramtype2 = "4dir"` + * Supported drawtypes: "normal", "nodebox", "mesh" + * The rotation of the node is stored in `param2`. + * Allows node to be rotated horizontally, 4 rotations in total + * Can be made by using `minetest.dir_to_fourdir()`. + * Chests and furnaces can be rotated that way, but not flipped + * Values range 0 - 3 + * 4dir modulo 4 = rotation + * Otherwise, behavior is identical to facedir * `paramtype2 = "leveled"` * Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted". * Leveled nodebox: @@ -1091,7 +1125,7 @@ The function of `param2` is determined by `paramtype2` in node definition. optional modifiers of the "plant". `param2` is a bitfield. * Bits 0 to 2 select the shape. Use only one of the values below: - * 0 = a "x" shaped plant (ordinary plant) + * 0 = an "x" shaped plant (ordinary plant) * 1 = a "+" shaped plant (just rotated 45 degrees) * 2 = a "*" shaped plant with 3 faces instead of 2 * 3 = a "#" shaped plant with 4 faces instead of 2 @@ -1112,6 +1146,10 @@ The function of `param2` is determined by `paramtype2` in node definition. * Same as `facedir`, but with colors. * The first three bits of `param2` tells which color is picked from the palette. The palette should have 8 pixels. +* `paramtype2 = "color4dir"` + * Same as `facedir`, but with colors. + * The first six bits of `param2` tells which color is picked from the + palette. The palette should have 64 pixels. * `paramtype2 = "colorwallmounted"` * Same as `wallmounted`, but with colors. * The first five bits of `param2` tells which color is picked from the @@ -1153,12 +1191,14 @@ Look for examples in `games/devtest` or `games/minetest_game`. * The cubic source node for a liquid. * Faces bordering to the same node are never rendered. * Connects to node specified in `liquid_alternative_flowing`. + * You *must* set `liquid_alternative_source` to the node's own name. * Use `backface_culling = false` for the tiles you want to make visible when inside the node. * `flowingliquid` * The flowing version of a liquid, appears with various heights and slopes. * Faces bordering to the same node are never rendered. * Connects to node specified in `liquid_alternative_source`. + * You *must* set `liquid_alternative_flowing` to the node's own name. * Node textures are defined with `special_tiles` where the first tile is for the top and bottom faces and the second tile is for the side faces. @@ -1191,7 +1231,7 @@ Look for examples in `games/devtest` or `games/minetest_game`. used to compensate for how `glasslike` reduces visual thickness. * `torchlike` * A single vertical texture. - * If `paramtype2="[color]wallmounted": + * If `paramtype2="[color]wallmounted"`: * If placed on top of a node, uses the first texture specified in `tiles`. * If placed against the underside of a node, uses the second texture specified in `tiles`. @@ -1203,7 +1243,7 @@ Look for examples in `games/devtest` or `games/minetest_game`. * `signlike` * A single texture parallel to, and mounted against, the top, underside or side of a node. - * If `paramtype2="[color]wallmounted", it rotates according to `param2` + * If `paramtype2="[color]wallmounted"`, it rotates according to `param2` * If `paramtype2="none"`, it will always be on the floor. * `plantlike` * Two vertical and diagonal textures at right-angles to each other. @@ -1285,7 +1325,7 @@ A nodebox is defined as any of: wall_side = box } { - -- A node that has optional boxes depending on neighbouring nodes' + -- A node that has optional boxes depending on neighboring nodes' -- presence and type. See also `connects_to`. type = "connected", fixed = box OR {box1, box2, ...} @@ -1296,7 +1336,7 @@ A nodebox is defined as any of: connect_back = box OR {box1, box2, ...} connect_right = box OR {box1, box2, ...} -- The following `disconnected_*` boxes are the opposites of the - -- `connect_*` ones above, i.e. when a node has no suitable neighbour + -- `connect_*` ones above, i.e. when a node has no suitable neighbor -- on the respective side, the corresponding disconnected box is drawn. disconnected_top = box OR {box1, box2, ...} disconnected_bottom = box OR {box1, box2, ...} @@ -1304,9 +1344,9 @@ A nodebox is defined as any of: disconnected_left = box OR {box1, box2, ...} disconnected_back = box OR {box1, box2, ...} disconnected_right = box OR {box1, box2, ...} - disconnected = box OR {box1, box2, ...} -- when there is *no* neighbour + disconnected = box OR {box1, box2, ...} -- when there is *no* neighbor disconnected_sides = box OR {box1, box2, ...} -- when there are *no* - -- neighbours to the sides + -- neighbors to the sides } A `box` is defined as: @@ -1341,7 +1381,7 @@ clients and handled by many parts of the engine. A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks (80x80x80 nodes) and is the volume of world generated in one operation by the map generator. -The size in mapblocks has been chosen to optimise map generation. +The size in mapblocks has been chosen to optimize map generation. Coordinates ----------- @@ -1388,11 +1428,10 @@ HUD element types ----------------- The position field is used for all element types. - To account for differing resolutions, the position coordinates are the percentage of the screen, ranging in value from `0` to `1`. -The name field is not yet used, but should contain a description of what the +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. @@ -1425,10 +1464,9 @@ Supports negative values. By convention, the following values are recommended: * 100: Temporary text messages or notification icons * 1000: Full-screen effects such as full-black screen or credits. This includes effects that cover the entire screen -* Other: If your HUD element doesn't fit into any category, pick a number - between the suggested values - +If your HUD element doesn't fit into any category, pick a number +between the suggested values Below are the specific uses for fields in each type; fields not listed for that type are ignored. @@ -1458,6 +1496,8 @@ Displays text on the HUD. * `offset`: offset in pixels from position. * `size`: size of the text. The player-set font size is multiplied by size.x (y value isn't used). +* `style`: determines font style + Bitfield with 1 = bold, 2 = italic, 4 = monospace ### `statbar` @@ -1480,7 +1520,7 @@ Displays a horizontal bar made up of half-images with an optional background. * `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` +* `direction`: Direction the list will be displayed in * `offset`: offset in pixels from position. ### `waypoint` @@ -1524,7 +1564,7 @@ Displays an image oriented or translated according to current heading direction. * `text`: The name of the texture to use. * `alignment`: The alignment of the image. * `offset`: Offset in pixels from position. -* `dir`: How the image is rotated/translated: +* `direction`: How the image is rotated/translated: * 0 - Rotate as heading direction * 1 - Rotate in reverse direction * 2 - Translate as landscape direction @@ -1571,6 +1611,8 @@ Exact pointing location (currently only `Raycast` supports these fields): * `pointed_thing.intersection_normal`: Unit vector, points outwards of the selected selection box. This specifies which face is pointed at. Is a null vector `vector.zero()` when the pointer is inside the selection box. + For entities with rotated selection boxes, this will be rotated properly + by the entity's rotation - it will always be in absolute world space. @@ -1626,7 +1668,7 @@ Item types There are three kinds of items: nodes, tools and craftitems. * Node: Placeable item form of a node in the world's voxel grid -* Tool: Has a changable wear property but cannot be stacked +* Tool: Has a changeable wear property but cannot be stacked * Craftitem: Has no special properties Every registered node (the voxel in the world) has a corresponding @@ -1651,7 +1693,7 @@ Amount and wear --------------- All item stacks have an amount between 0 and 65535. It is 1 by -default. Tool item stacks can not have an amount greater than 1. +default. Tool item stacks cannot have an amount greater than 1. Tools use a wear (damage) value ranging from 0 to 65535. The value 0 is the default and is used for unworn tools. The values @@ -1672,10 +1714,16 @@ these formats. ### 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: +1-4 components: - [[ ]] +1. Full item identifier ("item name") +2. Optional amount +3. Optional wear value +4. Optional item metadata + +Syntax: + + [[ [ ]]] Examples: @@ -1683,6 +1731,26 @@ Examples: * `"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 +* `[[default:pick_wood 1 21323 "\u0001description\u0002My worn out pick\u0003"]]`: + * a wooden pickaxe from the `default` mod, + * amount must be 1 (pickaxe is a tool), ca. 1/3 worn out (it's a tool), + * with the `description` field set to `"My worn out pick"` in its metadata +* `[[default:dirt 5 0 "\u0001description\u0002Special dirt\u0003"]]`: + * analogous to the above example + * note how the wear is set to `0` as dirt is not a tool + +You should ideally use the `ItemStack` format to build complex item strings +(especially if they use item metadata) +without relying on the serialization format. Example: + + local stack = ItemStack("default:pick_wood") + stack:set_wear(21323) + stack:get_meta():set_string("description", "My worn out pick") + local itemstring = stack:to_string() + +Additionally the methods `minetest.itemstring_with_palette(item, palette_index)` +and `minetest.itemstring_with_color(item, colorstring)` may be used to create +item strings encoding color information in their metadata. ### Table format @@ -1757,8 +1825,8 @@ For entities, groups are, as of now, used only for calculating damage. The rating is the percentage of damage caused by items with this damage group. See [Entity damage mechanism]. - object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) - object.set_armor_groups({fleshy=30, cracky=80}) + object:get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) + object:set_armor_groups({fleshy=30, cracky=80}) Groups of tool capabilities --------------------------- @@ -1769,7 +1837,24 @@ are effective towards. Groups in crafting recipes -------------------------- -An example: Make meat soup from any meat, any water and any bowl: +In crafting recipes, you can specify a group as an input item. +This means that any item in that group will be accepted as input. + +The basic syntax is: + + "group:" + +For example, `"group:meat"` will accept any item in the `meat` group. + +It is also possible to require an input item to be in +multiple groups at once. The syntax for that is: + + "group:,,(...)," + +For example, `"group:leaves,birch,trimmed"` accepts any item which is member +of *all* the groups `leaves` *and* `birch` *and* `trimmed`. + +An example recipe: Craft a raw meat soup from any meat, any water and any bowl: { output = "food:meat_soup_raw", @@ -1778,10 +1863,11 @@ An example: Make meat soup from any meat, any water and any bowl: {"group:water"}, {"group:bowl"}, }, - -- preserve = {"group:bowl"}, -- Not implemented yet (TODO) } -Another example: Make red wool from white wool and red dye: +Another example: Craft red wool from white wool and red dye +(here, "red dye" is defined as any item which is member of +*both* the groups `dye` and `basecolor_red`). { type = "shapeless", @@ -1804,10 +1890,19 @@ to games. ### Node-only groups -* `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. -* `bouncy`: value is bounce speed in percent +* `attached_node`: the node is 'attached' to a neighboring node. It checks + whether the node it is attached to is walkable. If it + isn't, the node will drop as an item. + * `1`: if the node is wallmounted, the node is attached in the wallmounted + direction. Otherwise, the node is attached to the node below. + * `2`: if the node is facedir or 4dir, the facedir or 4dir direction is checked. + No effect for other nodes. + Note: The "attaching face" of this node is tile no. 5 (back face). + * `3`: the node is always attached to the node below. + * `4`: the node is always attached to the node above. +* `bouncy`: value is bounce speed in percent. + If positive, jump/sneak on floor impact will increase/decrease bounce height. + Negative value is the same bounciness, but non-controllable. * `connect_to_raillike`: makes nodes of raillike drawtype with same group value connect to each other * `dig_immediate`: Player can always pick up node without reducing tool wear @@ -1940,21 +2035,21 @@ Tool capabilities define: * Damage groups * Punch attack uses (until the tool breaks) -### Full punch interval +### Full punch interval `full_punch_interval` When used as a weapon, the item will do full damage if this time is spent between punches. If e.g. half the time is spent, the item will do half damage. -### Maximum drop level +### Maximum drop level `max_drop_level` Suggests the maximum level of node, when dug with the item, that will drop its useful item. (e.g. iron ore to drop a lump of iron). -This is not automated; it is the responsibility of the node definition -to implement this. +This value is not used in the engine; it is the responsibility of the game/mod +code to implement this. -### Uses (tools only) +### Uses `uses` (tools only) Determines how many uses the tool has when it is used for digging a node, of this group, of the maximum level. The maximum supported number of @@ -1969,17 +2064,17 @@ node's `level` group. The node cannot be dug if `leveldiff` is less than zero. For non-tools, this has no effect. -### Maximum level +### Maximum level `maxlevel` Tells what is the maximum level of a node of this group that the item will be able to dig. -### Digging times +### Digging times `times` List of digging times for different ratings of the group, for nodes of the maximum level. -For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would +For example, as a Lua table, `times={[2]=2.00, [3]=0.70}`. This would result in the item 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. @@ -2007,15 +2102,12 @@ Example definition of the capabilities of an item ------------------------------------------------- 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}, + }, } -This makes the item capable of digging nodes that fulfil both of these: +This makes the item capable of digging nodes that fulfill both of these: * Have the `crumbly` group * Have a `level` group less or equal to `2` @@ -2233,12 +2325,12 @@ player named ``. When displaying text which can contain formspec code, e.g. text set by a player, use `minetest.formspec_escape`. -For coloured text you can use `minetest.colorize`. +For colored text you can use `minetest.colorize`. Since formspec version 3, elements drawn in the order they are defined. All background elements are drawn before all other elements. -**WARNING**: do _not_ use a element name starting with `key_`; those names are +**WARNING**: do _not_ use an element name starting with `key_`; those names are reserved to pass key press events to formspec! **WARNING**: Minetest allows you to add elements to every single formspec instance @@ -2288,6 +2380,8 @@ Version History * Allow dropdown indexing events * Formspec version 5 (5.5.0): * Added padding[] element +* Formspec version 6 (5.6.0): + * Add nine-slice images, animated_image, and fgimg_middle Elements -------- @@ -2410,7 +2504,7 @@ Elements ### `listring[;]` -* Allows to create a ring of inventory lists +* Appends to an internal 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 @@ -2452,20 +2546,25 @@ Elements * `bgcolor` tooltip background color as `ColorString` (optional) * `fontcolor` tooltip font color as `ColorString` (optional) -### `image[,;,;]` +### `image[,;,;;]` -* Show an image +* Show an image. +* `middle` (optional): Makes the image render in 9-sliced mode and defines the middle rect. + * Requires formspec version >= 6. + * See `background9[]` documentation for more information. -### `animated_image[,;,;;;;;]` +### `animated_image[,;,;;;;;;]` * Show an animated image. The image is drawn like a "vertical_frames" tile - animation (See [Tile animation definition]), but uses a frame count/duration - for simplicity + animation (See [Tile animation definition]), but uses a frame count/duration for simplicity * `name`: Element name to send when an event occurs. The event value is the index of the current frame. * `texture name`: The image to use. * `frame count`: The number of frames animating the image. * `frame duration`: Milliseconds between each frame. `0` means the frames don't advance. -* `frame start` (Optional): The index of the frame to start on. Default `1`. +* `frame start` (optional): The index of the frame to start on. Default `1`. +* `middle` (optional): Makes the image render in 9-sliced mode and defines the middle rect. + * Requires formspec version >= 6. + * See `background9[]` documentation for more information. ### `model[,;,;;;;;;;;]` @@ -2523,8 +2622,6 @@ Elements will be added to the width and height of the texture, allowing it to be used as the distance from the far end. * All numbers in middle are integers. -* Example for formspec 8x4 in 16x resolution: - image shall be sized 8 times 16px times 4 times 16px * If `auto_clip` is `true`, the background is clipped to the formspec size (`x` and `y` are used as offset values, `w` and `h` are ignored) * Available since formspec version 2 @@ -2535,7 +2632,7 @@ Elements * When enter is pressed in field, fields.key_enter_field will be sent with the name of this field. * With the old coordinate system, fields are a set height, but will be vertically - centred on `H`. With the new coordinate system, `H` will modify the height. + centered on `H`. With the new coordinate system, `H` will modify the height. * `name` is the name of the field as returned in fields to `on_receive_fields` * `label`, if not blank, will be text printed on the top left above the field * See `field_close_on_enter` to stop enter closing the formspec @@ -2546,7 +2643,7 @@ Elements * When enter is pressed in field, `fields.key_enter_field` will be sent with the name of this field. * With the old coordinate system, fields are a set height, but will be vertically - centred on `H`. With the new coordinate system, `H` will modify the height. + centered on `H`. With the new coordinate system, `H` will modify the height. * `name` is the name of the field as returned in fields to `on_receive_fields` * `label`, if not blank, will be text printed on the top left above the field * `default` is the default value of the field @@ -2609,7 +2706,7 @@ Elements * Clickable button. When clicked, fields will be sent. * With the old coordinate system, buttons are a set height, but will be vertically - centred on `H`. With the new coordinate system, `H` will modify the height. + centered on `H`. With the new coordinate system, `H` will modify the height. * `label` is the text on the button ### `image_button[,;,;;;