X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=67ff823dad0af065d155b868da3dff18e697a45e;hb=45589fae58157c8a66c640a1db5795a42a86fc1c;hp=0027b1c863ba812bfc538f64809e87fb86428b1b;hpb=c1b829077a3518f3a129eee11887b2358a53f20b;p=minetest.git

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 0027b1c86..67ff823da 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -322,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".
 
@@ -353,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.
 
@@ -381,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.
@@ -432,14 +436,22 @@ Schematic specifier
 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.  It is an integer with a value from 0-255; 0 means
-that node will always appear.  If the probability value p is non-zero, then there is a
-(p / 256 * 100)% chance that node will appear when the schematic is placed on the map.
+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.
@@ -499,8 +511,7 @@ 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"}
@@ -875,6 +886,15 @@ background[<X>,<Y>;<W>,<H>;<texture name>]
 ^ Position and size units are inventory slots
 ^ Example for formspec 8x4 in 16x resolution: image shall be sized 8*16px x 4*16px
 
+pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]
+^ Textual password style field; will be sent to server when a button is clicked
+^ x and y position the field relative to the top left of the menu
+^ w and h are the size of the field
+^ fields are a set height, but will be vertically centred on h
+^ Position and size units are inventory slots
+^ name is the name of the field as returned in fields to on_receive_fields
+^ label, if not blank, will be text printed on the top left above the field
+
 field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
 ^ Textual field; will be sent to server when a button is clicked
 ^ x and y position the field relative to the top left of the menu
@@ -902,6 +922,12 @@ label[<X>,<Y>;<label>]
 ^ label is the text on the label
 ^ Position and size units are inventory slots
 
+vertlabel[<X>,<Y>;<label>]
+^ Textual label drawn verticaly
+^ x and y work as per field
+^ label is the text on the label
+^ Position and size units are inventory slots
+
 button[<X>,<Y>;<W>,<H>;<name>;<label>]
 ^ Clickable button. When clicked, fields will be sent.
 ^ x, y and name work as per field
@@ -911,8 +937,23 @@ button[<X>,<Y>;<W>,<H>;<name>;<label>]
 
 image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
 ^ x, y, w, h, and name work as per button
-^ image is the filename of an image
+^ texture name is the filename of an image
+^ Position and size units are inventory slots
+
+image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>]
+^ x, y, w, h, and name work as per button
+^ texture name is the filename of an image
 ^ Position and size units are inventory slots
+^ noclip true meand imagebutton doesn't need to be within specified formsize
+^ drawborder draw button bodrer or not
+
+image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]
+^ x, y, w, h, and name work as per button
+^ texture name is the filename of an image
+^ Position and size units are inventory slots
+^ noclip true meand imagebutton doesn't need to be within specified formsize
+^ drawborder draw button bodrer or not
+^ pressed texture name is the filename of an image on pressed state
 
 item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]
 ^ x, y, w, h, name and label work as per button
@@ -926,6 +967,58 @@ button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]
 image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
 ^ When clicked, fields will be sent and the form will quit.
 
+textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]
+^Scrollabel itemlist showing arbitrary text elements
+^ x and y position the itemlist relative to the top left of the menu
+^ w and h are the size of the itemlist
+^ name fieldname sent to server on doubleclick value is current selected element
+^ listelements can be prepended by #colorkey (see colorkeys), 
+^    if you want a listelement to start with # write ##
+
+textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]
+^Scrollabel itemlist showing arbitrary text elements
+^ x and y position the itemlist relative to the top left of the menu
+^ w and h are the size of the itemlist
+^ name fieldname sent to server on doubleclick value is current selected element
+^ listelements can be prepended by #RRGGBB in hexadecimal format
+^    if you want a listelement to start with # write ##
+^ index to be selected within textlist
+^ true/false draw transparent background
+
+tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]
+^ show a tabHEADER at specific position (ignores formsize)
+^ x and y position the itemlist relative to the top left of the menu
+^ name fieldname data is transfered to lua
+^ caption 1... name shown on top of tab
+^ current_tab index of selected tab 1...
+^ transparent (optional) show transparent
+^ draw_border (optional) draw border
+
+box[<X>,<Y>;<W>,<H>;<color>]
+^ simple colored semitransparent box
+^ x and y position the box relative to the top left of the menu
+^ w and h are the size of box
+^ colorkey (see colorkeys)
+
+dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]
+^ show a dropdown field
+^ x and y position of dropdown
+^ width of dropdown
+^ fieldname data is transfered to lua
+^ items to be shown in dropdown
+^ index of currently selected dropdown item
+^ color in hexadecimal format RRGGBB
+
+checkbox[<X>,<Y>;<name>;<label>;<selected>]
+^ show a checkbox
+^ x and y position of checkbox
+^ name fieldname data is transfered to lua
+^ label to be shown left of checkbox
+^ selected (optional) true/false
+
+Note: do NOT use a element name starting with "key_" those names are reserved to
+pass key press events to formspec! 
+
 Inventory location:
 
 - "context": Selected node metadata (deprecated: "current_name")
