X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=8b2b81c7512d5fa1124fb1705bb11c40b2a10b2e;hb=3e419ffb38df3f802ed30c5e114b8b3e8b7a6c1f;hp=798ea607c5f259d54c2594ec0e3869d369f0f840;hpb=8ecfd88d92b0c8bf695f862b76077488127ab33f;p=oweals%2Fminetest.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 798ea607c..8b2b81c75 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -25,7 +25,7 @@ If you have any difficulty in understanding this, please read: Startup -------- Mods are loaded during server startup from the mod load paths by running -the init.lua scripts. +the init.lua scripts in a shared environment. Mod load path ------------- @@ -46,6 +46,25 @@ On an installed version on linux: ~/.minetest/mods/gameid/ <-- User-installed mods ~/.minetest/worlds/worldname/worldmods +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 happens if the following directory exists: + $world/game/ + +Mods should be then be placed in: + $world/game/mods/ + +Modpack support +---------------- +Mods can be put in a subdirectory, if the parent directory, which otherwise +should be a mod, contains a file named modpack.txt. This file shall be +empty, except for lines starting with #, which are comments. + Mod directory structure ------------------------ mods @@ -167,43 +186,124 @@ Examples of sound parameter tables: -- Play connected to an object, looped { object = , - gain = 1.0, -- default - max_hear_distance = 32, -- default + gain = 1.0, -- default + max_hear_distance = 32, -- default loop = true, -- only sounds connected to objects can be looped } -Representations of simple things +SimpleSoundSpec: +eg. "" +eg. "default_place_node" +eg. {} +eg. {name="default_place_node"} +eg. {name="default_place_node", gain=1.0} + +Registered definitions of stuff -------------------------------- -MapNode representation: - {name="name", param1=num, param2=num} +Anything added using certain minetest.register_* functions get added to +the global minetest.registered_* tables. + +minetest.register_entity(name, prototype table) + -> minetest.registered_entities[name] + +minetest.register_node(name, node definition) + -> minetest.registered_items[name] + -> minetest.registered_nodes[name] + +minetest.register_tool(name, item definition) + -> minetest.registered_items[name] + +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 +existence before trying to access the fields. + +Example: If you want to check the drawtype of a node, you could do: + +local function get_nodedef_field(nodename, fieldname) + if not minetest.registered_nodes[nodename] then + return nil + end + return minetest.registered_nodes[nodename][fieldname] +end +local drawtype = get_nodedef_field(nodename, "drawtype") + +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] +end -MapNodes do not directly have any other data associated with them. -If you want to access the definition of the node, you access +Nodes +------ +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 minetest.registered_nodes[node.name] +See "Registered definitions of stuff". -param1 and param2 are 8 bit and 4 bit integers, respectively. They -are reserved for certain automated functions. If you don't use these +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 is reserved for the engine when: - paramtype != "none" +The functions of param1 and param2 are determined by certain fields in the +node definition: +param1 is reserved for the engine when paramtype != "none": + paramtype = "light" + ^ The value stores light with and without sun in it's + upper and lower 4 bits. param2 is reserved for the engine when any of these are used: liquidtype == "flowing" + ^ The level and some flags of the liquid is stored in param2 drawtype == "flowingliquid" + ^ The drawn liquid level is read from param2 drawtype == "torchlike" drawtype == "signlike" + paramtype2 == "wallmounted" + ^ The rotation of the node is stored in param2. You can make this value + by using minetest.dir_to_wallmounted(). + 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(). + +Nodes can also contain extra data. See "Node Metadata". +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. -stackstring/itemstring: A stack of items in serialized format. +Items +------ +Node (register_node): + A node from the world +Tool (register_tool): + A tool/weapon that can dig and damage things according to tool_capabilities +Craftitem (register_craftitem): + A miscellaneous item + +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' -item: A stack of items in Lua table format. +Table format: eg. {name="default:dirt", count=5, wear=0, metadata=""} ^ 5 dirt nodes eg. {name="default:pick_wood", count=1, wear=21323, metadata=""} @@ -211,24 +311,12 @@ eg. {name="default:pick_wood", count=1, wear=21323, metadata=""} eg. {name="default:apple", count=1, wear=0, metadata=""} ^ an apple. -Any time an item must be passed to a function, it can be an -ItemStack (see below), an itemstring or a table in the above format. - -SimpleSoundSpec: -eg. "" -eg. "default_place_node" -eg. {} -eg. {name="default_place_node"} -eg. {name="default_place_node", gain=1.0} +ItemStack: +C++ native format with many helper methods. Useful for converting between +formats. See the Class reference section for details. -Items ------- -Node (register_node): - A node from the world -Tool (register_tool): - A tool/weapon that can dig and damage things according to tool_capabilities -Craftitem (register_craftitem): - A miscellaneous item +When an item must be passed to a function, it can usually be in any of +these formats. Groups ------- @@ -249,6 +337,9 @@ Usage: - When not defined, the rating of a group defaults to 0. Thus when you read groups, you must interpret nil and 0 as the same value, 0. +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 can define what kind of an item it is (eg. wool). @@ -281,7 +372,7 @@ Groups in crafting recipes {'group:water'}, {'group:bowl'}, }, - preserve = {'group:bowl'}, + preserve = {'group:bowl'}, } Special groups @@ -313,7 +404,7 @@ Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated. 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 larger speed than this + speed of a tool if the tool can dig at a faster speed than this suggests for the hand. Examples of custom groups @@ -369,9 +460,9 @@ it's useful item. (eg. iron ore to drop a lump of iron). 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. -- uses=10, leveldiff=0 -> actual_uses=10 -- uses=10, leveldiff=1 -> actual_uses=30 -- uses=10, leveldiff=2 -> actual_uses=90 +- uses=10, leveldiff=0 -> actual uses: 10 +- uses=10, leveldiff=1 -> actual uses: 30 +- uses=10, leveldiff=2 -> actual uses: 90 **Maximum level** Tells what is the maximum level of a node of this group that the tool will @@ -381,7 +472,7 @@ be able to dig. 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 the tool to be able to dig nodes that have a rating of 2 or 3 + 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 @@ -427,7 +518,7 @@ Entity damage mechanism Damage calculation: - Take the time spent after the last hit - Limit time to full_punch_interval -- Take the damage groups, assume a node has them +- 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. Client predicts damage based on damage groups. Because of this, it is able to @@ -436,28 +527,119 @@ pre-defined somehow (eg. by defining a sprite animation) (not implemented; TODO). - Currently a smoke puff will appear when an entity dies. -The group **immortal** will completely disable normal damage. +The group **immortal** completely disables normal damage. Entities can define a special armor group, which is **punch_operable**. This -group will disable the regular damage mechanism for players punching it by hand -or a non-tool item. +group 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. On the Lua side, every punch calls ''entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction)''. This should never be called directly, because damage is usually not handled by the entity itself. * ''puncher'' is the object performing the punch. Can be nil. Should never be - accessed unless absolutely required. + accessed unless absolutely required, to encourage interoperability. * ''time_from_last_punch'' is time from last punch (by puncher) or nil. * ''tool_capabilities'' can be nil. * ''direction'' is a unit vector, pointing from the source of the punch to the punched object. -To punch an entity/object in Lua, call ''object:punch(puncher, time_from_last_punch, tool_capabilities, direction)''. +To punch an entity/object in Lua, call ''object:punch(puncher, +time_from_last_punch, tool_capabilities, direction)''. * Return value is tool wear. * Parameters are equal to the above callback. * If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be automatically filled in based on the location of ''puncher''. +Node Metadata +------------- +The instance of a node in the world normally only contains the three values +mentioned in "Nodes". However, it is possible to insert extra data into a +node. It is called "node metadata"; See "NodeMetaRef". + +Metadata contains two things: +- A key-value store +- An inventory + +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 + +Example stuff: + +local meta = minetest.env:get_meta(pos) +meta:set_string("formspec", + "invsize[8,9;]".. + "list[current_name;main;0,0;8,4;]".. + "list[current_player;main;0,5;8,4;]") +meta:set_string("infotext", "Chest"); +local inv = meta:get_inventory() +inv:set_size("main", 8*4) +print(dump(meta:to_table())) +meta:from_table({ + inventory = { + 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;]", + infotext = "Chest" + } +}) + +Formspec +-------- +Formspec defines a menu. Currently not much else than inventories are +supported. It is a string, with a somewhat strange format. + +Spaces and newlines can be inserted between the blocks, as is used in the +examples. + +Examples: +- Chest: + invsize[8,9;] + list[current_name;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[current_player;main;0,5;8,4;] +- Minecraft-like player inventory + invsize[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;] + list[current_player;craftpreview;7,1;1,1;] + +Elements: + +invsize[,;] +^ Define the size of the menu in inventory slots + +list[;;,;,;] +^ Show an inventory list + +image[,;,;] +^ Show an image +^ Position and size units are inventory slots + +field[,;,;;