X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=af70a1047672ffbb098ce4ac93f9a6a784f78818;hb=6291fd1cbb9c2808e336532c833e26330ff2642b;hp=5e0f2f1185ce8327ea9614d170d14bcdd131fe22;hpb=c3658e7c797cbf5b9d04a6d950505d37dcdd422b;p=dragonfireclient.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 5e0f2f118..f593b0db8 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -1,6 +1,7 @@ -Minetest Lua Modding API Reference 0.4.dev -========================================== -More information at http://c55.me/minetest/ +Minetest Lua Modding API Reference 0.4.7 +======================================== +More information at http://www.minetest.net/ +Developer Wiki: http://dev.minetest.net/ Introduction ------------- @@ -27,13 +28,42 @@ Startup Mods are loaded during server startup from the mod load paths by running 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: + +RUN_IN_PLACE=0: (Linux release) + $path_share: Linux: /usr/share/minetest + Windows: /minetest-0.4.x + $path_user: Linux: ~/.minetest + Windows: C:/users//AppData/minetest (maybe) + +Games +----- +Games are looked up from: + $path_share/games/gameid/ + $path_user/games/gameid/ +where gameid is unique to each game. + +The game directory contains the file game.conf, which contains these fields: + name = +eg. + name = Minetest + +The game directory can contain the file minetest.conf, which will be used +to set default settings when running the particular game. + Mod load path ------------- Generic: $path_share/games/gameid/mods/ - $path_share/mods/gameid/ + $path_share/mods/ $path_user/games/gameid/mods/ - $path_user/mods/gameid/ <-- User-installed mods + $path_user/mods/ <-- User-installed mods $worldpath/worldmods/ In a run-in-place version (eg. the distributed windows version): @@ -87,6 +117,17 @@ depends.txt: List of mods that have to be loaded before loading this mod. A single line contains a single modname. + Optional dependencies can be defined by appending a question mark + to a single modname. Their meaning is that if the specified mod + is missing, that does not prevent this mod from being loaded. + +optdepends.txt: + An alternative way of specifying optional dependencies. + Like depends.txt, a single line contains a single modname. + + NOTE: This file exists for compatibility purposes only and + support for it will be removed from the engine by the end of 2013. + init.lua: The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on minetest calling the @@ -170,18 +211,18 @@ from the available ones of the following files: Examples of sound parameter tables: -- Play locationless on all clients { - gain = 1.0, -- default + gain = 1.0, -- default } -- Play locationless to a player { - to_player = name, - gain = 1.0, -- default + to_player = name, + gain = 1.0, -- default } -- Play in a location { - pos = {x=1,y=2,z=3}, - gain = 1.0, -- default - max_hear_distance = 32, -- default + pos = {x=1,y=2,z=3}, + gain = 1.0, -- default + max_hear_distance = 32, -- default } -- Play connected to an object, looped { @@ -233,11 +274,11 @@ local drawtype = get_nodedef_field(nodename, "drawtype") Example: minetest.get_item_group(name, group) has been implemented as: function minetest.get_item_group(name, group) - if not minetest.registered_items[name] or not - minetest.registered_items[name].groups[group] then - return 0 - end - return minetest.registered_items[name].groups[group] + if not minetest.registered_items[name] or not + minetest.registered_items[name].groups[group] then + return 0 + end + return minetest.registered_items[name].groups[group] end Nodes @@ -254,9 +295,9 @@ Nodes are passed by value between Lua and the engine. They are represented by a table: {name="name", param1=num, param2=num} -param1 and param2 are 8 bit and 4 bit integers, respectively. The engine -uses them for certain automated functions. If you don't use these -functions, you can use them to store arbitrary values. +param1 and param2 are 8 bit integers. The engine uses them for certain +automated functions. If you don't use these functions, you can use them to +store arbitrary values. The functions of param1 and param2 are determined by certain fields in the node definition: @@ -277,15 +318,203 @@ param2 is reserved for the engine when any of these are used: paramtype2 == "facedir" ^ 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(). + Values range 0 - 23 + facedir modulo 4 = axisdir + 0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y- + facedir's two less significant bits are rotation around the axis + paramtype2 == "leveled" + ^ The drawn node level is read from param2, like flowingliquid Nodes can also contain extra data. See "Node Metadata". +Node drawtypes +--------------- +There are a bunch of different looking node types. These are mostly just +copied from Minetest 0.3; more may be made in the future. + +Look for examples in games/minimal or games/minetest_game. + +- normal +- airlike +- liquid +- flowingliquid +- glasslike +- glasslike_framed +- allfaces +- allfaces_optional +- torchlike +- signlike +- plantlike +- fencelike +- raillike +- nodebox -- See below. EXPERIMENTAL + +Node boxes +----------- +Node selection boxes are defined using "node boxes" + +The "nodebox" node drawtype allows defining visual of nodes consisting of +arbitrary number of boxes. It allows defining stuff like stairs. Only the +"fixed" and "leveled" box type is supported for these. +^ Please note that this is still experimental, and may be incompatibly + changed in the future. + +A nodebox is defined as any of: +{ + -- A normal cube; the default in most things + type = "regular" +} +{ + -- A fixed box (facedir param2 is used, if applicable) + type = "fixed", + fixed = box OR {box1, box2, ...} +} +{ + -- A box like the selection box for torches + -- (wallmounted param2 is used, if applicable) + type = "wallmounted", + wall_top = box, + wall_bottom = box, + wall_side = box +} + +A box is defined as: + {x1, y1, z1, x2, y2, z2} +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 + +Ore types +--------------- +These tell in what manner the ore is generated. +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 + 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. + 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. +- claylike - NOT YET IMPLEMENTED + Places ore if there are no more than clust_scarcity number of specified nodes within a Von Neumann + neighborhood of clust_size radius. + +Ore attributes +------------------- +Currently supported flags: absheight + - absheight + Also produce this same ore between the height range of -height_max and -height_min. + Useful for having ore in sky realms without having to duplicate ore entries. + +Decoration types +------------------- +The varying types of decorations that can be placed. +The default value is simple, and is currently the only type supported. + +- simple + Creates a 1xHx1 column of a specified node (or a random node from a list, if a decoration + list is specified). Can specify a certain node it must spawn next to, such as water or lava, + for example. Can also generate a decoration of random height between a specified lower and + upper bound. This type of decoration is intended for placement of grass, flowers, cacti, + papyrus, and so on. +- schematic + Copies a box of MapNodes from a specified schematic file (or raw description). Can specify a + probability of a node randomly appearing when placed. This decoration type is intended to be used + for multi-node sized discrete structures, such as trees, cave spikes, rocks, and so on. + +Schematic specifier +-------------------- + A schematic specifier identifies a schematic by either a filename to a Minetest Schematic file (.mts) +or through raw data supplied through Lua, in the form of a table. This table must specify two fields: + - The 'size' field is a 3d vector containing the dimensions of the provided schematic. + - 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 +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). + - A probability value of 255 means the node will always appear (100% chance). + - If the probability value p is greater than 0, then there is a (p / 256 * 100)% chance that node + will appear when the schematic is placed on the map. + +Important note: Node aliases cannot be used for a raw schematic provided when registering as a decoration. + +Schematic attributes +--------------------- +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. + - place_center_y + Placement of this decoration is centered along the Y axis. + - place_center_z + Placement of this decoration is centered along the Z axis. + +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 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. +The alignment field specifies how the item will be aligned. It ranges from -1 to 1, +with 0 being the center, -1 is moved to the left/up, and 1 is to the right/down. Fractional +values can be used. +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. +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. + +- image + Displays an image on the HUD. + - scale: The scale of the image, with 1 being the original texture size. + Only the X coordinate scale is used. + - text: The name of the texture that is displayed. + - alignment: The alignment of the image. + - offset: offset in pixels from position. +- text + Displays text on the HUD. + - scale: Defines the bounding rectangle of the text. + A value such as {x=100, y=100} should work. + - text: The text to be displayed in the HUD element. + - number: An integer containing the RGB value of the color used to draw the text. + Specify 0xFFFFFF for white text, 0xFF0000 for red, and so on. + - alignment: The alignment of the text. + - offset: offset in pixels from position. +- statbar + Displays a horizontal bar made up of half-images. + - text: The name of the texture that is used. + - number: The number of half-textures that are displayed. + If odd, will end with a vertically center-split texture. + - direction + - offset: offset in pixels from position. +- 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 + Representations of simple things -------------------------------- Position/vector: {x=num, y=num, z=num} -Currently the API does not provide any helper functions for addition, -subtraction and whatever; you can define those that you need yourself. +For helper functions see "Vector helpers". + +pointed_thing: + {type="nothing"} + {type="node", under=pos, above=pos} + {type="object", ref=ObjectRef} Items ------ @@ -329,7 +558,7 @@ Usage: - Groups are stored in a table, having the group names with keys and the group ratings as values. For example: groups = {crumbly=3, soil=1} - ^ Default dirt (soil group actually currently not defined; TODO) + ^ Default dirt groups = {crumbly=2, soil=1, level=2, outerspace=1} ^ A more special dirt-kind of thing - Groups always have a rating associated with them. If there is no @@ -352,9 +581,11 @@ a node is destroyable and how long it takes to destroy by a tool. 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". -object.get_armor_groups() -> a group-rating table (eg. {fleshy=3}) -object.set_armor_groups({level=2, fleshy=2, cracky=2}) +object.get_armor_groups() -> a group-rating table (eg. {fleshy=100}) +object.set_armor_groups({fleshy=30, cracky=80}) Groups of tools ---------------- @@ -363,8 +594,7 @@ effective towards. Groups in crafting recipes --------------------------- -- Not implemented yet. (TODO) -- Will probably look like this: +An example: Make meat soup from any meat, any water and any bowl { output = 'food:meat_soup_raw', recipe = { @@ -372,7 +602,13 @@ Groups in crafting recipes {'group:water'}, {'group:bowl'}, }, - preserve = {'group:bowl'}, + -- preserve = {'group:bowl'}, -- Not implemented yet (TODO) +} +An another example: Make red wool from white wool and red dye +{ + type = 'shapeless', + output = 'wool:red', + recipe = {'wool:white', 'group:dye,basecolor_red'}, } Special groups @@ -381,17 +617,26 @@ Special groups - 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 - from destroyed nodes. + from destroyed nodes. - 0 is something that is directly accessible at the start of gameplay - There is no upper limit - dig_immediate: (player can always pick up node without tool wear) - 2: node is removed without tool wear after 0.5 seconds or so (rail, sign) - 3: node is removed without tool wear immediately (torch) +- disable_jump: Player (and possibly other things) cannot jump from node +- fall_damage_add_percent: damage speed = speed * (1 + value/100) +- bouncy: value is bounce speed in percent +- falling_node: if there is no walkable block under the node it will fall +- attached_node: if the node under it is not a walkable block the node will be + dropped as an item. If the node is wallmounted the + wallmounted direction is checked. +- soil: saplings will grow on nodes in this group +- connect_to_raillike: makes nodes of raillike drawtype connect to + other group members with same drawtype Known damage and digging time defining groups ---------------------------------------------- -Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated. - crumbly: dirt, sand - cracky: tough but crackable stuff like stone. - snappy: something that can be cut using fine tools; eg. leaves, small @@ -444,6 +689,7 @@ groups to enable interaction with tools. * Uses (until the tool breaks) * Maximum level (usually 0, 1, 2 or 3) * Digging times + * Damage groups **Full punch interval**: When used as a weapon, the tool will do full damage if this time is spent @@ -475,17 +721,19 @@ maximum level. 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. - * For entities, damage equals the amount of nodes dug in the time spent - between hits, with a maximum time of ''full_punch_interval''. + +**Damage groups** +List of damage for groups of entities. See "Entity damage mechanism". Example definition of the capabilities of a tool ------------------------------------------------- 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}} - } + 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 tool be able to dig nodes that fullfill both of these: @@ -516,10 +764,12 @@ Notes: Entity damage mechanism ------------------------ Damage calculation: -- Take the time spent after the last hit -- Limit time to full_punch_interval -- Take the damage groups and imagine a bunch of nodes that have them -- Damage in HP is the amount of nodes destroyed in this time. +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 +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 @@ -566,10 +816,10 @@ Some of the values in the key-value store are handled specially: Example stuff: -local meta = minetest.env:get_meta(pos) +local meta = minetest.get_meta(pos) meta:set_string("formspec", "invsize[8,9;]".. - "list[current_name;main;0,0;8,4;]".. + "list[context;main;0,0;8,4;]".. "list[current_player;main;0,5;8,4;]") meta:set_string("infotext", "Chest"); local inv = meta:get_inventory() @@ -580,7 +830,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[current_name;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", + formspec = "invsize[8,9;]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", infotext = "Chest" } }) @@ -596,13 +846,13 @@ examples. Examples: - Chest: invsize[8,9;] - list[current_name;main;0,0;8,4;] + list[context;main;0,0;8,4;] list[current_player;main;0,5;8,4;] - Furnace: invsize[8,9;] - list[current_name;fuel;2,3;1,1;] - list[current_name;src;2,1;1,1;] - list[current_name;dst;5,1;2,2;] + 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;] @@ -613,32 +863,193 @@ Examples: Elements: -invsize[,;] +size[,] ^ Define the size of the menu in inventory slots +^ deprecated: invsize[,;] list[;;,;,;] +list[;;,;,;] ^ Show an inventory list image[,;,;] ^ Show an image ^ Position and size units are inventory slots +item_image[,;,;] +^ Show an inventory image of registered item/node +^ Position and size units are inventory slots + +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*16px x 4*16px + +pwdfield[,;,;;