@@ -934,12 +1027,41 @@ Inventory location:
 - "nodemeta:<X>,<Y>,<Z>": Any node metadata
 - "detached:<name>": A detached inventory
 
+Vector helpers
+---------------
+vector.new([x[, y, z]]) -> vector
+ ^ x is a table or the x position.
+vector.direction(p1, p2) -> vector
+vector.distance(p1, p2) -> number
+vector.length(v) -> number
+vector.normalize(v) -> vector
+vector.round(v) -> vector
+vector.equal(v1, v2) -> bool
+vector.add(v, x) -> vector
+ ^ x can be annother vector or a number
+vector.subtract(v, x) -> vector
+vector.multiply(v, x) -> vector
+vector.divide(v, x) -> vector
+
+You can also use Lua operators on vectors.
+For example:
+	v1 = vector.new()
+	v1 = v1 + 5
+	v2 = vector.new(v1)
+	v1 = v1 * v2
+	if v1 == v2 then
+		error("Math broke")
+	end
+
 Helper functions
 -----------------
 dump2(obj, name="_", dumped={})
 ^ Return object serialized as a string, handles reference loops
 dump(obj, dumped={})
 ^ Return object serialized as a string
+math.hypot(x, y)
+^ Get the hypotenuse of a triangle with legs x and y.
+  Usefull for distance calculation.
 string:split(separator)
 ^ eg. string:split("a,b", ",") == {"a","b"}
 string:trim()
@@ -1026,6 +1148,9 @@ minetest.register_on_player_receive_fields(func(player, formname, fields))
 ^ Called when a button is pressed in player's inventory form
 ^ Newest functions are called first
 ^ If function returns true, remaining functions are not called
+minetest.register_on_mapgen_init(func(MapgenParams))
+^ Called just before the map generator is initialized but before the environment is initialized
+^ MapgenParams consists of a table with the fields mgname, seed, water_level, and flags
 
 Other registration functions:
 minetest.register_chatcommand(cmd, chatcommand definition)
@@ -1044,7 +1169,6 @@ minetest.setting_get(name) -> string or nil
 minetest.setting_getbool(name) -> boolean value or nil
 minetest.setting_get_pos(name) -> position or nil
 minetest.setting_save() -> nil, save all settings to config file
-minetest.add_to_creative_inventory(itemstring)
 
 Authentication:
 minetest.notify_authentication_modified(name)
@@ -1107,6 +1231,18 @@ minetest.find_nodes_in_area(minp, maxp, nodenames) -> list of positions
 ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
 minetest.get_perlin(seeddiff, octaves, persistence, scale)
 ^ Return world-specific perlin noise (int(worldseed)+seeddiff)
+minetest.get_voxel_manip()
+^ Return voxel manipulator object
+minetest.get_mapgen_object(objectname)
+^ Return requested mapgen object if available (see Mapgen objects)
+minetest.set_mapgen_params(MapgenParams)
+^ Set map generation parameters
+^ Function cannot be called after the registration period; only initialization and on_mapgen_init
+^ Takes a table as an argument with the fields mgname, seed, water_level, flags, and flagmask.
+^ Leave field unset to leave that parameter unchanged
+^ flagmask field must be set to all mapgen flags that are being modified
+^ flags contains only the flags that are being set
+^ flags and flagmask are in the same format and have the same options as 'mgflags' in minetest.conf
 minetest.clear_objects()
 ^ clear all objects in the environments
 minetest.line_of_sight(pos1,pos2,stepsize) ->true/false
