From 334d8c31ee96f2e6a8464c99eecf84793f598fb6 Mon Sep 17 00:00:00 2001 From: pauloue Date: Sat, 7 Jul 2018 23:18:53 -0400 Subject: [PATCH] Lua_api.txt: Formatting and grammar fixes (#7534) Use tree output for directory structure. Remove 2 blank lines near document top. Spelling and grammar fixes. Markdown fixes. Condense paths section. Fix skipped heading levels. --- doc/lua_api.txt | 645 ++++++++++++++++++++++++++++-------------------- 1 file changed, 377 insertions(+), 268 deletions(-) diff --git a/doc/lua_api.txt b/doc/lua_api.txt index d6cdd80a1..5e26921eb 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -4,8 +4,6 @@ Minetest Lua Modding API Reference * Developer Wiki: - - Introduction ============ @@ -34,14 +32,10 @@ the `init.lua` scripts in a shared environment. Paths ----- * `RUN_IN_PLACE=1` (Windows release, local build) - * `$path_user`: - * Linux: `` - * Windows: `` - * `$path_share` - * Linux: `` - * Windows: `` + * `$path_user`: `` + * `$path_share`: `` * `RUN_IN_PLACE=0`: (Linux release) - * `$path_share` + * `$path_share`: * Linux: `/usr/share/minetest` * Windows: `/minetest-0.4.x` * `$path_user`: @@ -79,7 +73,8 @@ The game directory can contain the following files: texturepack, overriding mod textures. Any server texturepack will override mod textures and the game texturepack. -### Menu images +Menu images +----------- Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory. @@ -129,7 +124,7 @@ This happens if the following directory exists: $world/game/ -Mods should be then be placed in: +Mods should then be placed in: $world/game/mods/ @@ -143,20 +138,20 @@ Mod directory structure ----------------------- mods - |-- modname - | |-- mod.conf - | |-- screenshot.png - | |-- settingtypes.txt - | |-- init.lua - | |-- models - | |-- textures - | | |-- modname_stuff.png - | | `-- modname_something_else.png - | |-- sounds - | |-- media - | |-- locale - | `-- - `-- another + ├── modname + │   ├── mod.conf + │   ├── screenshot.png + │   ├── settingtypes.txt + │   ├── init.lua + │   ├── models + │   ├── textures + │   │   ├── modname_stuff.png + │   │   └── modname_something_else.png + │   ├── sounds + │   ├── media + │   ├── locale + │   └── + └── another ### modname The location of this directory can be fetched by using @@ -284,65 +279,64 @@ of the game's nodes are to be used by the core mapgens. For example: ### Aliases needed for all mapgens except Mapgen v6 -Base terrain: +#### Base terrain +* mapgen_stone +* mapgen_water_source +* mapgen_river_water_source -"mapgen_stone" -"mapgen_water_source" -"mapgen_river_water_source" - -Caves: - -"mapgen_lava_source" - -Dungeons: +#### Caves +* mapgen_lava_source +#### Dungeons Only needed for registered biomes where 'node_stone' is stone: -"mapgen_cobble" -"mapgen_stair_cobble" -"mapgen_mossycobble" + +* mapgen_cobble +* mapgen_stair_cobble +* mapgen_mossycobble + Only needed for registered biomes where 'node_stone' is desert stone: -"mapgen_desert_stone" -"mapgen_stair_desert_stone" + +* mapgen_desert_stone +* mapgen_stair_desert_stone + Only needed for registered biomes where 'node_stone' is sandstone: -"mapgen_sandstone" -"mapgen_sandstonebrick" -"mapgen_stair_sandstone_block" + +* mapgen_sandstone +* mapgen_sandstonebrick +* mapgen_stair_sandstone_block ### Aliases needed for Mapgen v6 -Terrain and biomes: +#### Terrain and biomes +* 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_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" +#### Flora +* mapgen_tree +* mapgen_leaves +* mapgen_apple +* mapgen_jungletree +* mapgen_jungleleaves +* mapgen_junglegrass +* mapgen_pine_tree +* mapgen_pine_needles -Flora: - -"mapgen_tree" -"mapgen_leaves" -"mapgen_apple" -"mapgen_jungletree" -"mapgen_jungleleaves" -"mapgen_junglegrass" -"mapgen_pine_tree" -"mapgen_pine_needles" - -Dungeons: - -"mapgen_cobble" -"mapgen_stair_cobble" -"mapgen_mossycobble" -"mapgen_stair_desert_stone" +#### Dungeons +* mapgen_cobble +* mapgen_stair_cobble +* mapgen_mossycobble +* mapgen_stair_desert_stone @@ -404,6 +398,7 @@ on top of `cobble.png`. * `[cracko:::

` Parameters: + * `` = tile count (in each direction) * `` = animation frame count * `

` = current animation frame @@ -537,7 +532,6 @@ The mask is applied using binary AND. Retrieves a tile at position x,y from the base image which it assumes to be a tilesheet with dimensions w,h. - #### `[colorize::` Colorize the textures with the given color. `` is specified as a `ColorString`. @@ -573,12 +567,12 @@ the same texture, in different colors, each in a new node/item definition. When you register an item or node, set its `color` field (which accepts a `ColorSpec`) to the desired color. -An `ItemStack`s static color can be overwritten by the `color` metadata +An `ItemStack`'s static color can be overwritten by the `color` metadata field. If you set that field to a `ColorString`, that color will be used. #### Tile color Each tile may have an individual static color, which overwrites every -other coloring methods. To disable the coloring of a face, +other coloring method. To disable the coloring of a face, set its color to white (because multiplying with white does nothing). You can set the `color` property of the tiles in the node's definition if the tile is in table format. @@ -808,7 +802,8 @@ Examples of sound parameter tables: Looped sounds must either be connected to an object or played locationless to one player using `to_player = name,` -### `SimpleSoundSpec` +`SimpleSoundSpec` +----------------- * e.g. `""` * e.g. `"default_place_node"` * e.g. `{}` @@ -819,10 +814,10 @@ one player using `to_player = name,` -Registered definitions of stuff -=============================== +Registered definitions +====================== -Anything added using certain `minetest.register_*` functions get added to +Anything added using certain `minetest.register_*` functions gets added to the global `minetest.registered_*` tables. * `minetest.register_entity(name, prototype table)` @@ -919,11 +914,11 @@ Nodes are the bulk data of the world: cubes and other things that take the space of a cube. Huge amounts of them are handled efficiently, but they are quite static. -The definition of a node is stored and can be accessed by name in +The definition of a node is stored and can be accessed by using minetest.registered_nodes[node.name] -See "Registered definitions of stuff". +See "Registered definitions". Nodes are passed by value between Lua and the engine. They are represented by a table: @@ -1270,13 +1265,15 @@ Displays distance to selected world position. Representations of simple things ================================ -### Position/vector +Position/vector +--------------- {x=num, y=num, z=num} For helper functions see "Spatial Vectors". -### `pointed_thing` +`pointed_thing` +--------------- * `{type="nothing"}` * `{type="node", under=pos, above=pos}` * `{type="object", ref=ObjectRef}` @@ -1324,7 +1321,8 @@ since, by default, no schematic attributes are set. Items ===== -### Item types +Item types +---------- There are three kinds of items: nodes, tools and craftitems. * Node (`register_node`): A node from the world. @@ -1332,7 +1330,8 @@ There are three kinds of items: nodes, tools and craftitems. things according to `tool_capabilities`. * Craftitem (`register_craftitem`): A miscellaneous item. -### Amount and wear +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. @@ -1341,11 +1340,12 @@ value 0 is the default and used is for unworn tools. The values 1 to 65535 are used for worn tools, where a higher value stands for a higher wear. Non-tools always have a wear value of 0. -### Item formats +Item formats +------------ Items and item stacks can exist in three formats: Serializes, table format and `ItemStack`. -#### Serialized +### 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: @@ -1359,7 +1359,7 @@ Examples: * `'default:pick_stone'`: a new stone pickaxe * `'default:pick_wood 1 21323'`: a wooden pickaxe, ca. 1/3 worn out -#### Table format +### Table format Examples: 5 dirt nodes: @@ -1374,7 +1374,7 @@ An apple: {name="default:apple", count=1, wear=0, metadata=""} -#### `ItemStack` +### `ItemStack` A native C++ format with many helper methods. Useful for converting between formats. See the Class reference section for details. @@ -1392,7 +1392,8 @@ 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 +Usage +----- Groups are stored in a table, having the group names with keys and the group ratings as values. For example: @@ -1412,14 +1413,17 @@ You can read the rating of a group for an item or a node by using minetest.get_item_group(itemname, groupname) -### Groups of items +Groups of items +--------------- Groups of items can define what kind of an item it is (e.g. wool). -### Groups of nodes +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. -### Groups of entities +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". @@ -1427,11 +1431,13 @@ 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 tools +--------------- Groups in tools define which groups of nodes and entities they are effective towards. -### Groups in crafting recipes +Groups in crafting recipes +-------------------------- An example: Make meat soup from any meat, any water and any bowl: { @@ -1452,7 +1458,8 @@ Another example: Make red wool from white wool and red dye: recipe = {'wool:white', 'group:dye,basecolor_red'}, } -### Special groups +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 @@ -1480,7 +1487,8 @@ Another example: Make red wool from white wool and red dye: Slipperiness rises steadily with `slippery` value, starting at 1. -### Known damage and digging time defining groups +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 @@ -1496,7 +1504,8 @@ Another example: Make red wool from white wool and red dye: speed of a tool if the tool can dig at a faster speed than this suggests for the hand. -### Examples of custom groups +Examples of custom groups +------------------------- Item groups are often used for defining, well, _groups of items_. * `meat`: any meat-kind of a thing (rating might define the size or healing @@ -1510,7 +1519,8 @@ Item groups are often used for defining, well, _groups of items_. * `weapon`: any weapon * `heavy`: anything considerably heavy -### Digging time calculation specifics +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. @@ -1531,7 +1541,8 @@ groups to enable interaction with tools. Tools ===== -#### Tools definition +Tools definition +---------------- Tools define: * Full punch interval @@ -1542,19 +1553,22 @@ Tools define: * Digging times * Damage groups -#### Full punch interval +### 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. -#### Maximum drop level +### 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). This is not automated; it is the responsibility of the node definition to implement this. -#### Uses +### 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`. @@ -1563,11 +1577,13 @@ is multiplied by `3^leveldiff`. * `uses=10, leveldiff=1`: actual uses: 30 * `uses=10, leveldiff=2`: actual uses: 90 -#### Maximum level +### Maximum level + Tells what is the maximum level of a node of this group that the tool will be able to dig. -#### Digging times +### Digging times + List of digging times for different ratings of the group, for nodes of the maximum level. @@ -1580,10 +1596,12 @@ 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. -#### Damage groups +### Damage groups + List of damage for groups of entities. See "Entity damage mechanism". -#### Example definition of the capabilities of a tool +Example definition of the capabilities of a tool +------------------------------------------------ tool_capabilities = { full_punch_interval=1.5, @@ -1763,15 +1781,16 @@ 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[]` -### Examples +Examples +-------- -#### Chest +### Chest size[8,9] list[context;main;0,0;8,4;] list[current_player;main;0,5;8,4;] -#### Furnace +### Furnace size[8,9] list[context;fuel;2,3;1,1;] @@ -1779,7 +1798,7 @@ appearing when you don't expect them to. See `no_prepend[]` list[context;dst;5,1;2,2;] list[current_player;main;0,5;8,4;] -#### Minecraft-like player inventory +### Minecraft-like player inventory size[8,7.5] image[1,0.6;1,2;player.png] @@ -1787,14 +1806,15 @@ appearing when you don't expect them to. See `no_prepend[]` list[current_player;craft;3,0;3,3;] list[current_player;craftpreview;7,1;1,1;] -### Elements +Elements +-------- -#### `size[,,]` +### `size[,,]` * Define the size of the menu in inventory slots * `fixed_size`: `true`/`false` (optional) * deprecated: `invsize[,;]` -#### `position[,]` +### `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, @@ -1803,7 +1823,7 @@ appearing when you don't expect them to. See `no_prepend[]` * [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]. -#### `anchor[,]` +### `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, @@ -1815,79 +1835,79 @@ appearing when you don't expect them to. See `no_prepend[]` * `position` and `anchor` elements need suitable values to avoid a formspec extending off the game window due to particular game window sizes. -#### `no_prepend[]` +### `no_prepend[]` * Must be used after the `size`, `position`, and `anchor` elements (if present). * Disables player:set_formspec_prepend() from applying to this formspec. -#### `container[,]` +### `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) -#### `container_end[]` +### `container_end[]` * End of a container, following elements are no longer relative to this container. -#### `list[;;,;,;]` +### `list[;;,;,;]` * Show an inventory list -#### `list[;;,;,;]` +### `list[;;,;,;]` * Show an inventory list -#### `listring[;]` +### `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 -#### `listring[]` +### `listring[]` * Shorthand for doing `listring[;]` for the last two inventory lists added by list[...] -#### `listcolors[;]` +### `listcolors[;]` * Sets background color of slots as `ColorString` * Sets background color of slots on mouse hovering -#### `listcolors[;;]` +### `listcolors[;;]` * Sets background color of slots as `ColorString` * Sets background color of slots on mouse hovering * Sets color of slots border -#### `listcolors[;;;;]` +### `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 -#### `tooltip[;;;]` +### `tooltip[;;;]` * Adds tooltip for an element * `` tooltip background color as `ColorString` (optional) * `` tooltip font color as `ColorString` (optional) -#### `image[,;,;]` +### `image[,;,;]` * Show an image * Position and size units are inventory slots -#### `item_image[,;,;]` +### `item_image[,;,;]` * Show an inventory image of registered item/node * Position and size units are inventory slots -#### `bgcolor[;]` +### `bgcolor[;]` * Sets background color of formspec as `ColorString` * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec). -#### `background[,;,;]` +### `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. -#### `background[,;,;;]` +### `background[,;,;;]` * Use a background. Inventory rectangles are not drawn then. * Position and size units are inventory slots * Example for formspec 8x4 in 16x resolution: @@ -1895,7 +1915,7 @@ appearing when you don't expect them to. See `no_prepend[]` * If `true` the background is clipped to formspec size (`x` and `y` are used as offset values, `w` and `h` are ignored) -#### `pwdfield[,;,;;