* `disallowed_mapgen_settings= <comma-separated mapgen settings>`
e.g. `disallowed_mapgen_settings = mgv5_spflags`
These mapgen settings are hidden for this game in the world creation
- dialog and game start menu.
+ dialog and game start menu. Add `seed` to hide the seed input field.
* `disabled_settings = <comma-separated settings>`
e.g. `disabled_settings = enable_damage, creative_mode`
These settings are hidden for this game in the "Start game" tab
images named like `$identifier.$n.png`, with an ascending number $n starting
with 1, and a random image will be chosen from the provided ones.
+Menu music
+-----------
+Games can provide custom main menu music. They are put inside a `menu`
+directory inside the game directory.
+The music files are named `theme.ogg`.
+If you want to specify multiple music files for one game, add additional
+images named like `theme.$n.ogg`, with an ascending number $n starting
+with 1 (max 10), and a random music file will be chosen from the provided ones.
Mods
====
color, meaning white surfaces get a lot of your new color while black parts
don't change very much.
+#### `[png:<base64>`
+
+Embed a base64 encoded PNG image in the texture string.
+You can produce a valid string for this by calling
+`minetest.encode_base64(minetest.encode_png(tex))`,
+refer to the documentation of these functions for details.
+You can use this to send disposable images such as captchas
+to individual clients, or render things that would be too
+expensive to compose with `[combine:`.
+
+IMPORTANT: Avoid sending large images this way.
+This is not a replacement for asset files, do not use it to do anything
+that you could instead achieve by just using a file.
+In particular consider `minetest.dynamic_add_media` and test whether
+using other texture modifiers could result in a shorter string than
+embedding a whole image, this may vary by use case.
+
Hardware coloring
-----------------
`param1` is reserved for the engine when `paramtype != "none"`.
* `paramtype = "light"`
- * The value stores light with and without sun in its upper and lower 4 bits
+ * The value stores light with and without sun in its lower and upper 4 bits
respectively.
* Required by a light source node to enable spreading its light.
* Required by the following drawtypes as they determine their visual
### Uses (tools only)
Determines how many uses the tool has when it is used for digging a node,
-of this group, of the maximum level. For lower leveled nodes, the use count
-is multiplied by `3^leveldiff`.
+of this group, of the maximum level. The maximum supported number of
+uses is 65535. The special number 0 is used for infinite uses.
+For lower leveled nodes, the use count is multiplied by `3^leveldiff`.
`leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the
node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
* `color`: A `ColorString`, which sets the stack's color.
* `palette_index`: If the item has a palette, this is used to get the
current color from the palette.
+* `count_meta`: Replace the displayed count with any string.
+* `count_alignment`: Set the alignment of the displayed count value. This is an
+ int value. The lowest 2 bits specify the alignment in x-direction, the 3rd and
+ 4th bit specify the alignment in y-direction:
+ 0 = default, 1 = left / up, 2 = middle, 3 = right / down
+ The default currently is the same as right/down.
+ Example: 6 = 2 + 1*4 = middle,up
Example:
meta:set_string("key", "value")
print(dump(meta:to_table()))
+Example manipulations of "description" and expected output behaviors:
+
+ print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe
+ print(ItemStack("foobar"):get_description()) --> Unknown Item
+
+ local stack = ItemStack("default:stone")
+ stack:get_meta():set_string("description", "Custom description\nAnother line")
+ print(stack:get_description()) --> Custom description\nAnother line
+ print(stack:get_short_description()) --> Custom description
+
+ stack:get_meta():set_string("short_description", "Short")
+ print(stack:get_description()) --> Custom description\nAnother line
+ print(stack:get_short_description()) --> Short
+
+ print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc
Version History
---------------
-* FORMSPEC VERSION 1:
+* Formspec version 1 (pre-5.1.0):
* (too much)
-* FORMSPEC VERSION 2:
+* Formspec version 2 (5.1.0):
* Forced real coordinates
* background9[]: 9-slice scaling parameters
-* FORMSPEC VERSION 3:
+* Formspec version 3 (5.2.0):
* Formspec elements are drawn in the order of definition
* bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor)
* box[] and image[] elements enable clipping by default
* new element: scroll_container[]
-* FORMSPEC VERSION 4:
+* Formspec version 4 (5.4.0):
* Allow dropdown indexing events
+* Formspec version 5 (5.5.0):
+ * Added padding[] element
Elements
--------
* `position` and `anchor` elements need suitable values to avoid a formspec
extending off the game window due to particular game window sizes.
-### `no_prepend[]`
+### `padding[<X>,<Y>]`
* Must be used after the `size`, `position`, and `anchor` elements (if present).
+* Defines how much space is padded around the formspec if the formspec tries to
+ increase past the size of the screen and coordinates have to be shrunk.
+* For X and Y, 0.0 represents no padding (the formspec can touch the edge of the
+ screen), and 0.5 represents half the screen (which forces the coordinate size
+ to 0). If negative, the formspec can extend off the edge of the screen.
+* Defaults to [0.05, 0.05].
+
+### `no_prepend[]`
+
+* Must be used after the `size`, `position`, `anchor`, and `padding` elements
+ (if present).
* Disables player:set_formspec_prepend() from applying to this formspec.
### `real_coordinates[<bool>]`
* End of a scroll_container, following elements are no longer bound to this
container.
-### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
+### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
-* Show an inventory list if it has been sent to the client. Nothing will
- be shown if the inventory list is of size 0.
+* Show an inventory list if it has been sent to the client.
+* If the inventory list changes (eg. it didn't exist before, it's resized, or its items
+ are moved) while the formspec is open, the formspec element may (but is not guaranteed
+ to) adapt to the new inventory list.
+* Item slots are drawn in a grid from left to right, then up to down, ordered
+ according to the slot index.
+* `W` and `H` are in inventory slots, not in coordinates.
+* `starting item index` (Optional): The index of the first (upper-left) item to draw.
+ Indices start at `0`. Default is `0`.
+* The number of shown slots is the minimum of `W*H` and the inventory list's size minus
+ `starting item index`.
* **Note**: With the new coordinate system, the spacing between inventory
slots is one-fourth the size of an inventory slot by default. Also see
[Styling Formspecs] for changing the size of slots and spacing.
-### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
-
-* Show an inventory list if it has been sent to the client. Nothing will
- be shown if the inventory list is of size 0.
-* **Note**: With the new coordinate system, the spacing between inventory
- slots is one-fourth the size of an inventory slot.
-
### `listring[<inventory location>;<list name>]`
* Allows to create a ring of inventory lists
* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
position.
* returns the exact position on the surface of a pointed node
-* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates an item
- that digs a node.
+* `minetest.get_dig_params(groups, tool_capabilities [, wear])`:
+ Simulates an item that digs a node.
Returns a table with the following fields:
* `diggable`: `true` if node can be dug, `false` otherwise.
* `time`: Time it would take to dig the node.
Parameters:
* `groups`: Table of the node groups of the node that would be dug
* `tool_capabilities`: Tool capabilities table of the item
-* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch])`:
+ * `wear`: Amount of wear the tool starts with (default: 0)
+* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch [, wear]])`:
Simulates an item that punches an object.
Returns a table with the following fields:
- * `hp`: How much damage the punch would cause.
+ * `hp`: How much damage the punch would cause (between -65535 and 65535).
* `wear`: How much wear would be added to the tool (ignored for non-tools).
Parameters:
* `groups`: Damage groups of the object
* `tool_capabilities`: Tool capabilities table of the item
* `time_from_last_punch`: time in seconds since last punch action
+ * `wear`: Amount of wear the item starts with (default: 0)
* `minetest.mkdir(path)`: returns success.
* Creates a directory specified by `path`, creating parent directories
if they don't exist.
+* `minetest.rmdir(path, recursive)`: returns success.
+ * Removes a directory specified by `path`.
+ * If `recursive` is set to `true`, the directory is recursively removed.
+ Otherwise, the directory will only be removed if it is empty.
+ * Returns true on success, false on failure.
+* `minetest.cpdir(source, destination)`: returns success.
+ * Copies a directory specified by `path` to `destination`
+ * Any files in `destination` will be overwritten if they already exist.
+ * Returns true on success, false on failure.
+* `minetest.mvdir(source, destination)`: returns success.
+ * Moves a directory specified by `path` to `destination`.
+ * If the `destination` is a non-empty directory, then the move will fail.
+ * Returns true on success, false on failure.
* `minetest.get_dir_list(path, [is_dir])`: returns list of entry names
* is_dir is one of:
* nil: return all entries,
* `minetest.remove_detached_inventory(name)`
* Returns a `boolean` indicating whether the removal succeeded.
* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
- returns left over ItemStack.
+ returns leftover ItemStack or nil to indicate no inventory change
* See `minetest.item_eat` and `minetest.register_on_item_eat`
Formspec
a player joined.
* This function may be overwritten by mods to customize the status message.
* `minetest.get_server_uptime()`: returns the server uptime in seconds
+* `minetest.get_server_max_lag()`: returns the current maximum lag
+ of the server in seconds or nil if server is not fully loaded yet
* `minetest.remove_player(name)`: remove player from database (if they are not
connected).
* As auth data is not removed, minetest.player_exists will continue to
* `minetest.kick_player(name, [reason])`: disconnect a player with an optional
reason.
* Returns boolean indicating success (false if player nonexistant)
+* `minetest.disconnect_player(name, [reason])`: disconnect a player with an
+ optional reason, this will not prefix with 'Kicked: ' like kick_player.
+ If no reason is given, it will default to 'Disconnected.'
+ * Returns boolean indicating success (false if player nonexistant)
Particles
---------
* `set_inventory_formspec(formspec)`
* Redefine player's inventory form
* Should usually be called in `on_joinplayer`
+ * If `formspec` is `""`, the player's inventory is disabled.
* `get_inventory_formspec()`: returns a formspec string
* `set_formspec_prepend(formspec)`:
* the formspec string will be added to every formspec shown to the user,
`aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`.
* The fields `LMB` and `RMB` are equal to `dig` and `place` respectively,
and exist only to preserve backwards compatibility.
+ * Returns an empty table `{}` if the object is not a player.
* `get_player_control_bits()`: returns integer with bit packed player pressed
- keys. Bits:
- * 0 - up
- * 1 - down
- * 2 - left
- * 3 - right
- * 4 - jump
- * 5 - aux1
- * 6 - sneak
- * 7 - dig
- * 8 - place
- * 9 - zoom
+ keys.
+ * Bits:
+ * 0 - up
+ * 1 - down
+ * 2 - left
+ * 3 - right
+ * 4 - jump
+ * 5 - aux1
+ * 6 - sneak
+ * 7 - dig
+ * 8 - place
+ * 9 - zoom
+ * Returns `0` (no bits set) if the object is not a player.
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
* `set_sky(sky_parameters)`
* The presence of the function `set_sun`, `set_moon` or `set_stars` indicates
whether `set_sky` accepts this format. Check the legacy format otherwise.
+ * Passing no arguments resets the sky to its default values.
* `sky_parameters` is a table with the following optional fields:
* `base_color`: ColorSpec, changes fog in "skybox" and "plain".
+ (default: `#ffffff`)
* `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.
+ (default: `"regular"`)
* `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: `#61b5f5`)
- * `day_horizon`: ColorSpec, for the bottom half of the
- `"regular"` sky during the day. (default: `#90d3f6`)
- * `dawn_sky`: ColorSpec, for the top half of the `"regular"`
- sky during dawn/sunset. (default: `#b4bafa`)
+ * `sky_color`: A table used in `"regular"` type only, containing the
+ following values (alpha is ignored):
+ * `day_sky`: ColorSpec, for the top half of the sky during the day.
+ (default: `#61b5f5`)
+ * `day_horizon`: ColorSpec, for the bottom half of the sky during the day.
+ (default: `#90d3f6`)
+ * `dawn_sky`: ColorSpec, for the top half of the 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`)
+ * `dawn_horizon`: ColorSpec, for the bottom half of the 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: `#006bff`)
+ * `night_sky`: ColorSpec, for the top half of the sky during the night.
+ (default: `#006bff`)
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`)
+ * `night_horizon`: ColorSpec, for the bottom half of the 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.
+ * `indoors`: ColorSpec, for when you're either indoors or underground.
(default: `#646464`)
* `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun
- at sunrise and sunset.
+ at sunrise and sunset. (default: `#f47d1d`)
* `fog_moon_tint`: ColorSpec, changes the fog tinting for the moon
- at sunrise and sunset.
+ at sunrise and sunset. (default: `#7f99cc`)
* `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.
* `get_sky_color()`: returns a table with the `sky_color` parameters as in
`set_sky`.
* `set_sun(sun_parameters)`:
+ * Passing no arguments resets the sun to its default values.
* `sun_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"`)
+ will re-enable the mesh sun. (default: "sun.png", if it exists)
* `tonemap`: A 512x1 texture containing the tonemap for the sun
(default: `"sun_tonemap.png"`)
* `sunrise`: A regular texture for the sunrise texture.
* `get_sun()`: returns a table with the current sun parameters as in
`set_sun`.
* `set_moon(moon_parameters)`:
+ * Passing no arguments resets the moon to its default values.
* `moon_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"`)
+ will re-enable the mesh moon. (default: `"moon.png"`, if it exists)
+ Note: Relative to the sun, the moon texture is rotated by 180°.
+ You can use the `^[transformR180` texture modifier to achieve the same orientation.
* `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(star_parameters)`:
+ * Passing no arguments resets stars to their default values.
* `star_parameters` is a table with the following optional fields:
* `visible`: Boolean for whether the stars are visible.
(default: `true`)
* `get_stars()`: returns a table with the current stars parameters as in
`set_stars`.
* `set_clouds(cloud_parameters)`: set cloud parameters
+ * Passing no arguments resets clouds to their default values.
* `cloud_parameters` is a table with the following optional fields:
* `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
* `color`: basic cloud color with alpha channel, ColorSpec
-- "sprite" uses 1 texture.
-- "upright_sprite" uses 2 textures: {front, back}.
-- "wielditem" expects 'textures = {itemname}' (see 'visual' above).
+ -- "mesh" requires one texture for each mesh buffer/material (in order)
colors = {},
-- Number of required colors depends on visual
on_place = function(itemstack, placer, pointed_thing),
-- When the 'place' key was pressed with the item in hand
-- and a node was pointed at.
- -- Shall place item and return the leftover itemstack.
+ -- Shall place item and return the leftover itemstack
+ -- or nil to not modify the inventory.
-- The placer may be any ObjectRef or nil.
-- default: minetest.item_place
on_secondary_use = function(itemstack, user, pointed_thing),
-- Same as on_place but called when not pointing at a node.
+ -- Function must return either nil if inventory shall not be modified,
+ -- or an itemstack to replace the original itemstack.
-- The user may be any ObjectRef or nil.
-- default: nil
on_use = function(itemstack, user, pointed_thing),
-- default: nil
-- When user pressed the 'punch/mine' key with the item in hand.
- -- Function must return either nil if no item shall be removed from
- -- inventory, or an itemstack to replace the original itemstack.
+ -- Function must return either nil if inventory shall not be modified,
+ -- or an itemstack to replace the original itemstack.
-- e.g. itemstack:take_item(); return itemstack
-- Otherwise, the function is free to do what it wants.
-- The user may be any ObjectRef or nil.
items = {"default:sand", "default:desert_sand"},
},
{
- -- Only drop if using an item in the "magicwand" group, or
+ -- Only drop if using an item in the "magicwand" group, or
-- an item that is in both the "pickaxe" and the "lucky"
-- groups.
tool_groups = {
-- Returns an iterator (use with `for` loops) for all player names
-- currently in the auth database
}
+
+Bit Library
+-----------
+
+Functions: bit.tobit, bit.tohex, bit.bnot, bit.band, bit.bor, bit.bxor, bit.lshift, bit.rshift, bit.arshift, bit.rol, bit.ror, bit.bswap
+
+See http://bitop.luajit.org/ for advanced information.