- 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
+ 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
Ore attributes
-------------------
+See section Flag Specifier Format.
Currently supported flags: absheight
- absheight
Also produce this same ore between the height range of -height_max and -height_min.
- 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
+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).
Schematic attributes
---------------------
+See section Flag Specifier Format.
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.
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.
+Note offset WILL adapt to screen dpi as well as user defined scaling factor!
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.
If odd, will end with a vertically center-split texture.
- direction
- offset: offset in pixels from position.
+ - size: If used will force full-image size to this value (override texture pack image size)
- 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
+- waypoint
+ Displays distance to selected world position.
+ - name: The name of the waypoint.
+ - text: Distance suffix. Can be blank.
+ - number: An integer containing the RGB value of the color used to draw the text.
+ - world_pos: World position of the waypoint.
Representations of simple things
--------------------------------
{type="node", under=pos, above=pos}
{type="object", ref=ObjectRef}
+Flag Specifier Format
+-----------------------
+Flags using the standardized flag specifier format can be specified in either of two ways, by string or table.
+The string format is a comma-delimited set of flag names; whitespace and unrecognized flag fields are ignored.
+Specifying a flag in the string sets the flag, and specifying a flag prefixed by the string "no" explicitly
+clears the flag from whatever the default may be.
+In addition to the standard string flag format, the schematic flags field can also be a table of flag names
+to boolean values representing whether or not the flag is set. Additionally, if a field with the flag name
+prefixed with "no" is present, mapped to a boolean of any value, the specified flag is unset.
+
+e.g. A flag field of value
+ {place_center_x = true, place_center_y=false, place_center_z=true}
+is equivalent to
+ {place_center_x = true, noplace_center_y=true, place_center_z=true}
+which is equivalent to
+ "place_center_x, noplace_center_y, place_center_z"
+or even
+ "place_center_x, place_center_z"
+since, by default, no schematic attributes are set.
+
Items
------
Node (register_node):
eg. 'default:apple'
Table format:
-eg. {name="default:dirt", count=5, wear=0, metadata=""}
+eg. {name="default:dirt", count=5, wear=0, metadata=""}
^ 5 dirt nodes
eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
^ a wooden pick about 1/3 weared out
local meta = minetest.get_meta(pos)
meta:set_string("formspec",
- "invsize[8,9;]"..
+ "size[8,9]"..
"list[context;main;0,0;8,4;]"..
"list[current_player;main;0,5;8,4;]")
meta:set_string("infotext", "Chest");
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[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
+ formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
infotext = "Chest"
}
})
Examples:
- Chest:
- invsize[8,9;]
+ size[8,9]
list[context;main;0,0;8,4;]
list[current_player;main;0,5;8,4;]
- Furnace:
- invsize[8,9;]
+ size[8,9]
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;]
+ size[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;]
Elements:
-size[<W>,<H>]
+size[<W>,<H>,<fixed_size>]
^ Define the size of the menu in inventory slots
+^ fixed_size true/false (optional)
^ deprecated: invsize[<W>,<H>;]
list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]
^ label is the text on the label
^ Position and size units are inventory slots
-button[<X>,<Y>;<W>,<H>;<name>;<label>]
+button[<X>,<Y>;<W>,<H>;<name>;<label>;<tooltip>]
^ Clickable button. When clicked, fields will be sent.
^ x, y and name work as per field
^ w and h are the size of the button
^ label is the text on the button
^ Position and size units are inventory slots
+^ tooltip is optional
image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
^ 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
-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>]
+image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>;<tooltip>]
^ 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
+^ tooltip is optional
item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]
^ x, y, w, h, name and label work as per button
^ index of currently selected dropdown item
^ color in hexadecimal format RRGGBB (only)
-checkbox[<X>,<Y>;<name>;<label>;<selected>]
+checkbox[<X>,<Y>;<name>;<label>;<selected>;<tooltip>]
^ 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
+^ tooltip (optional)
table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]
^ show scrollable table using options defined by the previous tableoptions[]
^^ span=<value> number of following columns to affect (default infinite)
Note: do NOT use a element name starting with "key_" those names are reserved to
-pass key press events to formspec!
+pass key press events to formspec!
Inventory location:
minetest.has_feature(arg) -> bool, missing_features
^ arg: string or table in format {foo=true, bar=true}
^ missing_features: {foo=true, bar=true}
+minetest.get_player_information(playername)
+^ table containing information about player peer:
+{
+ address = "127.0.0.1", -- ip address of client
+ ip_version = 4, -- IPv4 / IPv6
+ min_rtt = 0.01, -- minimum round trip time
+ max_rtt = 0.2, -- maximum round trip time
+ avg_rtt = 0.02, -- average round trip time
+ min_jitter = 0.01, -- minimum packet time jitter
+ max_jitter = 0.5, -- maximum packet time jitter
+ avg_jitter = 0.03, -- average packet time jitter
+ connection_uptime = 200, -- seconds since client connected
+
+ -- following information is available on debug build only!!!
+ -- DO NOT USE IN MODS
+ --ser_vers = 26, -- serialization version used by client
+ --prot_vers = 23, -- protocol version used by client
+ --major = 0, -- major version number
+ --minor = 4, -- minor version number
+ --patch = 10, -- patch version number
+ --vers_string = "0.4.9-git", -- full version string
+ --state = "Active" -- current client state
+}
Logging:
minetest.debug(line)
^ Called when a node has been dug.
^ Not recommended: Use on_destruct or after_dig_node in node definition
^ whenever possible
-minetest.register_on_punchnode(func(pos, node, puncher))
+minetest.register_on_punchnode(func(pos, node, puncher, pointed_thing))
^ Called when a node is punched
minetest.register_on_generated(func(minp, maxp, blockseed))
^ Called after generating a piece of world. Modifying nodes inside the area
^ The provided function should check that the position is protected by the mod
calling this function before it prints a message, if it does, to allow for
multiple protection mods.
+minetest.register_on_item_eat(func(hp_change, replace_with_item, itemstack, user, pointed_thing))
+^ Called when an item is eaten, by minetest.item_eat
+^ Return true or itemstack to cancel the default item eat response (ie: hp increase)
Other registration functions:
minetest.register_chatcommand(cmd, chatcommand definition)
Chat:
minetest.chat_send_all(text)
-minetest.chat_send_player(name, text, prepend)
-^ prepend: optional, if it is set to false "Server -!- " will not be prepended to the message
+minetest.chat_send_player(name, text)
Environment access:
^ Dig node with the same effects that a player would cause
minetest.punch_node(pos)
^ Punch node with the same effects that a player would cause
-
+
minetest.get_meta(pos) -- Get a NodeMetaRef at that position
minetest.get_node_timer(pos) -- Get NodeTimerRef
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.
+^ Takes a table as an argument with the fields mgname, seed, water_level, and flags.
^ 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
+^ flags contains a comma-delimited string of flags to set, or if the prefix "no" is attached, clears instead.
+^ flags is in the same format and has the same options as 'mg_flags' in minetest.conf
+minetest.set_noiseparam_defaults({np1=NoiseParams, np2= NoiseParams, ...})
+^ Sets the default value of a noiseparam setting
+^ Takes a table as an argument that maps one or more setting names to NoiseParams structures
+^ Possible setting names consist of any NoiseParams setting exposed through the global settings
minetest.clear_objects()
^ clear all objects in the environments
minetest.line_of_sight(pos1, pos2, stepsize) -> true/false, pos
^ 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
^ returns indexed table with all registered recipes for query item (node)
or nil if no recipe was found
recipe entry table:
- {
+ {
method = 'normal' or 'cooking' or 'fuel'
width = 0-3, 0 means shapeless recipe
items = indexed [1-9] table with recipe items
^ Eat the item. replace_with_item can be nil.
Defaults for the on_punch and on_dig node definition callbacks:
-minetest.node_punch(pos, node, puncher)
+minetest.node_punch(pos, node, puncher, pointed_thing)
^ Calls functions registered by minetest.register_on_punchnode()
minetest.node_dig(pos, node, digger)
^ Checks if node can be dug, puts item into inventory, removes node
minetest.get_ban_description(ip_or_name) -> ban description (string)
minetest.ban_player(name) -> ban a player
minetest.unban_player_or_ip(name) -> unban player or IP address
+minetest.kick_player(name, [reason]) -> disconnect a player with a optional reason
Particles:
minetest.add_particle(particle definition)
^ If slice probability list is nil, no slice probabilities are applied.
^ Saves schematic in the Minetest Schematic format to filename.
-minetest.place_schematic(pos, schematic, rotation, replacements)
+minetest.place_schematic(pos, schematic, rotation, replacements, force_placement)
^ 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"}, ...}
+^ force_placement is a boolean indicating whether nodes other than air and
+^ ignore are replaced by the schematic
Random:
minetest.get_connected_players() -> list of ObjectRefs
- to_table() -> nil or {fields = {...}, inventory = {list1 = {}, ...}}
- from_table(nil or {})
^ See "Node Metadata"
-
+
NodeTimerRef: Node Timers - a high resolution persistent per-node timer
- Can be gotten via minetest.get_node_timer(pos)
methods:
^ flags: (is visible) hotbar, healthbar, crosshair, wielditem
^ pass a table containing a true/false value of each flag to be set or unset
^ if a flag is nil, the flag is not modified
+- hud_get_flags(): returns a table containing status of hud flags
+ ^ returns { hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true }
- hud_set_hotbar_itemcount(count): sets number of items in builtin hotbar
^ count: number of items, must be between 1 and 23
- hud_set_hotbar_image(texturename)
^ sets background image for hotbar
- hud_set_hotbar_selected_image(texturename)
^ sets image for selected item of hotbar
+- hud_replace_builtin(name, hud definition)
+ ^ replace definition of a builtin hud element
+ ^ name: "breath" or "health"
+ ^ hud definition: definition to replace builtin definition
+- set_sky(bgcolor, type, {texture names})
+ ^ bgcolor: {r=0...255, g=0...255, b=0...255} or nil, defaults to white
+ ^ Available types:
+ - "regular": Uses 0 textures, bgcolor ignored
+ - "skybox": Uses 6 textures, bgcolor used
+ - "plain": Uses 0 textures, bgcolor used
+ ^ Note: currently does not work directly in on_joinplayer; use
+ minetest.after(0) in there.
+- override_day_night_ratio(ratio or nil)
+ ^ 0...1: Overrides day-night ratio, controlling sunlight to a specific amount
+ ^ nil: Disables override, defaulting to sunlight based on day-night cycle
+- set_local_animation({x=0, y=79}, {x=168, y=187}, {x=189, y=198}, {x=200, y=219}, frame_speed=30): set animation for player model in third person view
+ ^ stand/idle animation key frames
+ ^ walk animation key frames
+ ^ dig animation key frames
+ ^ walk+dig animation key frames
+ ^ animation frame speed
+- set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0}): defines offset value for camera per player
+ ^ in first person view
+ ^ in third person view (max. values {x=-10/10,y=-10,15,z=-5/5})
InvRef: Reference to an inventory
methods:
^ 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
+ ^ 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, p1, p2): Set the lighting within the VoxelManip to a uniform value
^ light is a table, {day=<0...15>, night=<0...15>}
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
+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
+ 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
+ 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
+ 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
+ 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
+ Returns an array containing the humidity values of nodes in the most recently generated chunk by the
current mapgen.
- gennotify
Entity definition (register_entity)
{
(Deprecated: Everything in object properties is read directly from here)
-
+
initial_properties = <initial object properties>,
on_activate = function(self, staticdata, dtime_s),
get_staticdata = function(self),
^ Called sometimes; the string returned is passed to on_activate when
the entity is re-activated from static state
-
+
# Also you can define arbitrary member variables here
myvariable = whatever,
}
post_effect_color = {a=0, r=0, g=0, b=0}, -- If player is inside node
paramtype = "none", -- See "Nodes"
paramtype2 = "none", -- See "Nodes"
- is_ground_content = false, -- Currently not used for anything
+ is_ground_content = true, -- If false, cavegen will not carve through this
sunlight_propagates = false, -- If true, sunlight will go infinitely through this
walkable = true, -- If true, objects collide with node
pointable = true, -- If true, can be pointed at
can_dig = function(pos,player)
^ returns true if node can be dug, or false if not
^ default: nil
-
- on_punch = func(pos, node, puncher),
+
+ on_punch = func(pos, node, puncher, pointed_thing),
^ default: minetest.node_punch
- ^ By default: does nothing
+ ^ By default: Calls minetest.register_on_punchnode callbacks
on_rightclick = func(pos, node, clicker, itemstack, pointed_thing),
^ default: nil
^ if defined, itemstack will hold clicker's wielded item
^ Shall return the leftover itemstack
^ Note: pointed_thing can be nil, if a mod calls this function
-
+
on_dig = func(pos, node, digger),
^ default: minetest.node_dig
^ By default: checks privileges, wears out tool and removes node
-
+
on_timer = function(pos,elapsed),
^ default: nil
^ called by NodeTimers, see minetest.get_node_timer and NodeTimerRef
to_list, to_index, count, player),
^ Called when a player wants to move items inside the inventory
^ Return value: number of items allowed to move
-
+
allow_metadata_inventory_put = func(pos, listname, index, stack, player),
^ Called when a player wants to put something into the inventory
^ Return value: number of items allowed to put
^ Return value: -1: Allow and don't modify item count in inventory
-
+
allow_metadata_inventory_take = func(pos, listname, index, stack, player),
^ Called when a player wants to take something out of the inventory
^ Return value: number of items allowed to take
on_metadata_inventory_take = func(pos, listname, index, stack, player),
^ Called after the actual action has happened, according to what was allowed.
^ No return value
-
+
on_blast = func(pos, intensity),
^ intensity: 1.0 = mid range of regular TNT
^ If defined, called when an explosion touches the node, instead of
Chatcommand definition (register_chatcommand)
{
- params = "<name> <privilege>", -- short parameter description
- description = "Remove privilege from player", -- full description
- privs = {privs=true}, -- require the "privs" privilege to run
- func = function(name, param), -- called when command is run
+ params = "<name> <privilege>", -- Short parameter description
+ description = "Remove privilege from player", -- Full description
+ privs = {privs=true}, -- Require the "privs" privilege to run
+ func = function(name, param), -- Called when command is run.
+ -- Returns boolean success and text output.
}
Detached inventory callbacks
allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
^ Called when a player wants to move items inside the inventory
^ Return value: number of items allowed to move
-
+
allow_put = func(inv, listname, index, stack, player),
^ Called when a player wants to put something into the inventory
^ Return value: number of items allowed to put
^ Return value: -1: Allow and don't modify item count in inventory
-
+
allow_take = func(inv, listname, index, stack, player),
^ Called when a player wants to take something out of the inventory
^ Return value: number of items allowed to take
^ Return value: -1: Allow and don't modify item count in inventory
-
+
on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
on_put = func(inv, listname, index, stack, player),
on_take = func(inv, listname, index, stack, player),
^ See "HUD Element Types"
offset = {x=0, y=0},
^ See "HUD Element Types"
+ size = { x=100, y=100 },
+ ^ Size of element in pixels
}
Particle definition (add_particle)