X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=ebba40fbf2245fbe0e9d35a09e70ad3117ca5274;hb=b850f0f03829cbb024d22672de0af29cab001d86;hp=d3d427d69dff15213dd621839801d3c08cca6166;hpb=53066024f6a91d5f83241b379b94d8557d43a646;p=dragonfireclient.git

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index d3d427d69..ebba40fbf 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -421,6 +421,40 @@ The default value is simple, and is currently the only type supported.
     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
 -------------------
@@ -849,6 +883,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
@@ -876,6 +919,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
@@ -888,6 +937,13 @@ image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
 ^ image 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
+^ image 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
+
 item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]
 ^ x, y, w, h, name and label work as per button
 ^ item name is the registered name of an item/node,
@@ -900,6 +956,42 @@ 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
+^ listelements can be prepended by #colorkey (see colorkeys), 
+^    if you want a listelement to start with # write ##
+^ name fieldname sent to server on doubleclick value is current selected element
+
+tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>;<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>;<colorkey>]
+^ 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)
+
+Available colorkeys:
+- YLW yellow
+- GRN green
+- LIM lime
+- ORN orange
+- RED red
+- BLU blue
+- CYN cyan
+- BLK black
+- BRN brown
+- WHT white
+- GRY grey
+
 Inventory location:
 
 - "context": Selected node metadata (deprecated: "current_name")
@@ -1000,6 +1092,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)
@@ -1018,7 +1113,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)
@@ -1081,6 +1175,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
@@ -1249,6 +1355,23 @@ minetest.delete_particlespawner(id, player)
 ^ If playername is specified, only deletes on the player's client,
 ^ otherwise on all clients
 
+Schematics:
+minetest.create_schematic(p1, p2, probability_list, filename)
+^ Create a schematic from the volume of map specified by the box formed by p1 and p2.
+^ 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 -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, rotation)
+^ 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.
+
 Random:
 minetest.get_connected_players() -> list of ObjectRefs
 minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
@@ -1257,6 +1380,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
@@ -1293,15 +1420,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
@@ -1482,6 +1600,75 @@ 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
+
+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:
@@ -1710,7 +1897,7 @@ 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
-    drowning = true, -- Player will drown in these
+    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
@@ -1904,6 +2091,25 @@ Decoration definition (register_decoration)
     num_spawn_by = 1,
     ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
     ^ If absent or -1, decorations occur next to any nodes.
+
+    ----- Schematic-type parameters
+    schematic = "foobar.mts",
+    ^ 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 = {
+            {name="cobble", param1=0, param2=0},
+            {name="dirt_with_grass", param1=0, param2=0},
+             ...
+        }
+    },
+    ^ See 'Schematic specifier' for details.
+    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)