* `game.conf`, with the following keys:
* `name`: Required, human readable name e.g. `name = Minetest`
* `description`: Short description to be shown in the content tab
+ * `allowed_mapgens = <comma-separated mapgens>`
+ e.g. `allowed_mapgens = v5,v6,flat`
+ Mapgens not in this list are removed from the list of mapgens for
+ the game.
+ If not specified, all mapgens are allowed.
* `disallowed_mapgens = <comma-separated mapgens>`
e.g. `disallowed_mapgens = v5,v6,flat`
These mapgens are removed from the list of mapgens for the game.
+ When both `allowed_mapgens` and `disallowed_mapgens` are
+ specified, `allowed_mapgens` is applied before
+ `disallowed_mapgens`.
+ * `disallowed_mapgen_settings= <comma-separated mapgen settings>`
+ e.g. `disallowed_mapgen_settings = mgv5_spflags`
+ These settings are hidden for this game in the world creation
+ dialog and game start menu.
* `minetest.conf`:
Used to set default settings when running this game.
* `settingtypes.txt`:
* `player_damage`: Played when the local player takes damage (gain = 0.5)
* `player_falling_damage`: Played when the local player takes
damage by falling (gain = 0.5)
+ * `player_jump`: Played when the local player jumps
* `default_dig_<groupname>`: Default node digging sound
(see node sound definition for details)
* Values range 0 - 179. The value stored in `param2` is multiplied by two to
get the actual rotation in degrees of the node.
* `paramtype2 = "meshoptions"`
- * Only valid for "plantlike" drawtype. The value of `param2` becomes a
- bitfield which can be used to change how the client draws plantlike nodes.
- * Bits 0, 1 and 2 form a mesh selector.
- Currently the following meshes are choosable:
+ * Only valid for "plantlike" drawtype. `param2` encodes the shape and
+ optional modifiers of the "plant". `param2` is a bitfield.
+ * Bits 0 to 2 select the shape.
+ Use only one of the values below:
* 0 = a "x" shaped plant (ordinary plant)
* 1 = a "+" shaped plant (just rotated 45 degrees)
* 2 = a "*" shaped plant with 3 faces instead of 2
* 3 = a "#" shaped plant with 4 faces instead of 2
* 4 = a "#" shaped plant with 4 faces that lean outwards
* 5-7 are unused and reserved for future meshes.
- * Bits 3 through 7 are optional flags that can be combined and give these
- effects:
- * bit 3 (0x08) - Makes the plant slightly vary placement horizontally
- * bit 4 (0x10) - Makes the plant mesh 1.4x larger
- * bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
- * bits 6-7 are reserved for future use.
+ * Bits 3 to 7 are used to enable any number of optional modifiers.
+ Just add the corresponding value(s) below to `param2`:
+ * 8 - Makes the plant slightly vary placement horizontally
+ * 16 - Makes the plant mesh 1.4x larger
+ * 32 - Moves each face randomly a small bit down (1/8 max)
+ * values 64 and 128 (bits 6-7) are reserved for future use.
+ * Example: `param2 = 0` selects a normal "x" shaped plant
+ * Example: `param2 = 17` selects a "+" shaped plant, 1.4x larger (1+16)
* `paramtype2 = "color"`
* `param2` tells which color is picked from the palette.
The palette should have 256 pixels.
There are a bunch of different looking node types.
-Look for examples in `games/minimal` or `games/minetest_game`.
+Look for examples in `games/devtest` or `games/minetest_game`.
* `normal`
* A node-sized cube.
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.
+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 `z_index` field specifies the order of HUD elements from back to front.
Lower z-index elements are displayed behind higher z-index elements. Elements
with same z-index are displayed in an arbitrary order. Default 0.
-Supports negative values.
+Supports negative values. By convention, the following values are recommended:
+
+* -400: Graphical effects, such as vignette
+* -300: Name tags, waypoints
+* -200: Wieldhand
+* -100: Things that block the player's view, e.g. masks
+* 0: Default. For standard in-game HUD elements like crosshair, hotbar,
+ minimap, builtin statbars, etc.
+* 100: Temporary text messages or notification icons
+* 1000: Full-screen effects such as full-black screen or credits.
+ This includes effects that cover the entire screen
+* Other: If your HUD element doesn't fit into any category, pick a number
+ between the suggested values
+
+
Below are the specific uses for fields in each type; fields not listed for that
type are ignored.
text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
* `alignment`: The alignment of the text.
* `offset`: offset in pixels from position.
+* `size`: size of the text.
+ The player-set font size is multiplied by size.x (y value isn't used).
### `statbar`
-Displays a horizontal bar made up of half-images.
+Displays a horizontal bar made up of half-images with an optional background.
-* `text`: The name of the texture that is used.
+* `text`: The name of the texture to use.
+* `text2`: Optional texture name to enable a background / "off state"
+ texture (useful to visualize the maximal value). Both textures
+ must have the same size.
* `number`: The number of half-textures that are displayed.
If odd, will end with a vertically center-split texture.
-* `direction`
+* `item`: Same as `number` but for the "off state" texture
+* `direction`: To which direction the images will extend to
* `offset`: offset in pixels from position.
* `size`: If used, will force full-image size to this value (override texture
pack image size)
* `name`: The name of the waypoint.
* `text`: Distance suffix. Can be blank.
+* `precision`: Waypoint precision, integer >= 0. Defaults to 10.
+ If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`.
+ When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point.
+ `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`).
+ `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on:
+ `precision = n` will show multiples of `1/n`
* `number:` An integer containing the RGB value of the color used to draw the
text.
* `world_pos`: World position of the waypoint.
+* `offset`: offset in pixels from position.
+* `alignment`: The alignment of the waypoint.
+### `image_waypoint`
+
+Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint.
+
+* `scale`: The scale of the image, with 1 being the original texture size.
+ Only the X coordinate scale is used (positive values).
+ Negative values represent that percentage of the screen it
+ should take; e.g. `x=-100` means 100% (width).
+* `text`: The name of the texture that is displayed.
+* `alignment`: The alignment of the image.
+* `world_pos`: World position of the waypoint.
+* `offset`: offset in pixels from position.
* `2`: the node always gets the digging time 0.5 seconds (rail, sign)
* `3`: the node always gets the digging time 0 seconds (torch)
* `disable_jump`: Player (and possibly other things) cannot jump from node
+ or if their feet are in the node. Note: not supported for `new_move = false`
* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
* `falling_node`: if there is no walkable block under the node it will fall
* `float`: the node will not fall through liquids
* End of a container, following elements are no longer relative to this
container.
+### `scroll_container[<X>,<Y>;<W>,<H>;<scrollbar name>;<orientation>;<scroll factor>]`
+
+* Start of a scroll_container block. All contained elements will ...
+ * take the scroll_container coordinate as position origin,
+ * be additionally moved by the current value of the scrollbar with the name
+ `scrollbar name` times `scroll factor` along the orientation `orientation` and
+ * be clipped to the rectangle defined by `X`, `Y`, `W` and `H`.
+* `orientation`: possible values are `vertical` and `horizontal`.
+* `scroll factor`: optional, defaults to `0.1`.
+* Nesting is possible.
+* Some elements might work a little different if they are in a scroll_container.
+* Note: If you want the scroll_container to actually work, you also need to add a
+ scrollbar element with the specified name. Furthermore, it is highly recommended
+ to use a scrollbaroptions element on this scrollbar.
+
+### `scroll_container_end[]`
+
+* End of a scroll_container, following elements are no longer bound to this
+ container.
+
### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
* Show an inventory list if it has been sent to the client. Nothing will
### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>;<fontcolor>]`
* Adds tooltip for an element
-* `<bgcolor>` tooltip background color as `ColorString` (optional)
-* `<fontcolor>` tooltip font color as `ColorString` (optional)
+* `bgcolor` tooltip background color as `ColorString` (optional)
+* `fontcolor` tooltip font color as `ColorString` (optional)
### `tooltip[<X>,<Y>;<W>,<H>;<tooltip_text>;<bgcolor>;<fontcolor>]`
* Adds tooltip for an area. Other tooltips will take priority when present.
-* `<bgcolor>` tooltip background color as `ColorString` (optional)
-* `<fontcolor>` tooltip font color as `ColorString` (optional)
+* `bgcolor` tooltip background color as `ColorString` (optional)
+* `fontcolor` tooltip font color as `ColorString` (optional)
### `image[<X>,<Y>;<W>,<H>;<texture name>]`
* Show an image
-### `animated_image[<X>,<Y>;<W>,<H>;<texture name>:<frame count>,<frame duration>]`
+### `animated_image[<X>,<Y>;<W>,<H>;<name>;<texture name>;<frame count>;<frame duration>;<frame start>]`
* Show an animated image. The image is drawn like a "vertical_frames" tile
- animation (See Tile animation definition), but uses a frame count/duration
+ animation (See [Tile animation definition]), but uses a frame count/duration
for simplicity
-* `<texture name>` is the image to use
-* `<frame count>` is the number of frames animating the image
-* `<frame duration>` is in milliseconds
+* `name`: Element name to send when an event occurs. The event value is the index of the current frame.
+* `texture name`: The image to use.
+* `frame count`: The number of frames animating the image.
+* `frame duration`: Milliseconds between each frame. `0` means the frames don't advance.
+* `frame start` (Optional): The index of the frame to start on. Default `1`.
### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
* 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
* Middle is a rect which defines the middle of the 9-slice.
- * `x` - The middle will be x pixels from all sides.
- * `x,y` - The middle will be x pixels from the horizontal and y from the vertical.
- * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values
- will be added to the width and height of the texture, allowing it to be used as the
- distance from the far end.
- * All numbers in middle are integers.
+ * `x` - The middle will be x pixels from all sides.
+ * `x,y` - The middle will be x pixels from the horizontal and y from the vertical.
+ * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values
+ will be added to the width and height of the texture, allowing it to be used as the
+ distance from the far end.
+ * All numbers in middle are integers.
* Example for formspec 8x4 in 16x resolution:
image shall be sized 8 times 16px times 4 times 16px
* If `auto_clip` is `true`, the background is clipped to the formspec size
### `hypertext[<X>,<Y>;<W>,<H>;<name>;<text>]`
* Displays a static formatted text with hyperlinks.
+* **Note**: This element is currently unstable and subject to change.
* `x`, `y`, `w` and `h` work as per field
* `name` is the name of the field as returned in fields to `on_receive_fields` in case of action in text.
-* `text` is the formatted text using `markup language` described below.
+* `text` is the formatted text using `Markup Language` described below.
### `vertlabel[<X>,<Y>;<label>]`
* Textual label drawn vertically
* `name` fieldname data is transferred 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
+* `transparent` (optional): if true, tabs are semi-transparent
+* `draw_border` (optional): if true, draw a thin line at tab base
### `tabheader[<X>,<Y>;<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
* `span=<value>`: number of following columns to affect
(default: infinite).
-### `style[<name>;<prop1>;<prop2>;...]`
+### `style[<selector 1>,<selector 2>;<prop1>;<prop2>;...]`
-* Set the style for the named element `name`.
+* Set the style for the element(s) matching `selector` by name.
+* `selector` can be one of:
+ * `<name>` - An element name. Includes `*`, which represents every element.
+ * `<name>:<state>` - An element name, a colon, and one or more states.
+* `state` is a list of states separated by the `+` character.
+ * If a state is provided, the style will only take effect when the element is in that state.
+ * All provided states must be active for the style to apply.
* Note: this **must** be before the element is defined.
* See [Styling Formspecs].
-### `style_type[<type>;<prop1>;<prop2>;...]`
+### `style_type[<selector 1>,<selector 2>;<prop1>;<prop2>;...]`
-* Sets the style for all elements of type `type` which appear after this element.
+* Set the style for the element(s) matching `selector` by type.
+* `selector` can be one of:
+ * `<type>` - An element type. Includes `*`, which represents every element.
+ * `<type>:<state>` - An element type, a colon, and one or more states.
+* `state` is a list of states separated by the `+` character.
+ * If a state is provided, the style will only take effect when the element is in that state.
+ * All provided states must be active for the style to apply.
* See [Styling Formspecs].
Migrating to Real Coordinates
Formspec elements can be themed using the style elements:
- style[<name>;<prop1>;<prop2>;...]
- style_type[<type>;<prop1>;<prop2>;...]
+ style[<name 1>,<name 2>;<prop1>;<prop2>;...]
+ style[<name 1>:<state>,<name 2>:<state>;<prop1>;<prop2>;...]
+ style_type[<type 1>,<type 2>;<prop1>;<prop2>;...]
+ style_type[<type 1>:<state>,<type 2>:<state>;<prop1>;<prop2>;...]
Where a prop is:
style[world_delete;bgcolor=red;textcolor=yellow]
button[4,3.95;2.6,1;world_delete;Delete]
+A name/type can optionally be a comma separated list of names/types, like so:
+
+ world_delete,world_create,world_configure
+ button,image_button
+
+A `*` type can be used to select every element in the formspec.
+
+Any name/type in the list can also be accompanied by a `+`-separated list of states, like so:
+
+ world_delete:hovered+pressed
+ button:pressed
+
+States allow you to apply styles in response to changes in the element, instead of applying at all times.
+
Setting a property to nothing will reset it to the default value. For example:
style_type[button;bgimg=button.png;bgimg_pressed=button_pressed.png;border=false]
Some types may inherit styles from parent types.
+* animated_image, inherits from image
* button
* button_exit, inherits from button
* checkbox
* bgimg - standard background image. Defaults to none.
* bgimg_hovered - background image when hovered. Defaults to bgimg when not provided.
* bgimg_middle - Makes the bgimg textures render in 9-sliced mode and defines the middle rect.
- See background9[] documentation for more details
+ See background9[] documentation for more details. This property also pads the
+ button's content when set.
* bgimg_pressed - background image when pressed. Defaults to bgimg when not provided.
* border - boolean, draw border. Set to false to hide the bevelled button pane. Default true.
+ * content_offset - 2d vector, shifts the position of the button's content without resizing it.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * padding - rect, adds space between the edges of the button and the content. This value is
+ relative to bgimg_middle.
* textcolor - color, default white.
* checkbox
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* textcolor - color. Default white.
-Markup language
+### Valid States
+
+* *all elements*
+ * default - Equivalent to providing no states
+* button, button_exit, image_button, item_image_button
+ * hovered - Active when the mouse is hovering over the element
+ * pressed - Active when the button is pressed
+
+Markup Language
---------------
-Markup language used in `hypertext[]` elements uses tag that look like HTML tags. Some
-tags can enclose text, they open with `<tagname>` and close with `</tagname>`.
+Markup language used in `hypertext[]` elements uses tags that look like HTML tags.
+The markup language is currently unstable and subject to change. Use with caution.
+Some tags can enclose text, they open with `<tagname>` and close with `</tagname>`.
Tags can have attributes, in that case, attributes are in the opening tag in
form of a key/value separated with equal signs. Attribute values should not be quoted.
* `vector.divide(v, x)`:
* Returns a scaled vector or Schur quotient.
+For the following functions `a` is an angle in radians and `r` is a rotation
+vector ({x = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are
+angles in radians.
+
+* `vector.rotate(v, r)`:
+ * Applies the rotation `r` to `v` and returns the result.
+ * `vector.rotate({x = 0, y = 0, z = 1}, r)` and
+ `vector.rotate({x = 0, y = 1, z = 0}, r)` return vectors pointing
+ forward and up relative to an entity's rotation `r`.
+* `vector.rotate_around_axis(v1, v2, a)`:
+ * Returns `v1` rotated around axis `v2` by `a` radians according to
+ the right hand rule.
+* `vector.dir_to_rotation(direction[, up])`:
+ * Returns a rotation vector for `direction` pointing forward using `up`
+ as the up vector.
+ * If `up` is omitted, the roll of the returned vector defaults to zero.
+ * Otherwise `direction` and `up` need to be vectors in a 90 degree angle to each other.
+
`minetest.translate`, but is in translation files.
* `@n` acts as a literal newline as well.
+Server side translations
+------------------------
+
+On some specific cases, server translation could be useful. For example, filter
+a list on labels and send results to client. A method is supplied to achieve
+that:
+
+`minetest.get_translated_string(lang_code, string)`: Translates `string` using
+translations for `lang_code` language. It gives the same result as if the string
+was translated by the client.
+The `lang_code` to use for a given player can be retrieved from
+the table returned by `minetest.get_player_information(name)`.
+IMPORTANT: This functionality should only be used for sorting, filtering or similar purposes.
+You do not need to use this to get translated strings to show up on the client.
Perlin noise
============
preferable for this to be different from other seeds, but sometimes it is useful
to be able to create identical noise patterns.
-When used in mapgen this is actually a 'seed offset', it is added to the
-'world seed' to create the seed used by the noise, to ensure the noise has a
-different pattern in different worlds.
+In some noise APIs the world seed is added to the seed specified in noise
+parameters. This is done to make the resulting noise pattern vary in different
+worlds, and be 'world-specific'.
### `octaves`
* `dir`: unit vector of direction of punch. Always defined. Points from the
puncher to the punched.
* `damage`: damage that will be done to entity.
+ * Can return `true` to prevent the default damage mechanism.
* `on_death(self, killer)`
* Called when the object dies.
* `killer`: an `ObjectRef` (can be `nil`)
formspec_version_element = true,
-- Whether AreaStore's IDs are kept on save/load (5.1.0)
area_store_persistent_ids = true,
+ -- Whether minetest.find_path is functional (5.2.0)
+ pathfinder_works = true,
+ -- Whether Collision info is available to an objects' on_step (5.3.0)
+ object_step_has_moveresult = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
{
address = "127.0.0.1", -- IP address of client
ip_version = 4, -- IPv4 / IPv6
+ connection_uptime = 200, -- seconds since client connected
+ protocol_version = 32, -- protocol version used by client
+ formspec_version = 2, -- supported formspec version
+ lang_code = "fr" -- Language code used for translation
+ -- the following keys can be missing if no stats have been collected yet
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
- protocol_version = 32, -- protocol version used by client
- formspec_version = 2, -- supported formspec version
- -- following information is available on debug build only!!!
+ -- the following information is available in a debug build only!!!
-- DO NOT USE IN MODS
--ser_vers = 26, -- serialization version used by client
--major = 0, -- major version number
* Called after generating a piece of world. Modifying nodes inside the area
is a bit faster than usually.
* `minetest.register_on_newplayer(function(ObjectRef))`
- * Called after a new player has been created
+ * Called when a new player enters the world for the first time
* `minetest.register_on_punchplayer(function(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))`
* Called when a player is punched
* Note: This callback is invoked even if the punched player is dead.
* Called _before_ repositioning of player occurs
* return true in func to disable regular player placement
* `minetest.register_on_prejoinplayer(function(name, ip))`
- * Called before a player joins the game
- * If it returns a string, the player is disconnected with that string as
+ * Called when a client connects to the server, prior to authentication
+ * If it returns a string, the client is disconnected with that string as
reason.
-* `minetest.register_on_joinplayer(function(ObjectRef))`
+* `minetest.register_on_joinplayer(function(ObjectRef, last_login))`
* Called when a player joins the game
+ * `last_login`: The timestamp of the previous login, or nil if player is new
* `minetest.register_on_leaveplayer(function(ObjectRef, timed_out))`
* Called when a player leaves the game
* `timed_out`: True for timeout, false for other reasons.
+* `minetest.register_on_authplayer(function(name, ip, is_success))`
+ * Called when a client attempts to log into an account.
+ * `name`: The name of the account being authenticated.
+ * `ip`: The IP address of the client
+ * `is_success`: Whether the client was successfully authenticated
+ * For newly registered accounts, `is_success` will always be true
* `minetest.register_on_auth_fail(function(name, ip))`
- * Called when a client attempts to log into an account but supplies the
- wrong password.
- * `ip`: The IP address of the client.
- * `name`: The account the client attempted to log into.
+ * Deprecated: use `minetest.register_on_authplayer(name, ip, is_success)` instead.
* `minetest.register_on_cheat(function(ObjectRef, cheat))`
* Called when a player cheats
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
is a table containing each formspecs element value (as string), with
the `name` parameter as index for each. The value depends on the
formspec element type:
+ * `animated_image`: Returns the index of the current frame.
* `button` and variants: If pressed, contains the user-facing button
text as value. If not pressed, is `nil`
* `field`, `textarea` and variants: Text in the field
* The same as before, except that it is called before the player crafts, to
make craft prediction, and it should not change anything.
* `minetest.register_allow_player_inventory_action(function(player, action, inventory, inventory_info))`
- * Determinates how much of a stack may be taken, put or moved to a
+ * Determines how much of a stack may be taken, put or moved to a
player inventory.
* `player` (type `ObjectRef`) is the player who modified the inventory
`inventory` (type `InvRef`).
* `minetest.auth_reload()`
* See `reload()` in authentication handler definition
-`minetest.set_player_password`, `minetest_set_player_privs`,
-`minetest_get_player_privs` and `minetest.auth_reload` call the authentication
+`minetest.set_player_password`, `minetest.set_player_privs`,
+`minetest.get_player_privs` and `minetest.auth_reload` call the authentication
handler.
Chat
* Return value: Table with all node positions with a node air above
* Area volume is limited to 4,096,000 nodes
* `minetest.get_perlin(noiseparams)`
+ * Return world-specific perlin noise.
+ * The actual seed used is the noiseparams seed plus the world seed.
* `minetest.get_perlin(seeddiff, octaves, persistence, spread)`
- * Return world-specific perlin noise (`int(worldseed)+seeddiff`)
+ * Deprecated: use `minetest.get_perlin(noiseparams)` instead.
+ * Return world-specific perlin noise.
* `minetest.get_voxel_manip([pos1, pos2])`
* Return voxel manipulator object.
* Loads the manipulator from the map if positions are passed.
* `objects`: if false, only nodes will be returned. Default is `true`.
* `liquids`: if false, liquid nodes won't be returned. Default is `false`.
* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)`
- * returns table containing path
+ * returns table containing path that can be walked on
* returns a table of 3D points representing a path from `pos1` to `pos2` or
- `nil`.
+ `nil` on failure.
+ * Reasons for failure:
+ * No path exists at all
+ * No path exists within `searchdistance` (see below)
+ * Start or end pos is buried in land
* `pos1`: start position
* `pos2`: end position
- * `searchdistance`: number of blocks to search in each direction using a
- maximum metric.
+ * `searchdistance`: maximum distance from the search positions to search in.
+ In detail: Path must be completely inside a cuboid. The minimum
+ `searchdistance` of 1 will confine search between `pos1` and `pos2`.
+ Larger values will increase the size of this cuboid in all directions
* `max_jump`: maximum height difference to consider walkable
* `max_drop`: maximum height difference to consider droppable
- * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`
+ * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`.
+ Difference between `"A*"` and `"A*_noprefetch"` is that
+ `"A*"` will pre-calculate the cost-data, the other will calculate it
+ on-the-fly
* `minetest.spawn_tree (pos, {treedef})`
* spawns L-system tree at given `pos` with definition in `treedef` table
* `minetest.transforming_liquid_add(pos)`
* `minetest.add_node_level(pos, level)`
* increase level of leveled node by level, default `level` equals `1`
* if `totallevel > maxlevel`, returns rest (`total-max`)
- * can be negative for decreasing
+ * `level` must be between -127 and 127
* `minetest.fix_light(pos1, pos2)`: returns `true`/`false`
* resets the light in a cuboid-shaped part of
the map and removes lighting bugs.
given `param2` value.
* Returns `nil` if the given `paramtype2` does not contain color
information.
-* `minetest.get_node_drops(nodename, toolname)`
- * Returns list of item names.
- * **Note**: This will be removed or modified in a future version.
+* `minetest.get_node_drops(node, toolname)`
+ * Returns list of itemstrings that are dropped by `node` when dug
+ with `toolname`.
+ * `node`: node as table or node name
+ * `toolname`: name of the tool item (can be `nil`)
* `minetest.get_craft_result(input)`: returns `output, decremented_input`
* `input.method` = `"normal"` or `"cooking"` or `"fuel"`
* `input.width` = for example `3`
* Returns a code (0: successful, 1: no such player, 2: player is connected)
* `minetest.remove_player_auth(name)`: remove player authentication data
* Returns boolean indicating success (false if player nonexistant)
+* `minetest.dynamic_add_media(filepath)`
+ * Adds the file at the given path to the media sent to clients by the server
+ on startup and also pushes this file to already connected clients.
+ The file must be a supported image, sound or model format. It must not be
+ modified, deleted, moved or renamed after calling this function.
+ The list of dynamically added media is not persisted.
+ * Returns boolean indicating success (duplicate files count as error)
+ * The media will be ready to use (in e.g. entity textures, sound_play)
+ immediately after calling this function.
+ Old clients that lack support for this feature will not see the media
+ unless they reconnect to the server.
+ * Since media transferred this way does not use client caching or HTTP
+ transfers, dynamic media should not be used with big files or performance
+ will suffer.
Bans
----
* Convert a table containing tables, strings, numbers, booleans and `nil`s
into string form readable by `minetest.deserialize`
* Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
-* `minetest.deserialize(string)`: returns a table
- * Convert a string returned by `minetest.deserialize` into a table
+* `minetest.deserialize(string[, safe])`: returns a table
+ * Convert a string returned by `minetest.serialize` into a table
* `string` is loaded in an empty sandbox environment.
- * Will load functions, but they cannot access the global environment.
+ * Will load functions if safe is false or omitted. Although these functions
+ cannot directly access the global environment, they could bypass this
+ restriction with maliciously crafted Lua bytecode if mod security is
+ disabled.
+ * This function should not be used on untrusted data, regardless of the
+ value of `safe`. It is fine to serialize then deserialize user-provided
+ data, but directly providing user input to deserialize is always unsafe.
* Example: `deserialize('return { ["foo"] = "bar" }')`,
returns `{foo='bar'}`
* Example: `deserialize('print("foo")')`, returns `nil`
* Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
* `minetest.encode_base64(string)`: returns string encoded in base64
* Encodes a string in base64.
-* `minetest.decode_base64(string)`: returns string
+* `minetest.decode_base64(string)`: returns string or nil for invalid base64
* Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
* Returning `true` restricts the player `name` from modifying (i.e. digging,
* `minetest.record_protection_violation(pos, name)`
* This function calls functions registered with
`minetest.register_on_protection_violation`.
+* `minetest.is_creative_enabled(name)`: returns boolean
+ * Returning `true` means that Creative Mode is enabled for player `name`.
+ * `name` will be `""` for non-players or if the player is unknown.
+ * This function should be overridden by Creative Mode-related mods to
+ implement a per-player Creative Mode.
+ * By default, this function returns `true` if the setting
+ `creative_mode` is `true` and `false` otherwise.
* `minetest.is_area_protected(pos1, pos2, player_name, interval)`
* Returns the position of the first node that `player_name` may not modify
in the specified cuboid between `pos1` and `pos2`.
insecure functions if the calling mod has been listed as trusted in the
`secure.trusted_mods` setting or security is disabled, otherwise returns
`nil`.
- * Only works at init time and must be called from the mod's main scope (not
- from a function).
+ * Only works at init time and must be called from the mod's main scope
+ (ie: the init.lua of the mod, not from another Lua file or within a function).
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE
IT IN A LOCAL VARIABLE!**
* max: bubbles bar is not shown
* See [Object properties] for more information
* Is limited to range 0 ... 65535 (2^16 - 1)
-* `set_fov(fov, is_multiplier)`: Sets player's FOV
+* `set_fov(fov, is_multiplier, transition_time)`: Sets player's FOV
* `fov`: FOV value.
* `is_multiplier`: Set to `true` if the FOV value is a multiplier.
Defaults to `false`.
- * Set to 0 to clear FOV override.
-* `get_fov()`:
- * Returns player's FOV override in degrees, and a boolean depending on whether
- the value is a multiplier.
- * Returns 0 as first value if player's FOV hasn't been overridden.
+ * `transition_time`: If defined, enables smooth FOV transition.
+ Interpreted as the time (in seconds) to reach target FOV.
+ If set to 0, FOV change is instantaneous. Defaults to 0.
+ * Set `fov` to 0 to clear FOV override.
+* `get_fov()`: Returns the following:
+ * Server-sent FOV value. Returns 0 if an FOV override doesn't exist.
+ * Boolean indicating whether the FOV value is a multiplier.
+ * Time (in seconds) taken for the FOV transition. Set by `set_fov`.
* `set_attribute(attribute, value)`: DEPRECATED, use get_meta() instead
* Sets an extra attribute with value on player.
* `value` must be a string, or a number which will be converted to a
* `get_formspec_prepend(formspec)`: returns a formspec string.
* `get_player_control()`: returns table with player pressed keys
* The table consists of fields with boolean value representing the pressed
- keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up.
+ keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up, zoom.
* example: `{jump=false, right=true, left=false, LMB=false, RMB=false,
- sneak=true, aux1=false, down=false, up=false}`
+ sneak=true, aux1=false, down=false, up=false, zoom=false}`
+ * The `zoom` field is available since 5.3
* `get_player_control_bits()`: returns integer with bit packed player pressed
keys.
* bit nr/meaning: 0/up, 1/down, 2/left, 3/right, 4/jump, 5/aux1, 6/sneak,
- 7/LMB, 8/RMB
+ 7/LMB, 8/RMB, 9/zoom (zoom available since 5.3)
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
* `hud_set_hotbar_selected_image(texturename)`
* sets image for selected item of hotbar
* `hud_get_hotbar_selected_image`: returns texturename
-* `set_sky(bgcolor, type, {texture names}, clouds)`
- * `bgcolor`: ColorSpec, defaults to white
- * `type`: Available types:
- * `"regular"`: Uses 0 textures, `bgcolor` ignored
- * `"skybox"`: Uses 6 textures, `bgcolor` used
- * `"plain"`: Uses 0 textures, `bgcolor` used
- * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or
- `"plain"` custom skyboxes (default: `true`)
-* `get_sky()`: returns bgcolor, type, table of textures, clouds
+* `set_sky(parameters)`
+ * `parameters` is a table with the following optional fields:
+ * `base_color`: ColorSpec, changes fog in "skybox" and "plain".
+ * `type`: Available types:
+ * `"regular"`: Uses 0 textures, `base_color` ignored
+ * `"skybox"`: Uses 6 textures, `base_color` used as fog.
+ * `"plain"`: Uses 0 textures, `base_color` used as both fog and sky.
+ * `textures`: A table containing up to six textures in the following
+ order: Y+ (top), Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south).
+ * `clouds`: Boolean for whether clouds appear. (default: `true`)
+ * `sky_color`: A table containing the following values, alpha is ignored:
+ * `day_sky`: ColorSpec, for the top half of the `"regular"`
+ sky during the day. (default: `#8cbafa`)
+ * `day_horizon`: ColorSpec, for the bottom half of the
+ `"regular"` sky during the day. (default: `#9bc1f0`)
+ * `dawn_sky`: ColorSpec, for the top half of the `"regular"`
+ sky during dawn/sunset. (default: `#b4bafa`)
+ The resulting sky color will be a darkened version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `dawn_horizon`: ColorSpec, for the bottom half of the `"regular"`
+ sky during dawn/sunset. (default: `#bac1f0`)
+ The resulting sky color will be a darkened version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `night_sky`: ColorSpec, for the top half of the `"regular"`
+ sky during the night. (default: `#006aff`)
+ The resulting sky color will be a dark version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `night_horizon`: ColorSpec, for the bottom half of the `"regular"`
+ sky during the night. (default: `#4090ff`)
+ The resulting sky color will be a dark version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `indoors`: ColorSpec, for when you're either indoors or
+ underground. Only applies to the `"regular"` sky.
+ (default: `#646464`)
+ * `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun
+ at sunrise and sunset.
+ * `fog_moon_tint`: ColorSpec, changes the fog tinting for the moon
+ at sunrise and sunset.
+ * `fog_tint_type`: string, changes which mode the directional fog
+ abides by, `"custom"` uses `sun_tint` and `moon_tint`, while
+ `"default"` uses the classic Minetest sun and moon tinting.
+ Will use tonemaps, if set to `"default"`. (default: `"default"`)
+* `get_sky()`: returns base_color, type, table of textures, clouds.
+* `get_sky_color()`: returns a table with the `sky_color` parameters as in
+ `set_sky`.
+* `set_sun(parameters)`:
+ * `parameters` is a table with the following optional fields:
+ * `visible`: Boolean for whether the sun is visible.
+ (default: `true`)
+ * `texture`: A regular texture for the sun. Setting to `""`
+ will re-enable the mesh sun. (default: `"sun.png"`)
+ * `tonemap`: A 512x1 texture containing the tonemap for the sun
+ (default: `"sun_tonemap.png"`)
+ * `sunrise`: A regular texture for the sunrise texture.
+ (default: `"sunrisebg.png"`)
+ * `sunrise_visible`: Boolean for whether the sunrise texture is visible.
+ (default: `true`)
+ * `scale`: Float controlling the overall size of the sun. (default: `1`)
+* `get_sun()`: returns a table with the current sun parameters as in
+ `set_sun`.
+* `set_moon(parameters)`:
+ * `parameters` is a table with the following optional fields:
+ * `visible`: Boolean for whether the moon is visible.
+ (default: `true`)
+ * `texture`: A regular texture for the moon. Setting to `""`
+ will re-enable the mesh moon. (default: `"moon.png"`)
+ * `tonemap`: A 512x1 texture containing the tonemap for the moon
+ (default: `"moon_tonemap.png"`)
+ * `scale`: Float controlling the overall size of the moon (default: `1`)
+* `get_moon()`: returns a table with the current moon parameters as in
+ `set_moon`.
+* `set_stars(parameters)`:
+ * `parameters` is a table with the following optional fields:
+ * `visible`: Boolean for whether the stars are visible.
+ (default: `true`)
+ * `count`: Integer number to set the number of stars in
+ the skybox. Only applies to `"skybox"` and `"regular"` sky types.
+ (default: `1000`)
+ * `star_color`: ColorSpec, sets the colors of the stars,
+ alpha channel is used to set overall star brightness.
+ (default: `#ebebff69`)
+ * `scale`: Float controlling the overall size of the stars (default: `1`)
+* `get_stars()`: returns a table with the current stars parameters as in
+ `set_stars`.
* `set_clouds(parameters)`: set cloud parameters
* `parameters` is a table with the following optional fields:
* `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
-------------
A perlin noise generator.
-It can be created via `PerlinNoise(seed, octaves, persistence, spread)`
-or `PerlinNoise(noiseparams)`.
-Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, spread)`
-or `minetest.get_perlin(noiseparams)`.
+It can be created via `PerlinNoise()` or `minetest.get_perlin()`.
+For `minetest.get_perlin()`, the actual seed used is the noiseparams seed
+plus the world seed, to create world-specific noise.
+
+`PerlinNoise(noiseparams)`
+`PerlinNoise(seed, octaves, persistence, spread)` (Deprecated).
+
+`minetest.get_perlin(noiseparams)`
+`minetest.get_perlin(seeddiff, octaves, persistence, spread)` (Deprecated).
### Methods
It can be created via `PerlinNoiseMap(noiseparams, size)` or
`minetest.get_perlin_map(noiseparams, size)`.
+For `minetest.get_perlin_map()`, the actual seed used is the noiseparams seed
+plus the world seed, to create world-specific noise.
Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
automatic_rotate = 0,
-- Set constant rotation in radians per second, positive or negative.
+ -- Object rotates along the local Y-axis, and works with set_rotation.
-- Set to 0 to disable constant rotation.
stepheight = 0,
-- deleted when the block gets unloaded.
-- The get_staticdata() callback is never called then.
-- Defaults to 'true'.
+
+ damage_texture_modifier = "^[brighten",
+ -- Texture modifier to be applied for a short duration when object is hit
+
+ shaded = true,
+ -- Setting this to 'false' disables diffuse lighting of entity
}
Entity definition
on_activate = function(self, staticdata, dtime_s),
- on_step = function(self, dtime),
+ on_step = function(self, dtime, moveresult),
+ -- Called every server step
+ -- dtime: Elapsed time
+ -- moveresult: Table with collision info (only available if physical=true)
on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
-- for more info) by using a '_' prefix
}
+Collision info passed to `on_step`:
+
+ {
+ touching_ground = boolean,
+ collides = boolean,
+ standing_on_object = boolean,
+ collisions = {
+ {
+ type = string, -- "node" or "object",
+ axis = string, -- "x", "y" or "z"
+ node_pos = vector, -- if type is "node"
+ object = ObjectRef, -- if type is "object"
+ old_velocity = vector,
+ new_velocity = vector,
+ },
+ ...
+ }
+ }
+
ABM (ActiveBlockModifier) definition
------------------------------------
wield_scale = {x = 1, y = 1, z = 1},
+ -- The default value of 99 may be configured by
+ -- users using the setting "default_stack_max"
stack_max = 99,
range = 4.0,
visual_scale = 1.0,
-- Supported for drawtypes "plantlike", "signlike", "torchlike",
- -- "firelike", "mesh".
+ -- "firelike", "mesh", "nodebox", "allfaces".
-- For plantlike and firelike, the image will start at the bottom of the
-- node. For torchlike, the image will start at the surface to which the
-- node "attaches". For the other drawtypes the image will be centered
-- If true, a new liquid source can be created by placing two or more
-- sources nearby
- leveled = 16,
+ leveled = 0,
-- Only valid for "nodebox" drawtype with 'type = "leveled"'.
-- Allows defining the nodebox height without using param2.
-- The nodebox height is 'leveled' / 64 nodes.
- -- The maximum value of 'leveled' is 127.
+ -- The maximum value of 'leveled' is `leveled_max`.
+
+ leveled_max = 127,
+ -- Maximum value for `leveled` (0-127), enforced in
+ -- `minetest.set_node_level` and `minetest.add_node_level`.
liquid_range = 8, -- Number of flowing nodes around source (max. 8)
-- node is deleted from the world or the drops are added. This is
-- generally the result of either the node being dug or an attached node
-- becoming detached.
+ -- oldmeta is the NodeMetaRef of the oldnode before deletion.
-- drops is a table of ItemStacks, so any metadata to be preserved can
-- be added directly to one or more of the dropped items. See
-- "ItemStackMetaRef".
on_punch = function(pos, node, puncher, pointed_thing),
-- default: minetest.node_punch
+ -- Called when puncher (an ObjectRef) punches the node at pos.
-- By default calls minetest.register_on_punchnode callbacks.
on_rightclick = function(pos, node, clicker, itemstack, pointed_thing),
-- default: nil
+ -- Called when clicker (an ObjectRef) "rightclicks"
+ -- ("rightclick" here stands for the placement key) while pointing at
+ -- the node at pos with 'node' being the node table.
-- itemstack will hold clicker's wielded item.
-- Shall return the leftover itemstack.
-- Note: pointed_thing can be nil, if a mod calls this function.
Used by `minetest.register_biome`.
+The maximum number of biomes that can be used is 65535. However, using an
+excessive number of biomes will slow down map generation. Depending on desired
+performance and computing power the practical limit is much lower.
+
{
name = "tundra",
text = "<text>",
+ text2 = "<text>",
+
number = 2,
item = 3,
size = 1,
-- Scales the visual size of the particle texture.
+ -- If `node` is set, size can be set to 0 to spawn a randomly-sized
+ -- particle (just like actual node dig particles).
collisiondetection = false,
-- If true collides with `walkable` nodes and, depending on the
-- If true faces player using y axis only
texture = "image.png",
+ -- The texture of the particle
playername = "singleplayer",
-- Optional, if specified spawns particle only on the player's client
glow = 0
-- Optional, specify particle self-luminescence in darkness.
-- Values 0-14.
+
+ node = {name = "ignore", param2 = 0},
+ -- Optional, if specified the particle will have the same appearance as
+ -- node dig particles for the given node.
+ -- `texture` and `animation` will be ignored if this is set.
+
+ node_tile = 0,
+ -- Optional, only valid in combination with `node`
+ -- If set to a valid number 1-6, specifies the tile from which the
+ -- particle texture is picked.
+ -- Otherwise, the default behavior is used. (currently: any random tile)
}
maxsize = 1,
-- The particles' properties are random values between the min and max
-- values.
- -- pos, velocity, acceleration, expirationtime, size
+ -- applies to: pos, velocity, acceleration, expirationtime, size
+ -- If `node` is set, min and maxsize can be set to 0 to spawn
+ -- randomly-sized particles (just like actual node dig particles).
collisiondetection = false,
-- If true collide with `walkable` nodes and, depending on the
-- If true face player using y axis only
texture = "image.png",
+ -- The texture of the particle
playername = "singleplayer",
-- Optional, if specified spawns particles only on the player's client
glow = 0
-- Optional, specify particle self-luminescence in darkness.
-- Values 0-14.
+
+ node = {name = "ignore", param2 = 0},
+ -- Optional, if specified the particles will have the same appearance as
+ -- node dig particles for the given node.
+ -- `texture` and `animation` will be ignored if this is set.
+
+ node_tile = 0,
+ -- Optional, only valid in combination with `node`
+ -- If set to a valid number 1-6, specifies the tile from which the
+ -- particle texture is picked.
+ -- Otherwise, the default behavior is used. (currently: any random tile)
}
`HTTPRequest` definition