X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=aa58bd48e65897c1cba1998210f024dc69d4a838;hb=1d07a365528e3b947a03baba9ef986af2ecd23d1;hp=af0d35f61656f53c7caca37093ccce1551db2b18;hpb=580e7e8eb902ae2faed36b4982e7e751e35f5201;p=dragonfireclient.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index af0d35f61..aa58bd48e 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -62,11 +62,35 @@ Where `` is unique to each game. The game directory can contain the following files: * `game.conf`, with the following keys: - * `name`: Required, human readable name e.g. `name = Minetest` + * `name`: Required, a human readable title to address the game, e.g. `name = Minetest`. * `description`: Short description to be shown in the content tab + * `allowed_mapgens = ` + e.g. `allowed_mapgens = v5,v6,flat` + Mapgens not in this list are removed from the list of mapgens for the + game. + If not specified, all mapgens are allowed. * `disallowed_mapgens = ` e.g. `disallowed_mapgens = v5,v6,flat` These mapgens are removed from the list of mapgens for the game. + When both `allowed_mapgens` and `disallowed_mapgens` are + specified, `allowed_mapgens` is applied before + `disallowed_mapgens`. + * `disallowed_mapgen_settings= ` + e.g. `disallowed_mapgen_settings = mgv5_spflags` + These mapgen settings are hidden for this game in the world creation + dialog and game start menu. Add `seed` to hide the seed input field. + * `disabled_settings = ` + e.g. `disabled_settings = enable_damage, creative_mode` + These settings are hidden for this game in the "Start game" tab + and will be initialized as `false` when the game is started. + Prepend a setting name with an exclamation mark to initialize it to `true` + (this does not work for `enable_server`). + Only these settings are supported: + `enable_damage`, `creative_mode`, `enable_server`. + * `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 + an internal ID used to track versions. * `minetest.conf`: Used to set default settings when running this game. * `settingtypes.txt`: @@ -89,8 +113,16 @@ 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. +Menu music +----------- +Games can provide custom main menu music. They are put inside a `menu` +directory inside the game directory. +The music files are named `theme.ogg`. +If you want to specify multiple music files for one game, add additional +images named like `theme.$n.ogg`, with an ascending number $n starting +with 1 (max 10), and a random music file will be chosen from the provided ones. Mods ==== @@ -122,9 +154,15 @@ Mods can be put in a subdirectory, if the parent directory, which otherwise should be a mod, contains a file named `modpack.conf`. The file is a key-value store of modpack details. -* `name`: The modpack name. +* `name`: The modpack name. Allows Minetest to determine the modpack name even + if the folder is wrongly named. * `description`: Description of mod to be shown in the Mods tab of the main menu. +* `author`: The author of the modpack. It only appears when downloaded from + ContentDB. +* `release`: Ignore this: Should only ever be set by ContentDB, as it is an + internal ID used to track versions. +* `title`: A human-readable title to address the modpack. Note: to support 0.4.x, please also create an empty modpack.txt file. @@ -140,7 +178,12 @@ Mod directory structure │   ├── models │   ├── textures │   │   ├── modname_stuff.png - │   │   └── modname_something_else.png + │   │   ├── modname_stuff_normal.png + │   │   ├── modname_something_else.png + │   │   ├── subfolder_foo + │   │   │ ├── modname_more_stuff.png + │   │   │ └── another_subfolder + │   │   └── bar_subfolder │   ├── sounds │   ├── media │   ├── locale @@ -164,6 +207,11 @@ A `Settings` file that provides meta information about the mod. loaded before this mod. * `optional_depends`: A comma separated list of optional dependencies. Like a dependency, but no error if the mod doesn't exist. +* `author`: The author of the mod. It only appears when downloaded from + ContentDB. +* `release`: Ignore this: Should only ever be set by ContentDB, as it is an + 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. @@ -209,18 +257,23 @@ registered callbacks. `minetest.settings` can be used to read custom or existing settings at load time, if necessary. (See [`Settings`]) -### `models` - -Models for entities or meshnodes. - -### `textures`, `sounds`, `media` +### `textures`, `sounds`, `media`, `models`, `locale` Media files (textures, sounds, whatever) that will be transferred to the -client and will be available for use by the mod. +client and will be available for use by the mod and translation files for +the clients (see [Translations]). -### `locale` +It is suggested to use the folders for the purpose they are thought for, +eg. put textures into `textures`, translation files into `locale`, +models for entities or meshnodes into `models` et cetera. -Translation files for the clients. (See [Translations]) +These folders and subfolders can contain subfolders. +Subfolders with names starting with `_` or `.` are ignored. +If a subfolder contains a media file with the same name as a media file +in one of its parents, the parent's file is used. + +Although it is discouraged, a mod can overwrite a media file of any mod that it +depends on by supplying a file with an equal name. Naming conventions ------------------ @@ -366,11 +419,14 @@ stripping out the file extension: * e.g. `foomod_foothing.png` * e.g. `foomod_foothing` + Texture modifiers ----------------- There are various texture modifiers that can be used -to generate textures on-the-fly. +to let the client generate textures on-the-fly. +The modifiers are applied directly in sRGB colorspace, +i.e. without gamma-correction. ### Texture overlaying @@ -580,6 +636,23 @@ Result is more like what you'd expect if you put a color on top of another color, meaning white surfaces get a lot of your new color while black parts don't change very much. +#### `[png:` + +Embed a base64 encoded PNG image in the texture string. +You can produce a valid string for this by calling +`minetest.encode_base64(minetest.encode_png(tex))`, +refer to the documentation of these functions for details. +You can use this to send disposable images such as captchas +to individual clients, or render things that would be too +expensive to compose with `[combine:`. + +IMPORTANT: Avoid sending large images this way. +This is not a replacement for asset files, do not use it to do anything +that you could instead achieve by just using a file. +In particular consider `minetest.dynamic_add_media` and test whether +using other texture modifiers could result in a shorter string than +embedding a whole image, this may vary by use case. + Hardware coloring ----------------- @@ -768,7 +841,7 @@ Example (colored grass block): -- Overlay tiles: define them in the same style -- The top and bottom tile does not have overlay overlay_tiles = {"", "", - {name = "default_grass_side.png", tileable_vertical = false}}, + {name = "default_grass_side.png"}}, -- Global color, used in inventory color = "green", -- Palette in the world @@ -889,6 +962,7 @@ These sound files are played back by the engine if provided. * `player_damage`: Played when the local player takes damage (gain = 0.5) * `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 (see node sound definition for details) @@ -952,7 +1026,7 @@ The function of `param1` is determined by `paramtype` in node definition. `param1` is reserved for the engine when `paramtype != "none"`. * `paramtype = "light"` - * The value stores light with and without sun in its upper and lower 4 bits + * The value stores light with and without sun in its lower and upper 4 bits respectively. * Required by a light source node to enable spreading its light. * Required by the following drawtypes as they determine their visual @@ -976,10 +1050,13 @@ The function of `param2` is determined by `paramtype2` in node definition. * `paramtype2 = "flowingliquid"` * Used by `drawtype = "flowingliquid"` and `liquidtype = "flowing"` * The liquid level and a flag of the liquid are stored in `param2` - * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node + * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node; + see `minetest.get_node_level`, `minetest.set_node_level` and `minetest.add_node_level` + to access/manipulate the content of this field * Bit 3: If set, liquid is flowing downwards (no graphical effect) * `paramtype2 = "wallmounted"` - * Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh" + * Supported drawtypes: "torchlike", "signlike", "plantlike", + "plantlike_rooted", "normal", "nodebox", "mesh" * The rotation of the node is stored in `param2` * You can make this value by using `minetest.dir_to_wallmounted()` * Values range 0 - 5 @@ -1005,27 +1082,29 @@ The function of `param2` is determined by `paramtype2` in node definition. * The height of the 'plantlike' section is stored in `param2`. * The height is (`param2` / 16) nodes. * `paramtype2 = "degrotate"` - * Only valid for "plantlike" drawtype. The rotation of the node is stored in - `param2`. - * Values range 0 - 179. The value stored in `param2` is multiplied by two to + * Valid for `plantlike` and `mesh` drawtypes. The rotation of the node is + stored in `param2`. + * Values range 0–239. The value stored in `param2` is multiplied by 1.5 to get the actual rotation in degrees of the node. * `paramtype2 = "meshoptions"` - * Only valid for "plantlike" drawtype. The value of `param2` becomes a - bitfield which can be used to change how the client draws plantlike nodes. - * Bits 0, 1 and 2 form a mesh selector. - Currently the following meshes are choosable: + * Only valid for "plantlike" drawtype. `param2` encodes the shape and + 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) * 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 * 4 = a "#" shaped plant with 4 faces that lean outwards * 5-7 are unused and reserved for future meshes. - * Bits 3 through 7 are optional flags that can be combined and give these - effects: - * bit 3 (0x08) - Makes the plant slightly vary placement horizontally - * bit 4 (0x10) - Makes the plant mesh 1.4x larger - * bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max) - * bits 6-7 are reserved for future use. + * Bits 3 to 7 are used to enable any number of optional modifiers. + Just add the corresponding value(s) below to `param2`: + * 8 - Makes the plant slightly vary placement horizontally + * 16 - Makes the plant mesh 1.4x larger + * 32 - Moves each face randomly a small bit down (1/8 max) + * values 64 and 128 (bits 6-7) are reserved for future use. + * Example: `param2 = 0` selects a normal "x" shaped plant + * Example: `param2 = 17` selects a "+" shaped plant, 1.4x larger (1+16) * `paramtype2 = "color"` * `param2` tells which color is picked from the palette. The palette should have 256 pixels. @@ -1039,10 +1118,20 @@ The function of `param2` is determined by `paramtype2` in node definition. palette. The palette should have 32 pixels. * `paramtype2 = "glasslikeliquidlevel"` * Only valid for "glasslike_framed" or "glasslike_framed_optional" - drawtypes. - * `param2` values 0-63 define 64 levels of internal liquid, 0 being empty - and 63 being full. + drawtypes. "glasslike_framed_optional" nodes are only affected if the + "Connected Glass" setting is enabled. + * Bits 0-5 define 64 levels of internal liquid, 0 being empty and 63 being + full. + * Bits 6 and 7 modify the appearance of the frame and node faces. One or + both of these values may be added to `param2`: + * 64 - Makes the node not connect with neighbors above or below it. + * 128 - Makes the node not connect with neighbors to its sides. * Liquid texture is defined using `special_tiles = {"modname_tilename.png"}` +* `paramtype2 = "colordegrotate"` + * Same as `degrotate`, but with colors. + * The first (most-significant) three bits of `param2` tells which color + is picked from the palette. The palette should have 8 pixels. + * Remaining 5 bits store rotation in range 0–23 (i.e. in 15° steps) * `paramtype2 = "none"` * `param2` will not be used by the engine and can be used to store an arbitrary value @@ -1054,7 +1143,7 @@ Node drawtypes There are a bunch of different looking node types. -Look for examples in `games/minimal` or `games/minetest_game`. +Look for examples in `games/devtest` or `games/minetest_game`. * `normal` * A node-sized cube. @@ -1062,8 +1151,20 @@ Look for examples in `games/minimal` or `games/minetest_game`. * Invisible, uses no texture. * `liquid` * The cubic source node for a liquid. + * Faces bordering to the same node are never rendered. + * Connects to node specified in `liquid_alternative_flowing`. + * 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`. + * 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. + * `tiles` is used for the item/inventory/wield image rendering. + * Use `backface_culling = false` for the special tiles you want to make + visible when inside the node * `glasslike` * Often used for partially-transparent nodes. * Only external sides of textures are visible. @@ -1090,14 +1191,20 @@ Look for examples in `games/minimal` or `games/minetest_game`. used to compensate for how `glasslike` reduces visual thickness. * `torchlike` * A single vertical texture. - * 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`. - * If placed on the side of a node, uses the third texture specified in - `tiles` and is perpendicular to that node. + * 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`. + * If placed on the side of a node, uses the third texture specified in + `tiles` and is perpendicular to that node. + * If `paramtype2="none"`: + * Will be rendered as if placed on top of a node (see + above) and only the first texture is used. * `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="none"`, it will always be on the floor. * `plantlike` * Two vertical and diagonal textures at right-angles to each other. * See `paramtype2 = "meshoptions"` above for other options. @@ -1130,12 +1237,17 @@ Look for examples in `games/minimal` or `games/minetest_game`. * `plantlike_rooted` * Enables underwater `plantlike` without air bubbles around the nodes. * Consists of a base cube at the co-ordinates of the node plus a - `plantlike` extension above with a height of `param2 / 16` nodes. + `plantlike` extension above + * If `paramtype2="leveled", the `plantlike` extension has a height + of `param2 / 16` nodes, otherwise it's the height of 1 node + * If `paramtype2="wallmounted"`, the `plantlike` extension + will be at one of the corresponding 6 sides of the base cube. + Also, the base cube rotates like a `normal` cube would * The `plantlike` extension visually passes through any nodes above the base cube without affecting them. * The base cube texture tiles are defined as normal, the `plantlike` extension uses the defined special tile, for example: - `special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},` + `special_tiles = {{name = "default_papyrus.png"}},` `*_optional` drawtypes need less rendering time if deactivated (always client-side). @@ -1205,6 +1317,9 @@ A box of a regular node would look like: {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, +To avoid collision issues, keep each value within the range of +/- 1.45. +This also applies to leveled nodeboxes, where the final height shall not +exceed this soft limit. @@ -1278,9 +1393,9 @@ 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 -HUD element represents. The direction field is the direction in which something -is drawn. +HUD element represents. +The `direction` field is the direction in which something is drawn. `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. @@ -1299,7 +1414,21 @@ factor! The `z_index` field specifies the order of HUD elements from back to front. Lower z-index elements are displayed behind higher z-index elements. Elements with same z-index are displayed in an arbitrary order. Default 0. -Supports negative values. +Supports negative values. By convention, the following values are recommended: + +* -400: Graphical effects, such as vignette +* -300: Name tags, waypoints +* -200: Wieldhand +* -100: Things that block the player's view, e.g. masks +* 0: Default. For standard in-game HUD elements like crosshair, hotbar, + minimap, builtin statbars, etc. +* 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 + + Below are the specific uses for fields in each type; fields not listed for that type are ignored. @@ -1327,15 +1456,21 @@ Displays text on the HUD. text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. * `alignment`: The alignment of the text. * `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). ### `statbar` -Displays a horizontal bar made up of half-images. +Displays a horizontal bar made up of half-images with an optional background. -* `text`: The name of the texture that is used. +* `text`: The name of the texture to use. +* `text2`: Optional texture name to enable a background / "off state" + texture (useful to visualize the maximal value). Both textures + must have the same size. * `number`: The number of half-textures that are displayed. If odd, will end with a vertically center-split texture. -* `direction` +* `item`: Same as `number` but for the "off state" texture +* `direction`: To which direction the images will extend to * `offset`: offset in pixels from position. * `size`: If used, will force full-image size to this value (override texture pack image size) @@ -1354,22 +1489,67 @@ Displays distance to selected world position. * `name`: The name of the waypoint. * `text`: Distance suffix. Can be blank. +* `precision`: Waypoint precision, integer >= 0. Defaults to 10. + If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`. + When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point. + `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`). + `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on: + `precision = n` will show multiples of `1/n` * `number:` An integer containing the RGB value of the color used to draw the text. * `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. +* `alignment`: The alignment of the waypoint. + +### `image_waypoint` + +Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint. + +* `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. +* `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. +### `compass` +Displays an image oriented or translated according to current heading direction. + +* `size`: The size of this element. Negative values represent percentage + of the screen; e.g. `x=-100` means 100% (width). +* `scale`: Scale of the translated image (used only for dir = 2 or dir = 3). +* `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: + * 0 - Rotate as heading direction + * 1 - Rotate in reverse direction + * 2 - Translate as landscape direction + * 3 - Translate in reverse direction +If translation is chosen, texture is repeated horizontally to fill the whole element. + +### `minimap` + +Displays a minimap on the HUD. + +* `size`: Size of the minimap to display. Minimap should be a square to avoid + distortion. +* `alignment`: The alignment of the minimap. +* `offset`: offset in pixels from position. Representations of simple things ================================ -Position/vector ---------------- +Vector (ie. a position) +----------------------- - {x=num, y=num, z=num} + vector.new(x, y, z) -For helper functions see [Spatial Vectors]. +See [Spatial Vectors] for details. `pointed_thing` --------------- @@ -1390,8 +1570,7 @@ Exact pointing location (currently only `Raycast` supports these fields): from 1). * `pointed_thing.intersection_normal`: Unit vector, points outwards of the selected selection box. This specifies which face is pointed at. - Is a null vector `{x = 0, y = 0, z = 0}` when the pointer is inside the - selection box. + Is a null vector `vector.zero()` when the pointer is inside the selection box. @@ -1436,15 +1615,37 @@ since, by default, no schematic attributes are set. Items ===== +Items are things that can be held by players, dropped in the map and +stored in inventories. +Items come in the form of item stacks, which are collections of equal +items that occupy a single inventory slot. + Item types ---------- There are three kinds of items: nodes, tools and craftitems. -* Node: Can be placed in the world's voxel grid -* Tool: Has a wear property but cannot be stacked. The default use action is to - dig nodes or hit objects according to its tool capabilities. -* Craftitem: Cannot dig nodes or be placed +* Node: Placeable item form of a node in the world's voxel grid +* Tool: Has a changable wear property but cannot be stacked +* Craftitem: Has no special properties + +Every registered node (the voxel in the world) has a corresponding +item form (the thing in your inventory) that comes along with it. +This item form can be placed which will create a node in the +world (by default). +Both the 'actual' node and its item form share the same identifier. +For all practical purposes, you can treat the node and its item form +interchangeably. We usually just say 'node' to the item form of +the node as well. + +Note the definition of tools is purely technical. The only really +unique thing about tools is their wear, and that's basically it. +Beyond that, you can't make any gameplay-relevant assumptions +about tools or non-tools. It is perfectly valid to register something +that acts as tool in a gameplay sense as a craftitem, and vice-versa. + +Craftitems can be used for items that neither need to be a node +nor a tool. Amount and wear --------------- @@ -1455,7 +1656,9 @@ 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 is used 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. +a higher wear. Non-tools technically also have a wear property, +but it is always 0. There is also a special 'toolrepair' crafting +recipe that is only available to tools. Item formats ------------ @@ -1476,10 +1679,10 @@ wear value. Syntax: 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 +* `"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 @@ -1509,8 +1712,8 @@ 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 +properties of a thing (item, node, armor of entity, tool capabilities) +in such a way that the engine and other mods can can interact with the thing without actually knowing what the thing is. Usage @@ -1551,17 +1754,17 @@ 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. +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}) -Groups of tools ---------------- +Groups of tool capabilities +--------------------------- -Groups in tools define which groups of nodes and entities they are -effective towards. +Groups in tool capabilities define which groups of nodes and entities they +are effective towards. Groups in crafting recipes -------------------------- @@ -1569,21 +1772,21 @@ Groups in crafting recipes An example: Make meat soup from any meat, any water and any bowl: { - output = 'food:meat_soup_raw', + output = "food:meat_soup_raw", recipe = { - {'group:meat'}, - {'group:water'}, - {'group:bowl'}, + {"group:meat"}, + {"group:water"}, + {"group:bowl"}, }, - -- preserve = {'group:bowl'}, -- Not implemented yet (TODO) + -- preserve = {"group:bowl"}, -- Not implemented yet (TODO) } Another example: Make red wool from white wool and red dye: { - type = 'shapeless', - output = 'wool:red', - recipe = {'wool:white', 'group:dye,basecolor_red'}, + type = "shapeless", + output = "wool:red", + recipe = {"wool:white", "group:dye,basecolor_red"}, } Special groups @@ -1593,7 +1796,7 @@ The asterisk `(*)` after a group name describes that there is no engine functionality bound to it, and implementation is left up as a suggestion to games. -### Node, item and tool groups +### Node and item groups * `not_in_creative_inventory`: (*) Special group for inventory mods to indicate that the item should be hidden in item lists. @@ -1611,16 +1814,25 @@ to games. * `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)` + or if their feet are in the node. Note: not supported for `new_move = false` +* `fall_damage_add_percent`: modifies the fall damage suffered when hitting + the top of this node. There's also an armor group with the same name. + The final player damage is determined by the following formula: + damage = + collision speed + * ((node_fall_damage_add_percent + 100) / 100) -- node group + * ((player_fall_damage_add_percent + 100) / 100) -- player armor group + - (14) -- constant tolerance + Negative damage values are discarded as no damage. * `falling_node`: if there is no walkable block under the node it will fall -* `float`: the node will not fall through liquids +* `float`: the node will not fall through liquids (`liquidtype ~= "none"`) * `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 - * See also: `leveldiff` in [Tools] + * See also: `leveldiff` in [Tool Capabilities] * `slippery`: Players and items will slide on the node. Slipperiness rises steadily with `slippery` value, starting at 1. @@ -1631,11 +1843,15 @@ to games. `"toolrepair"` crafting recipe -### `ObjectRef` groups +### `ObjectRef` armor groups * `immortal`: Skips all damage and breath handling for an object. This group - will also hide the integrated HUD status bars for players, and is - automatically set to all players when damage is disabled on the server. + will also hide the integrated HUD status bars for players. It is + automatically set to all players when damage is disabled on the server and + cannot be reset (subject to change). +* `fall_damage_add_percent`: Modifies the fall damage suffered by players + when they hit the ground. It is analog to the node group with the same + name. See the node group above for the exact calculation. * `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. @@ -1647,8 +1863,8 @@ 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 +* `snappy`: something that can be cut using things like scissors, shears, + bolt cutters and the like, 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. @@ -1657,7 +1873,7 @@ Known damage and digging time defining groups 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 + digging speed of an item if it can dig at a faster speed than this suggests for the hand. Examples of custom groups @@ -1683,54 +1899,67 @@ 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. -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. +The `level` group is used to limit the toughness of nodes an item capable +of digging can dig and to scale the digging times / damage to a greater extent. **Please do understand this**, otherwise you cannot use the system to it's full potential. -Tools define their properties by a list of parameters for groups. They +Items 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. +groups to enable interaction with items. -Tools -===== +Tool Capabilities +================= -Tools definition ----------------- +'Tool capabilities' is a property of items that defines two things: + +1) Which nodes it can dig and how fast +2) Which objects it can hurt by punching and by how much + +Tool capabilities are available for all items, not just tools. +But only tools can receive wear from digging and punching. -Tools define: +Missing or incomplete tool capabilities will default to the +player's hand. + +Tool capabilities definition +---------------------------- + +Tool capabilities define: * Full punch interval * Maximum drop level -* For an arbitrary list of groups: +* For an arbitrary list of node groups: * Uses (until the tool breaks) - * Maximum level (usually `0`, `1`, `2` or `3`) - * Digging times - * Damage groups + * Maximum level (usually `0`, `1`, `2` or `3`) + * Digging times +* Damage groups +* Punch attack uses (until the tool breaks) ### 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 +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 -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). +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. -### 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. For lower leveled nodes, the use count -is multiplied by `3^leveldiff`. +of this group, of the maximum level. The maximum supported number of +uses is 65535. The special number 0 is used for infinite uses. +For lower leveled nodes, the use count is multiplied by `3^leveldiff`. `leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the node's `level` group. The node cannot be dug if `leveldiff` is less than zero. @@ -1738,9 +1967,11 @@ node's `level` group. The node cannot be dug if `leveldiff` is less than zero. * `uses=10, leveldiff=1`: actual uses: 30 * `uses=10, leveldiff=2`: actual uses: 90 +For non-tools, this has no effect. + ### Maximum level -Tells what is the maximum level of a node of this group that the tool will +Tells what is the maximum level of a node of this group that the item will be able to dig. ### Digging times @@ -1749,7 +1980,7 @@ 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 -result in the tool to be able to dig nodes that have a rating of `2` or `3` +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. @@ -1761,8 +1992,19 @@ i.e. players can more quickly click the nodes away instead of holding LMB. List of damage for groups of entities. See [Entity damage mechanism]. -Example definition of the capabilities of a tool ------------------------------------------------- +### Punch attack uses (tools only) + +Determines how many uses (before breaking) the tool has when dealing damage +to an object, when the full punch interval (see above) was always +waited out fully. + +Wear received by the tool is proportional to the time spent, scaled by +the full punch interval. + +For non-tools, this has no effect. + +Example definition of the capabilities of an item +------------------------------------------------- tool_capabilities = { full_punch_interval=1.5, @@ -1773,7 +2015,7 @@ Example definition of the capabilities of a tool damage_groups = {fleshy=2}, } -This makes the tool be able to dig nodes that fulfil both of these: +This makes the item capable of digging nodes that fulfil both of these: * Have the `crumbly` group * Have a `level` group less or equal to `2` @@ -1877,8 +2119,12 @@ Node metadata contains two things: Some of the values in the key-value store are handled specially: -* `formspec`: Defines a right-click inventory menu. See [Formspec]. -* `infotext`: Text shown on the screen when the node is pointed at +* `formspec`: Defines an inventory menu that is opened with the + 'place/use' key. Only works if no `on_rightclick` was + defined for the node. See also [Formspec]. +* `infotext`: Text shown on the screen when the node is pointed at. + Line-breaks will be applied automatically. + If the infotext is very long, it will be truncated. Example: @@ -1917,11 +2163,20 @@ Item metadata only contains a key-value store. Some of the values in the key-value store are handled specially: -* `description`: Set the item stack's description. Defaults to - `idef.description`. +* `description`: Set the item stack's description. + See also: `get_description` in [`ItemStack`] +* `short_description`: Set the item stack's short description. + See also: `get_short_description` in [`ItemStack`] * `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. +* `count_meta`: Replace the displayed count with any string. +* `count_alignment`: Set the alignment of the displayed count value. This is an + int value. The lowest 2 bits specify the alignment in x-direction, the 3rd and + 4th bit specify the alignment in y-direction: + 0 = default, 1 = left / up, 2 = middle, 3 = right / down + The default currently is the same as right/down. + Example: 6 = 2 + 1*4 = middle,up Example: @@ -1929,6 +2184,21 @@ Example: meta:set_string("key", "value") print(dump(meta:to_table())) +Example manipulations of "description" and expected output behaviors: + + print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe + print(ItemStack("foobar"):get_description()) --> Unknown Item + + local stack = ItemStack("default:stone") + stack:get_meta():set_string("description", "Custom description\nAnother line") + print(stack:get_description()) --> Custom description\nAnother line + print(stack:get_short_description()) --> Custom description + + stack:get_meta():set_string("short_description", "Short") + print(stack:get_description()) --> Custom description\nAnother line + print(stack:get_short_description()) --> Short + + print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc @@ -2001,6 +2271,24 @@ Examples list[current_player;craft;3,0;3,3;] list[current_player;craftpreview;7,1;1,1;] +Version History +--------------- + +* Formspec version 1 (pre-5.1.0): + * (too much) +* Formspec version 2 (5.1.0): + * Forced real coordinates + * background9[]: 9-slice scaling parameters +* Formspec version 3 (5.2.0): + * Formspec elements are drawn in the order of definition + * bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor) + * box[] and image[] elements enable clipping by default + * new element: scroll_container[] +* Formspec version 4 (5.4.0): + * Allow dropdown indexing events +* Formspec version 5 (5.5.0): + * Added padding[] element + Elements -------- @@ -2012,6 +2300,7 @@ Elements * Clients older than this version can neither show newer elements nor display elements with new arguments correctly. * Available since feature `formspec_version_element`. +* See also: [Version History] ### `size[,,]` @@ -2042,9 +2331,20 @@ Elements * `position` and `anchor` elements need suitable values to avoid a formspec extending off the game window due to particular game window sizes. -### `no_prepend[]` +### `padding[,]` * Must be used after the `size`, `position`, and `anchor` elements (if present). +* Defines how much space is padded around the formspec if the formspec tries to + increase past the size of the screen and coordinates have to be shrunk. +* For X and Y, 0.0 represents no padding (the formspec can touch the edge of the + screen), and 0.5 represents half the screen (which forces the coordinate size + to 0). If negative, the formspec can extend off the edge of the screen. +* Defaults to [0.05, 0.05]. + +### `no_prepend[]` + +* Must be used after the `size`, `position`, `anchor`, and `padding` elements + (if present). * Disables player:set_formspec_prepend() from applying to this formspec. ### `real_coordinates[]` @@ -2071,19 +2371,42 @@ Elements * End of a container, following elements are no longer relative to this container. -### `list[;;,;,;]` +### `scroll_container[,;,;;;]` -* Show an inventory list if it has been sent to the client. Nothing will - be shown if the inventory list is of size 0. -* **Note**: With the new coordinate system, the spacing between inventory - slots is one-fourth the size of an inventory slot. +* Start of a scroll_container block. All contained elements will ... + * take the scroll_container coordinate as position origin, + * be additionally moved by the current value of the scrollbar with the name + `scrollbar name` times `scroll factor` along the orientation `orientation` and + * be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. +* `orientation`: possible values are `vertical` and `horizontal`. +* `scroll factor`: optional, defaults to `0.1`. +* Nesting is possible. +* Some elements might work a little different if they are in a scroll_container. +* Note: If you want the scroll_container to actually work, you also need to add a + scrollbar element with the specified name. Furthermore, it is highly recommended + to use a scrollbaroptions element on this scrollbar. + +### `scroll_container_end[]` + +* End of a scroll_container, following elements are no longer bound to this + container. ### `list[;;,;,;]` -* Show an inventory list if it has been sent to the client. Nothing will - be shown if the inventory list is of size 0. +* Show an inventory list if it has been sent to the client. +* If the inventory list changes (eg. it didn't exist before, it's resized, or its items + are moved) while the formspec is open, the formspec element may (but is not guaranteed + to) adapt to the new inventory list. +* Item slots are drawn in a grid from left to right, then up to down, ordered + according to the slot index. +* `W` and `H` are in inventory slots, not in coordinates. +* `starting item index` (Optional): The index of the first (upper-left) item to draw. + Indices start at `0`. Default is `0`. +* The number of shown slots is the minimum of `W*H` and the inventory list's size minus + `starting item index`. * **Note**: With the new coordinate system, the spacing between inventory - slots is one-fourth the size of an inventory slot. + slots is one-fourth the size of an inventory slot by default. Also see + [Styling Formspecs] for changing the size of slots and spacing. ### `listring[;]` @@ -2120,27 +2443,45 @@ Elements ### `tooltip[;;;]` * Adds tooltip for an element -* `` tooltip background color as `ColorString` (optional) -* `` tooltip font color as `ColorString` (optional) +* `bgcolor` tooltip background color as `ColorString` (optional) +* `fontcolor` tooltip font color as `ColorString` (optional) ### `tooltip[,;,;;;]` * Adds tooltip for an area. Other tooltips will take priority when present. -* `` tooltip background color as `ColorString` (optional) -* `` tooltip font color as `ColorString` (optional) +* `bgcolor` tooltip background color as `ColorString` (optional) +* `fontcolor` tooltip font color as `ColorString` (optional) ### `image[,;,;]` * Show an image -### `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 + animation (See [Tile animation definition]), but uses a frame count/duration for simplicity -* `` is the image to use -* `` is the number of frames animating the image -* `` is in milliseconds +* `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`. + +### `model[,;,;;;;;;;;]` + +* Show a mesh model. +* `name`: Element name that can be used for styling +* `mesh`: The mesh model to use. +* `textures`: The mesh textures to use according to the mesh materials. + Texture names must be separated by commas. +* `rotation {X,Y}` (Optional): Initial rotation of the camera. + The axes are euler angles in degrees. +* `continuous` (Optional): Whether the rotation is continuous. Default `false`. +* `mouse control` (Optional): Whether the model can be controlled with the mouse. Default `true`. +* `frame loop range` (Optional): Range of the animation frames. + * Defaults to the full range of all available frames. + * Syntax: `,` +* `animation speed` (Optional): Sets the animation speed. Default 0 FPS. ### `item_image[,;,;]` @@ -2176,12 +2517,12 @@ Elements * 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling * Middle is a rect which defines the middle of the 9-slice. - * `x` - The middle will be x pixels from all sides. - * `x,y` - The middle will be x pixels from the horizontal and y from the vertical. - * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values - 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. + * `x` - The middle will be x pixels from all sides. + * `x,y` - The middle will be x pixels from the horizontal and y from the vertical. + * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values + 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 @@ -2253,9 +2594,10 @@ Elements ### `hypertext[,;,;;]` * Displays a static formatted text with hyperlinks. +* **Note**: This element is currently unstable and subject to change. * `x`, `y`, `w` and `h` work as per field * `name` is the name of the field as returned in fields to `on_receive_fields` in case of action in text. -* `text` is the formatted text using `markup language` described below. +* `text` is the formatted text using `Markup Language` described below. ### `vertlabel[,;