X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=37eb7e79685b4ceb7852e43ec1b1538d95d58068;hb=d7364d65ac9ed8a8312d87156de78a81d08c5f86;hp=afb142513aa9206e6fccdd55d29de34ca32b3d8c;hpb=bd8ddf1a526c57648028bbee192d92e1289219ac;p=minetest.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index afb142513..37eb7e796 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Modding API Reference 0.4.9 +Minetest Lua Modding API Reference 0.4.10 ======================================== More information at http://www.minetest.net/ Developer Wiki: http://dev.minetest.net/ @@ -51,7 +51,7 @@ where gameid is unique to each game. The game directory contains the file game.conf, which contains these fields: name = -eg. +e.g. name = Minetest The game directory can contain the file minetest.conf, which will be used @@ -66,14 +66,14 @@ Generic: $path_user/mods/ <-- User-installed mods $worldpath/worldmods/ -In a run-in-place version (eg. the distributed windows version): +In a run-in-place version (e.g. the distributed windows version): minetest-0.4.x/games/gameid/mods/ - minetest-0.4.x/mods/gameid/ <-- User-installed mods + minetest-0.4.x/mods/ <-- User-installed mods minetest-0.4.x/worlds/worldname/worldmods/ -On an installed version on linux: +On an installed version on Linux: /usr/share/minetest/games/gameid/mods/ - ~/.minetest/mods/gameid/ <-- User-installed mods + ~/.minetest/mods/ <-- User-installed mods ~/.minetest/worlds/worldname/worldmods Mod load path for world-specific games @@ -81,7 +81,7 @@ Mod load path for world-specific games It is possible to include a game in a world; in this case, no mods or games are loaded or checked from anywhere else. -This is useful for eg. adventure worlds. +This is useful for e.g. adventure worlds. This happens if the following directory exists: $world/game/ @@ -127,7 +127,7 @@ screenshot.png: A screenshot shown in modmanager within mainmenu. description.txt: - File containing desctiption to be shown within mainmenu. + File containing description to be shown within mainmenu. init.lua: The main Lua script. Running this script should register everything it @@ -170,30 +170,106 @@ convert_to. This can be used for maintaining backwards compatibility. -This can be also used for setting quick access names for things, eg. if +This can be also used for setting quick access names for things, e.g. if you have an item called epiclylongmodname:stuff, you could do minetest.register_alias("stuff", "epiclylongmodname:stuff") and be able to use "/giveme stuff". Textures -------- -Mods should generally prefix their textures with modname_, eg. given +Mods should generally prefix their textures with modname_, e.g. given the mod name "foomod", a texture could be called "foomod_foothing.png" Textures are referred to by their complete name, or alternatively by stripping out the file extension: - eg. foomod_foothing.png - eg. foomod_foothing + 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. + +Texture overlaying: + Textures can be overlaid by putting a ^ between them. + Example: default_dirt.png^default_grass_side.png + default_grass_side.png is overlayed over default_dirt.png + +Texture grouping: + Textures can be grouped together by enclosing them in ( and ). + Example: cobble.png^(thing1.png^thing2.png) + A texture for 'thing1.png^thing2.png' is created and the resulting + texture is overlaid over cobble.png. + +Advanced texture modifiers: + [crack::