@@ -1126,6 +1262,20 @@ minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)
 ^ algorithm: A*_noprefetch(default), A*, Dijkstra
 minetest.spawn_tree (pos, {treedef})
 ^ spawns L-System tree at given pos with definition in treedef table
+minetest.transforming_liquid_add(pos)
+^ add node to liquid update queue
+minetest.get_node_max_level(pos)
+^ get max available level for leveled node
+minetest.get_node_level(pos)
+^ get level of leveled node (water, snow)
+minetest.set_node_level(pos, level)
+^ set level of leveled node, default level = 1, if totallevel > maxlevel returns rest (total-max).
+minetest.add_node_level(pos, level)
+^ increase level of leveled node by level, default level = 1, if totallevel > maxlevel returns rest (total-max). can be negative for decreasing
+minetest.get_heat(pos)
+^ heat at pos
+minetest.get_humidity(pos)
+^ humidity at pos
 
 Inventory:
 minetest.get_inventory(location) -> InvRef
@@ -1146,8 +1296,10 @@ minetest.inventorycube(img1, img2, img3)
 ^ Returns a string for making an image of a cube (useful as an item image)
 minetest.get_pointed_thing_position(pointed_thing, above)
 ^ Get position of a pointed_thing (that you can get from somewhere)
-minetest.dir_to_facedir(dir)
-^ Convert a vector to a facedir value, used in param2 for paramtype2="facedir"
+minetest.dir_to_facedir(dir, is6d)
+^ Convert a vector to a facedir value, used in param2 for paramtype2="facedir"; passing something non-nil/false for the optional second parameter causes it to take the y component into account
+minetest.facedir_to_dir(facedir)
+^ Convert a facedir back into a vector aimed directly out the "back" of a node
 minetest.dir_to_wallmounted(dir)
 ^ Convert a vector to a wallmounted value, used for paramtype2="wallmounted"
 minetest.get_node_drops(nodename, toolname)
@@ -1281,14 +1433,17 @@ minetest.create_schematic(p1, p2, probability_list, filename)
 ^ Apply the specified probability values to the specified nodes in probability_list.
    ^ probability_list is an array of tables containing two fields, pos and prob.
    ^ pos is the 3d vector specifying the absolute coordinates of the node being modified,
-   ^ and prob is the integer value from 0 to 255 of the probability (see: Schematic specifier).
+   ^ and prob is the integer value from -1 to 255 of the probability (see: Schematic specifier).
    ^ If there are two or more entries with the same pos value, the last occuring in the array is used.
    ^ If pos is not inside the box formed by p1 and p2, it is ignored.
    ^ If probability_list is nil, no probabilities are applied.
 ^ Saves schematic in the Minetest Schematic format to filename.
 
-minetest.place_schematic(pos, schematic)
+minetest.place_schematic(pos, schematic, rotation, replacements)
 ^ Place the schematic specified by schematic (see: Schematic specifier) at pos.
+^ Rotation can be "0", "90", "180", "270", or "random".
+^ If the rotation parameter is omitted, the schematic is not rotated.
+^ replacements = {{"oldname", "convert_to"}, ...}
 
 Random:
 minetest.get_connected_players() -> list of ObjectRefs
@@ -1298,6 +1453,10 @@ minetest.get_item_group(name, group) -> rating
 ^ Get rating of a group of an item. (0 = not in group)
 minetest.get_node_group(name, group) -> rating
 ^ Deprecated: An alias for the former.
+minetest.get_content_id(name) -> integer
+^ Gets the internal content ID of name
+minetest.get_name_from_content_id(content_id) -> string
+^ Gets the name of the content with that content ID
 minetest.serialize(table) -> string
 ^ Convert a table containing tables, strings, numbers, booleans and nils
   into string form readable by minetest.deserialize
@@ -1334,15 +1493,6 @@ minetest.object_refs
 minetest.luaentities
 ^ List of lua entities, indexed by active object id
 
