X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=67ff823dad0af065d155b868da3dff18e697a45e;hb=45589fae58157c8a66c640a1db5795a42a86fc1c;hp=de73ecd3f517eb11b8d1d33a1cdbcf0f9abcd239;hpb=2fb0e547a01a6e61b821737e61315bad3312e41e;p=minetest.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index de73ecd3f..67ff823da 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -1,6 +1,7 @@ -Minetest Lua Modding API Reference 0.4.6 +Minetest Lua Modding API Reference 0.4.7 ======================================== -More information at http://c55.me/minetest/ +More information at http://www.minetest.net/ +Developer Wiki: http://dev.minetest.net/ Introduction ------------- @@ -50,12 +51,8 @@ where gameid is unique to each game. The game directory contains the file game.conf, which contains these fields: name = - common_mods = eg. name = Minetest - common_mods = bucket, default, doors, fire, stairs - -Common mods are loaded from the pseudo-game "common". The game directory can contain the file minetest.conf, which will be used to set default settings when running the particular game. @@ -64,9 +61,9 @@ 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): @@ -120,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 @@ -314,6 +322,8 @@ param2 is reserved for the engine when any of these are used: 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". @@ -329,6 +339,7 @@ Look for examples in games/minimal or games/minetest_game. - liquid - flowingliquid - glasslike +- glasslike_framed - allfaces - allfaces_optional - torchlike @@ -344,7 +355,7 @@ 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" box type is supported for these. +"fixed" and "leveled" box type is supported for these. ^ Please note that this is still experimental, and may be incompatibly changed in the future. @@ -372,6 +383,8 @@ 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 + Ore types --------------- These tell in what manner the ore is generated. @@ -401,12 +414,104 @@ Currently supported flags: 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]]]. + +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 -1 to 255: + - A probability value of 0 means that node will always appear. + - A probability value of -1 means the node will never appear. + - 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. + +If registering a structure in the raw format, however, -1 is not a valid probability value; in order to +have a node that is not placed, it must be CONTENT_IGNORE (the name for which is "ignore"). + +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"} @@ -455,7 +560,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 @@ -528,6 +633,9 @@ Special groups - 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 ---------------------------------------------- @@ -710,7 +818,7 @@ 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[context;main;0,0;8,4;]".. @@ -778,6 +886,15 @@ background[,;,;] ^ Position and size units are inventory slots ^ Example for formspec 8x4 in 16x resolution: image shall be sized 8*16px x 4*16px +pwdfield[,;,;;