+ n = animation frame count, p = current animation frame + Draw a step of the crack animation on the texture. + Example: default_cobble.png^[crack:10:1 + + [combine:x:,=:,= + w = width, h = height, x1/x2 = x position, y1/y1 = y position, + file1/file2 = texture to combine + Create a texture of size x and blit to (,) + and blit to (,). + Example: [combine:16x32:0,0=default_cobble.png:0,16=default_wood.png + + [brighten + Brightens the texture. + Example: tnt_tnt_side.png^[brighten + + [noalpha + Makes the texture completely opaque. + Example: default_leaves.png^[noalpha + + [makealpha:,, + Convert one color to transparency. + Example: default_cobble.png^[makealpha:128,128,128 + + [transform + t = transformation(s) to apply + Rotates and/or flips the image. + can be a number (between 0 and 7) or a transform name. + Rotations are counter-clockwise. + 0 I identity + 1 R90 rotate by 90 degrees + 2 R180 rotate by 180 degrees + 3 R270 rotate by 270 degrees + 4 FX flip X + 5 FXR90 flip X then rotate by 90 degrees + 6 FY flip Y + 7 FYR90 flip Y then rotate by 90 degrees + Example: default_stone.png^[transformFXR90 + + [inventorycube{{{ + '^' is replaced by '&' in texture names + Create an inventory cube texture using the side textures. + Example: [inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png + Creates an inventorycube with 'grass.png', 'dirt.png^grass_side.png' and + 'dirt.png^grass_side.png' textures + + [lowpart:: + Blit the lower % part of on the texture: + Example: base.png^[lowpart:25:overlay.png + + [verticalframe:: + t = animation frame count, n = current animation frame + Crops the texture to a frame of a vertical animation. + Example: default_torch_animated.png^[verticalframe:16:8 + + [mask: + Apply a mask to the base image. + The mask is applied using binary AND. Sounds ------- -Only OGG files are supported. +Only OGG Vorbis files are supported. For positional playing of sounds, only single-channel (mono) files are supported. Otherwise OpenAL will play them non-positionally. -Mods should generally prefix their sounds with modname_, eg. given +Mods should generally prefix their sounds with modname_, e.g. given the mod name "foomod", a sound could be called "foomod_foosound.ogg" @@ -210,11 +286,11 @@ from the available ones of the following files: foomod_foosound.9.ogg Examples of sound parameter tables: --- Play locationless on all clients +-- Play location-less on all clients { gain = 1.0, -- default } --- Play locationless to a player +-- Play location-less to a player { to_player = name, gain = 1.0, -- default @@ -234,11 +310,11 @@ Examples of sound parameter tables: } SimpleSoundSpec: -eg. "" -eg. "default_place_node" -eg. {} -eg. {name="default_place_node"} -eg. {name="default_place_node", gain=1.0} +e.g. "" +e.g. "default_place_node" +e.g. {} +e.g. {name="default_place_node"} +e.g. {name="default_place_node", gain=1.0} Registered definitions of stuff -------------------------------- @@ -259,7 +335,7 @@ minetest.register_craftitem(name, item definition) -> minetest.registered_items[name] Note that in some cases you will stumble upon things that are not contained -in these tables (eg. when a mod has been removed). Always check for +in these tables (e.g. when a mod has been removed). Always check for existence before trying to access the fields. Example: If you want to check the drawtype of a node, you could do: @@ -384,7 +460,7 @@ A box is defined as: A box of a regular node would look like: {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, -type = "leveled" is same as "fixed", but y2 will be automaticaly setted to level from param2 +type = "leveled" is same as "fixed", but y2 will be automatically set to level from param2 Ore types --------------- @@ -393,14 +469,14 @@ All default ores are of the uniformly-distributed scatter type. - scatter Randomly chooses a location and generates a cluster of ore. - If noise_params is specified, the ore will be placed if the 3d perlin noise at - that point is greater than the noise_threshhold, giving the ability to create a non-equal + If noise_params is specified, the ore will be placed if the 3d perlin noise at + that point is greater than the noise_threshold, giving the ability to create a non-equal distribution of ore. - sheet Creates a sheet of ore in a blob shape according to the 2d perlin noise described by noise_params. The relative height of the sheet can be controlled by the same perlin noise as well, by specifying a non-zero 'scale' parameter in noise_params. IMPORTANT: The noise is not transformed by offset or - scale when comparing against the noise threshhold, but scale is used to determine relative height. + scale when comparing against the noise threshold, but scale is used to determine relative height. The height of the blob is randomly scattered, with a maximum height of clust_size. clust_scarcity and clust_num_ores are ignored. This is essentially an improved version of the so-called "stratus" ore seen in some unofficial mods. @@ -410,6 +486,7 @@ All default ores are of the uniformly-distributed scatter type. Ore attributes ------------------- +See section Flag Specifier Format. Currently supported flags: absheight - absheight Also produce this same ore between the height range of -height_max and -height_min. @@ -439,7 +516,7 @@ or through raw data supplied through Lua, in the form of a table. This table mu - The 'data' field is a flat table of MapNodes making up the schematic, in the order of [z [y [x]]]. Important: The default value for param1 in MapNodes here is 255, which represents "always place". -In the bulk MapNode data, param1, instead of the typical light values, instead represents the +In the bulk MapNode data, param1, instead of the typical light values, instead represents the probability of that node appearing in the structure. When passed to minetest.create_schematic, probability is an integer value ranging from 0 to 255: - A probability value of 0 means that node will never appear (0% chance). @@ -451,6 +528,7 @@ Important note: Node aliases cannot be used for a raw schematic provided when re Schematic attributes --------------------- +See section Flag Specifier Format. Currently supported flags: place_center_x, place_center_y, place_center_z - place_center_x Placement of this decoration is centered along the X axis. @@ -473,6 +551,7 @@ values can be used. The offset field specifies a pixel offset from the position. Contrary to position, the offset is not scaled to screen size. This allows for some precisely-positioned items in the HUD. +Note offset WILL adapt to screen dpi as well as user defined scaling factor! Below are the specific uses for fields in each type; fields not listed for that type are ignored. Note: Future revisions to the HUD API may be incompatible; the HUD API is still in the experimental stages. @@ -502,11 +581,18 @@ Note: Future revisions to the HUD API may be incompatible; the HUD API is still If odd, will end with a vertically center-split texture. - direction - offset: offset in pixels from position. + - size: If used will force full-image size to this value (override texture pack image size) - inventory - text: The name of the inventory list to be displayed. - number: Number of items in the inventory to be displayed. - item: Position of item that is selected. - direction +- waypoint + Displays distance to selected world position. + - name: The name of the waypoint. + - text: Distance suffix. Can be blank. + - number: An integer containing the RGB value of the color used to draw the text. + - world_pos: World position of the waypoint. Representations of simple things -------------------------------- @@ -519,6 +605,26 @@ pointed_thing: {type="node", under=pos, above=pos} {type="object", ref=ObjectRef} +Flag Specifier Format +----------------------- +Flags using the standardized flag specifier format can be specified in either of two ways, by string or table. +The string format is a comma-delimited set of flag names; whitespace and unrecognized flag fields are ignored. +Specifying a flag in the string sets the flag, and specifying a flag prefixed by the string "no" explicitly +clears the flag from whatever the default may be. +In addition to the standard string flag format, the schematic flags field can also be a table of flag names +to boolean values representing whether or not the flag is set. Additionally, if a field with the flag name +prefixed with "no" is present, mapped to a boolean of any value, the specified flag is unset. + +e.g. A flag field of value + {place_center_x = true, place_center_y=false, place_center_z=true} +is equivalent to + {place_center_x = true, noplace_center_y=true, place_center_z=true} +which is equivalent to + "place_center_x, noplace_center_y, place_center_z" +or even + "place_center_x, place_center_z" +since, by default, no schematic attributes are set. + Items ------ Node (register_node): @@ -531,16 +637,16 @@ Craftitem (register_craftitem): Items and item stacks can exist in three formats: Serialized; This is called stackstring or itemstring: -eg. 'default:dirt 5' -eg. 'default:pick_wood 21323' -eg. 'default:apple' +e.g. 'default:dirt 5' +e.g. 'default:pick_wood 21323' +e.g. 'default:apple' Table format: -eg. {name="default:dirt", count=5, wear=0, metadata=""} +e.g. {name="default:dirt", count=5, wear=0, metadata=""} ^ 5 dirt nodes -eg. {name="default:pick_wood", count=1, wear=21323, metadata=""} - ^ a wooden pick about 1/3 weared out -eg. {name="default:apple", count=1, wear=0, metadata=""} +e.g. {name="default:pick_wood", count=1, wear=21323, metadata=""} + ^ a wooden pick about 1/3 worn out +e.g. {name="default:apple", count=1, wear=0, metadata=""} ^ an apple. ItemStack: @@ -574,7 +680,7 @@ You can read the rating of a group for an item or a node by using Groups of items ---------------- -Groups of items can define what kind of an item it is (eg. wool). +Groups of items can define what kind of an item it is (e.g. wool). Groups of nodes ---------------- @@ -587,7 +693,7 @@ 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". -object.get_armor_groups() -> a group-rating table (eg. {fleshy=100}) +object.get_armor_groups() -> a group-rating table (e.g. {fleshy=100}) object.set_armor_groups({fleshy=30, cracky=80}) Groups of tools @@ -618,8 +724,8 @@ Special groups --------------- - immortal: Disables the group damage system for an entity - level: Can be used to give an additional sense of progression in the game. - - A larger level will cause eg. a weapon of a lower level make much less - damage, and get weared out much faster, or not be able to get drops + - 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 @@ -642,9 +748,9 @@ 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; eg. leaves, small +- snappy: something that can be cut using fine tools; e.g. leaves, small plants, wire, sheets of metal -- choppy: something that can be cut using force; eg. trees, wooden planks +- choppy: something that can be cut using force; e.g. trees, wooden planks - fleshy: Living things like animals and the player. This could imply some blood effects when hitting. - explody: Especially prone to explosions @@ -663,7 +769,7 @@ Item groups are often used for defining, well, //groups of items//. - eatable: anything that can be eaten. Rating might define HP gain in half hearts. - flammable: can be set on fire. Rating might define the intensity of the - fire, affecting eg. the speed of the spreading of an open fire. + fire, affecting e.g. the speed of the spreading of an open fire. - wool: any wool (any origin, any color) - metal: any metal - weapon: any weapon @@ -696,12 +802,12 @@ groups to enable interaction with tools. **Full punch interval**: When used as a weapon, the tool will do full damage if this time is spent -between punches. If eg. half the time is spent, the tool will do half +between punches. If e.g. half the time is spent, the tool 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. (eg. iron ore to drop a lump of iron). +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 @@ -720,7 +826,7 @@ be able to dig. **Digging 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 tool to be able to dig nodes that have a rating of 2 or 3 for this group, and unable to dig the rating 1, which is the toughest. Unless there is a matching group that enables digging otherwise. @@ -739,7 +845,7 @@ tool_capabilities = { damage_groups = {fleshy=2}, } -This makes the tool be able to dig nodes that fullfill both of these: +This makes the tool be able to dig nodes that fulfil both of these: - Have the **crumbly** group - Have a **level** group less or equal to 2 @@ -771,12 +877,12 @@ damage = 0 foreach group in cap.damage_groups: damage += cap.damage_groups[group] * limit(actual_interval / cap.full_punch_interval, 0.0, 1.0) * (object.armor_groups[group] / 100.0) - -- Where object.armor_groups[group] is 0 for inexisting values + -- Where object.armor_groups[group] is 0 for inexistent values return damage Client predicts damage based on damage groups. Because of this, it is able to give an immediate response when an entity is damaged or dies; the response is -pre-defined somehow (eg. by defining a sprite animation) (not implemented; +pre-defined somehow (e.g. by defining a sprite animation) (not implemented; TODO). - Currently a smoke puff will appear when an entity dies. @@ -821,7 +927,7 @@ Example stuff: local meta = minetest.get_meta(pos) meta:set_string("formspec", - "invsize[8,9;]".. + "size[8,9]".. "list[context;main;0,0;8,4;]".. "list[current_player;main;0,5;8,4;]") meta:set_string("infotext", "Chest"); @@ -833,7 +939,7 @@ meta:from_table({ main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", [10] = "", [11] = "", [12] = "", [13] = "", [14] = "default:cobble", [15] = "", [16] = "", [17] = "", [18] = "", [19] = "", [20] = "default:cobble", [21] = "", [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", [32] = ""} }, fields = { - formspec = "invsize[8,9;]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", + formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", infotext = "Chest" } }) @@ -848,17 +954,17 @@ examples. Examples: - Chest: - invsize[8,9;] + size[8,9] list[context;main;0,0;8,4;] list[current_player;main;0,5;8,4;] - Furnace: - invsize[8,9;] + size[8,9] list[context;fuel;2,3;1,1;] list[context;src;2,1;1,1;] list[context;dst;5,1;2,2;] list[current_player;main;0,5;8,4;] - Minecraft-like player inventory - invsize[8,7.5;] + size[8,7.5] image[1,0.6;1,2;player.png] list[current_player;main;0,3.5;8,4;] list[current_player;craft;3,0;3,3;] @@ -866,8 +972,9 @@ Examples: Elements: -size[,] +size[,,] ^ Define the size of the menu in inventory slots +^ fixed_size true/false (optional) ^ deprecated: invsize[,;] list[;;,;,;] @@ -887,8 +994,14 @@ listcolors[;;;;;;,] +^ Adds tooltip for an element +^ tooltip background color in HEX-Color format (optional) +^ tooltip font color in HEX-Color format (optional) + image[,;,;] ^ Show an image @@ -950,7 +1063,7 @@ label[,;