-Deprecated but defined for backwards compatibility:
-minetest.digprop_constanttime(time)
-minetest.digprop_stonelike(toughness)
-minetest.digprop_dirtlike(toughness)
-minetest.digprop_gravellike(toughness)
-minetest.digprop_woodlike(toughness)
-minetest.digprop_leaveslike(toughness)
-minetest.digprop_glasslike(toughness)
-
 Class reference
 ----------------
 NodeMetaRef: Node metadata - reference extra data and functionality stored
@@ -1433,6 +1583,11 @@ Player-only: (no-op for other objects)
 - get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
 - set_look_pitch(radians): sets look pitch
 - set_look_yaw(radians): sets look yaw
+- get_breath() : returns players breath
+- set_breath(value) : sets players breath
+    values: 0    player is drowning,
+            1-10 number of bubbles remain,
+            11   bubbles bar is not shown
 - set_inventory_formspec(formspec)
   ^ Redefine player's inventory form
   ^ Should usually be called in on_joinplayer
@@ -1523,6 +1678,82 @@ methods:
 - get2d(pos) -> 2d noise value at pos={x=,y=}
 - get3d(pos) -> 3d noise value at pos={x=,y=,z=}
 
+PerlinNoiseMap: A fast, bulk perlin noise generator
+- Can be created via PerlinNoiseMap(noiseparams, size)
+- Also minetest.get_perlin_map(noiseparams, size)
+methods:
+- get2dMap(pos) -> <size.x>X<size.y> 2d array of 2d noise values starting at pos={x=,y=}
+- get3dMap(pos) -> <size.x>X<size.y>X<size.z> 3d array of 3d noise values starting at pos={x=,y=,z=}
+- get2dMap_flat(pos) -> Flat <size.x * size.y> element array of 2d noise values starting at pos={x=,y=}
+- get3dMap_flat(pos) -> Same as get2dMap_flat, but 3d noise
+
+VoxelManip: An interface to the MapVoxelManipulator for Lua
+- Can be created via VoxelManip()
+- Also minetest.get_voxel_manip()
+methods:
+- read_from_map(p1, p2):  Reads a chunk of map from the map containing the region formed by p1 and p2.
+  ^ returns actual emerged pmin, actual emerged pmax
+- write_to_map():  Writes the data loaded from the VoxelManip back to the map.
+  ^ important: data must be set using VoxelManip:set_data before calling this
+- get_data():  Gets the data read into the VoxelManip object
+  ^ returns raw node data is in the form of an array of node content ids
+- set_data(data):  Sets the data contents of the VoxelManip object
+- update_map():  Update map after writing chunk back to map.
+  ^ To be used only by VoxelManip objects created by the mod itself; not a VoxelManip that was 
+  ^ retrieved from minetest.get_mapgen_object
+- set_lighting(light):  Set the lighting within the VoxelManip
+  ^ light is a table, {day=<0...15>, night=<0...15>}
+  ^ To be used only by a VoxelManip object from minetest.get_mapgen_object
+- calc_lighting():  Calculate lighting within the VoxelManip
+  ^ To be used only by a VoxelManip object from minetest.get_mapgen_object
+- update_liquids():  Update liquid flow
+
+VoxelArea: A helper class for voxel areas
+- Can be created via VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}
+- Coordinates are *inclusive*, like most other things in Minetest
+methods:
+- getExtent():  returns a 3d vector containing the size of the area formed by MinEdge and MaxEdge
+- getVolume():  returns the volume of the area formed by MinEdge and MaxEdge
+- index(x, y, z):  returns the index of an absolute position in a flat array starting at 1
+  ^ useful for things like VoxelManip, raw Schematic specifiers, PerlinNoiseMap:get2d/3dMap, and so on
+- indexp(p):  same as above, except takes a vector
+- position(i):  returns the absolute position vector corresponding to index i
+- contains(x, y, z):  check if (x,y,z) is inside area formed by MinEdge and MaxEdge
+- containsp(p):  same as above, except takes a vector
+- containsi(i):  same as above, except takes an index
+- iter(minx, miny, minz, maxx, maxy, maxz):  returns an iterator that returns indices
+  ^ from (minx,miny,minz) to (maxx,maxy,maxz) in the order of [z [y [x]]]
+- iterp(minp, maxp):  same as above, except takes a vector
+
+Mapgen objects
+---------------
+A mapgen object is a construct used in map generation.  Mapgen objects can be used by an on_generate 
+callback to speed up operations by avoiding unnecessary recalculations; these can be retrieved using the 
+minetest.get_mapgen_object() function.  If the requested Mapgen object is unavailable, or 
+get_mapgen_object() was called outside of an on_generate() callback, nil is returned.
+
+The following Mapgen objects are currently available:
+
+- voxelmanip
+    This returns three values; the VoxelManip object to be used, minimum and maximum emerged position, in that 
+order.  All mapgens support this object.
+
+- heightmap
+    Returns an array containing the y coordinates of the ground levels of nodes in the most recently 
+generated chunk by the current mapgen.
+
+- biomemap
+    Returns an array containing the biome IDs of nodes in the most recently generated chunk by the 
+current mapgen.
+
+- heatmap
+    Returns an array containing the temperature values of nodes in the most recently generated chunk by 
+the current mapgen.
+
+- humiditymap
+    Returns an array containing the humidity values of nodes in the most recently generated chunk by the 
+current mapgen.
+
 Registered entities
 --------------------
 - Functions receive a "luaentity" as self:
@@ -1617,6 +1848,7 @@ Object Properties
 {
     hp_max = 1,
     physical = true,
+    collide_with_objects = true, -- collide with other objects if physical=true
     weight = 5,
     collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
     visual = "cube"/"sprite"/"upright_sprite"/"mesh",
@@ -1629,6 +1861,7 @@ Object Properties
     is_visible = true,
     makes_footstep_sound = false,
     automatic_rotate = false,
+    stepheight = 0,
 }
 
 Entity definition (register_entity)
@@ -1673,6 +1906,7 @@ Item definition (register_node, register_craftitem, register_tool)
     wield_image = "",
     wield_scale = {x=1,y=1,z=1},
     stack_max = 99,
+    range = 4.0,
     liquids_pointable = false,
     tool_capabilities = {
         full_punch_interval = 1.0,
@@ -1751,6 +1985,10 @@ Node definition (register_node)
     liquid_alternative_source = "", -- Source version of flowing liquid
     liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
     liquid_renewable = true, -- Can new liquid source be created by placing
+    freezemelt = "", -- water for snow/ice, ice/snow for water
+    leveled = 0, -- Block contain level in param2. value - default level, used for snow. Dont forget use "leveled" type nodebox
+    liquid_range = 8, -- number of flowing nodes arround source (max. 8)
+    drowning = true, -- Player will drown in these 
     two or more sources nearly?
     light_source = 0, -- Amount of light emitted by node
     damage_per_second = 0, -- If player is inside node, this damage is caused
@@ -1892,6 +2130,7 @@ Ore definition (register_ore)
     ore_type = "scatter", -- See "Ore types"
     ore = "default:stone_with_coal",
     wherein = "default:stone",
+    ^ a list of nodenames is supported too
     clust_scarcity = 8*8*8,
     ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
     ^ This value should be *MUCH* higher than your intuition might tell you!
@@ -1950,10 +2189,20 @@ Decoration definition (register_decoration)
     ^ If schematic is a string, it is the filepath relative to the current working directory of the
     ^ specified Minetest schematic file.
     ^  - OR -, could instead be a table containing two fields, size and data:
-    schematic = {size = {x=4, y=6, z=4}, data = { {"cobble", 0, 0}, {"dirt_with_grass", 0, 0}, ...}},
+    schematic = {
+        size = {x=4, y=6, z=4},
+        data = {
+            {name="cobble", param1=0, param2=0},
+            {name="dirt_with_grass", param1=0, param2=0},
+             ...
+        }
+    },
     ^ See 'Schematic specifier' for details.
+    replacements = {{"oldname", "convert_to"}, ...},
     flags = "place_center_x, place_center_z",
     ^ Flags for schematic decorations.  See 'Schematic attributes'.
+    rotation = "90" --rotate schematic 90 degrees on placement
+    ^ Rotation can be "0", "90", "180", "270", or "random".
 }
 
 Chatcommand definition (register_chatcommand)