The game directory can contain the file minetest.conf, which will be used
to set default settings when running the particular game.
+### Menu images
+
+Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory.
+
+The images are named `$identifier.png`, where `$identifier` is one of `overlay,background,footer,header`.
+If you want to specify multiple images for one identifier, add additional 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.
+
+
Mod load path
-------------
Generic:
#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
* Show an inventory list
+#### `listring[<inventory location>;<list name>]`
+* Allows to create a ring of inventory lists
+* Shift-clicking on items in one element of the ring
+* will send them to the next inventory list inside the ring
+* The first occurrence of an element inside the ring will
+* determine the inventory where items will be sent to
+
+#### `listring[]`
+* Shorthand for doing `listring[<inventory location>;<list name>]`
+* for the last two inventory lists added by list[...]
+
#### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering
(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
value must (always) be two hexadecimal digits.
+`ColorSpec`
+-----------
+A ColorSpec specifies a 32-bit color. It can be written in either:
+table form, each element ranging from 0..255 (a, if absent, defaults to 255):
+ `colorspec = {a=255, r=0, g=255, b=0}`
+numerical form, the raw integer value of an ARGB8 quad:
+ `colorspec = 0xFF00FF00`
+or string form, a ColorString (defined above):
+ `colorspec = "green"`
+
Vector helpers
--------------
* Useful for storing custom data
* `minetest.is_singleplayer()`
* `minetest.features`
- * table containing API feature flags: `{foo=true, bar=true}`
+ * Table containing API feature flags: `{foo=true, bar=true}`
* `minetest.has_feature(arg)`: returns `boolean, 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.
-
-Example of `minetest.get_player_information` return value:
-
- {
- 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
- }
+* `minetest.get_player_information(player_name)`: returns a table containing
+ information about player. Example return value:
+ {
+ 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
+ }
+* `minetest.mkdir(path)`: returns success.
+ * Creates a directory specified by `path`, creating parent directories
+ if they don't exist.
+* `minetest.get_dir_list(path, [is_dir])`: returns list of entry names
+ * is_dir is one of:
+ * nil: return all entries,
+ * true: return only subdirectory names, or
+ * false: return only file names.
### Logging
* `minetest.debug(line)`
* Called after a new player has been created
* `minetest.register_on_dieplayer(func(ObjectRef))`
* Called when a player dies
+* `minetest.register_on_punchplayer(func(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))`
+ * Called when a player is punched
+ * `player` - ObjectRef - Player that was punched
+ * `hitter` - ObjectRef - Player that hit
+ * `time_from_last_punch`: Meant for disallowing spamming of clicks (can be nil)
+ * `tool_capabilities`: capability table of used tool (can be nil)
+ * `dir`: unit vector of direction of punch. Always defined. Points from
+ the puncher to the punched.
+ * `damage` - number that represents the damage calculated by the engine
+ * should return `true` to prevent the default damage mechanism
+* `minetest.register_on_player_hpchange(func(player, hp_change), modifier)`
+ * Called when the player gets damaged or healed
+ * `player`: ObjectRef of the player
+ * `hp_change`: the amount of change. Negative when it is damage.
+ * `modifier`: when true, the function should return the actual hp_change.
+ Note: modifiers only get a temporary hp_change that can be modified by later modifiers.
+ modifiers can return true as a second argument to stop the execution of further functions.
* `minetest.register_on_respawnplayer(func(ObjectRef))`
* Called when player is to be respawned
* Called _before_ repositioning of player occurs
* `dug_too_fast`
* `minetest.register_on_chat_message(func(name, message))`
* Called always when a player says something
+ * Return `true` to mark the message as handled, which means that it will not be sent to other players
* `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
### Setting-related
* `minetest.setting_set(name, value)`
+ * Setting names can't contain whitespace or any of `="{}#`.
+ * Setting values can't contain the sequence `\n"""`.
+ * Setting names starting with "secure." can't be set.
* `minetest.setting_get(name)`: returns string or `nil`
* `minetest.setting_setbool(name, value)`
+ * See documentation on `setting_set` for restrictions.
* `minetest.setting_getbool(name)`: returns boolean or `nil`
* `minetest.setting_get_pos(name)`: returns position or nil
* `minetest.setting_save()`, returns `nil`, save all settings to config file
* `minetest.find_node_near(pos, radius, nodenames)`: returns pos or `nil`
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `minetest.find_nodes_in_area(minp, maxp, nodenames)`: returns a list of positions
+ * returns as second value a table with the count of the individual nodes found
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `minetest.find_nodes_in_area_under_air(minp, maxp, nodenames)`: returns a list of positions
* returned positions are nodes with a node air above
* `flags` is a flag field with the available flags: `dungeon`, `temple`, `cave_begin`,
`cave_end`, `large_cave_begin`, `large_cave_end`, `decoration`
* The second parameter is a list of IDS of decorations which notification is requested for
+* `get_gen_notify()`: returns a flagstring and a table with the deco_ids
* `minetest.get_mapgen_object(objectname)`
* Return requested mapgen object if available (see "Mapgen objects")
* `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing
* Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`.
* `set_default` is an optional boolean (default: `true`) that specifies whether the setting
should be applied to the default config or current active config
+* `minetest.get_noiseparams(name)`: returns a table of the noiseparams for name
* `minetest.generate_ores(vm, pos1, pos2)`
* Generate all registered ores within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
* `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
`{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
* `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack`
* `output.time` = a number, if unsuccessful: `0`
+ * `output.replacements` = list of `ItemStack`s that couldn't be placed in
+ `decremented_input.items`
* `decremented_input` = like `input`
* `minetest.get_craft_recipe(output)`: returns input
* returns last registered recipe for output item (node)
* Get rating of a group of an item. (`0` means: not in group)
* `minetest.get_node_group(name, group)`: returns a rating
* Deprecated: An alias for the former.
+* `minetest.raillike_group(name)`: returns a rating
+ * Returns rating of the connect_to_raillike group corresponding to name
+ * If name is not yet the name of a connect_to_raillike group, a new group id
+ * is created, with that name
* `minetest.get_content_id(name)`: returns an integer
* Gets the internal content ID of `name`
* `minetest.get_name_from_content_id(content_id)`: returns a string
the floor or ceiling
* The first four options are mutually-exclusive; the last in the list takes
precedence over the first.
-
-
-
* `minetest.rotate_node(itemstack, placer, pointed_thing)`
- * calls `rotate_and_place()` with infinitestacks set according to the state of
+ * calls `rotate_and_place()` with infinitestacks set according to the state of
the creative mode setting, and checks for "sneak" to set the `invert_wall`
parameter.
* `minetest.forceload_block(pos)`
* forceloads the position `pos`.
* returns `true` if area could be forceloaded
+ * Please note that forceloaded areas are saved when the server restarts.
* `minetest.forceload_free_block(pos)`
* stops forceloading the position `pos`
-Please note that forceloaded areas are saved when the server restarts.
+* `minetest.request_insecure_environment()`: returns an environment containing
+ 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.
+ * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN
+ A LOCAL VARIABLE!**
-minetest.global_exists(name)
-^ Checks if a global variable has been set, without triggering a warning.
+* `minetest.global_exists(name)`
+ * Checks if a global variable has been set, without triggering a warning.
### Global objects
* `minetest.env`: `EnvRef` of the server environment and world.
* Any function in the minetest namespace can be called using the syntax
`minetest.env:somefunction(somearguments)`
instead of `minetest.somefunction(somearguments)`
- * Deprecated, but support is not to be dropped soon
+ * Deprecated, but support is not to be dropped soon
### Global tables
* `minetest.registered_items`
* `get_wielded_item()`: returns an `ItemStack`
* `set_wielded_item(item)`: replaces the wielded item, returns `true` if successful
* `set_armor_groups({group1=rating, group2=rating, ...})`
-* `set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)`
+* `get_armor_groups()`: returns a table with the armor group ratings
+* `set_animation({x=1,y=1}, frame_speed=15, frame_blend=0, frame_loop=true)`
+* `get_animation()`: returns range, frame_speed, frame_blend and frame_loop
* `set_attach(parent, bone, position, rotation)`
* `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative)
* `rotation`: `{x=num, y=num, z=num}`
+* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't attached
* `set_detach()`
* `set_bone_position(bone, position, rotation)`
* `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative)
* `rotation`: `{x=num, y=num, z=num}`
+* `get_bone_position(bone)`: returns position and rotation of the bone
* `set_properties(object property table)`
+* `get_properties()`: returns object property table
+* `is_player()`: returns true for players, false otherwise
##### LuaEntitySAO-only (no-op for other objects)
* `setvelocity({x=num, y=num, z=num})`
* `get_luaentity()`
##### Player-only (no-op for other objects)
-* `is_player()`: true for players, false for others
* `get_player_name()`: returns `""` if is not a player
+* `get_player_velocity()`: returns `nil` if is not a player otherwise a table {x, y, z} representing the player's instantaneous velocity in nodes/s
* `get_look_dir()`: get camera direction as a unit vector
* `get_look_pitch()`: pitch in radians
* `get_look_yaw()`: yaw in radians (wraps around pretty randomly as of now)
* `gravity`: multiplier to default gravity value (default: `1`)
* `sneak`: whether player can sneak (default: `true`)
* `sneak_glitch`: whether player can use the sneak glitch (default: `true`)
+* `get_physics_override()`: returns the table given to set_physics_override
* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID
number on success
* `hud_remove(id)`: remove the HUD element of the specified id
* 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_get_hotbar_itemcount`: returns number of visible items
* `hud_set_hotbar_image(texturename)`
* sets background image for hotbar
+* `hud_get_hotbar_image`: returns texturename
* `hud_set_hotbar_selected_image(texturename)`
* sets image for selected item of hotbar
+* `hud_get_hotbar_selected_image`: returns texturename
* `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
+ * `bgcolor`: ColorSpec, 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.
+* `get_sky()`: returns bgcolor, type and a table with the textures
* `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(walk, dig, walk+dig, frame_speed=frame_speed)`
+* `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden
+* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`
set animation for player model in third person view
{x=189, y=198}, -- < dig animation key frames
{x=200, y=219}, -- < walk+dig animation key frames
frame_speed=30): -- < animation frame speed
-
+* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and 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}`)
+* `get_eye_offset()`: returns offset_first and offset_third
+* `get_nametag_attributes()`
+ * returns a table with the attributes of the nametag of the player
+ * {
+ color = {a=0..255, r=0..255, g=0..255, b=0..255},
+ }
+* `set_nametag_attributes(attributes)`
+ * sets the attributes of the nametag of the player
+ * `attributes`:
+ {
+ color = ColorSpec,
+ }
### `InvRef`
An `InvRef` is a reference to an inventory.
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
`nil` is returned).
+For each of the functions with an optional `buffer` parameter: If `buffer` is not
+nil, this table will be used to store the result instead of creating a new table.
+
+
#### Methods
* `get2dMap(pos)`: returns a `<size.x>` times `<size.y>` 2D array of 2D noise
with values starting at `pos={x=,y=}`
* `get3dMap(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>` 3D array
of 3D noise with values starting at `pos={x=,y=,z=}`
-* `get2dMap_flat(pos)`: returns a flat `<size.x * size.y>` element array of 2D noise
+* `get2dMap_flat(pos, buffer)`: returns a flat `<size.x * size.y>` element array of 2D noise
with values starting at `pos={x=,y=}`
-* `get3dMap_flat(pos)`: Same as `get2dMap_flat`, but 3D noise
+* `get3dMap_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise
+* `calc2dMap(pos)`: Calculates the 2d noise map starting at `pos`. The result is stored internally.
+* `calc3dMap(pos)`: Calculates the 3d noise map starting at `pos`. The result is stored internally.
+* `getMapSlice(slice_offset, slice_size, buffer)`: In the form of an array, returns a slice of the
+ most recently computed noise results. The result slice begins at coordinates `slice_offset` and
+ takes a chunk of `slice_size`.
+ E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20:
+ `noisevals = noise:getMapSlice({y=20}, {y=2})`
+ It is important to note that `slice_offset` offset coordinates begin at 1, and are relative to
+ the starting position of the most recently calculated noise.
+ To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000:
+ `noise:calc3dMap({x=1000, y=1000, z=1000})`
+ `noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})`
### `VoxelManip`
An interface to the `MapVoxelManipulator` for Lua.
the `VoxelManip` at that position
* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at
that position
-* `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
+* `get_data(buffer)`: Gets the data read into the `VoxelManip` object
+ * returns raw node data in the form of an array of node content IDs
+ * if the param `buffer` is present, this table will be used to store the result instead
* `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;
### Tile definition
* `"image.png"`
* `{name="image.png", animation={Tile Animation definition}}`
-* `{name="image.png", backface_culling=bool}`
- * backface culling only supported in special tiles
+* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
+ tileable_horizontal=bool}`
+ * backface culling only supported in special tiles.
+ * tileable flags are info for shaders, how they should treat texture
+ when displacement mapping is used
+ Directions are from the point of view of the tile texture,
+ not the node it's on
* deprecated, yet still supported field names:
* `image` (name)
^ List can be shortened to needed length ]]
alpha = 255,
use_texture_alpha = false, -- Use texture's alpha channel
- post_effect_color = {a=0, r=0, g=0, b=0}, -- If player is inside node
+ post_effect_color = "green#0F", -- If player is inside node, see "ColorSpec"
paramtype = "none", -- See "Nodes" --[[
^ paramtype = "light" allows light to propagate from or through the node with light value
^ falling by 1 per node. This line is essential for a light source node to spread its light. ]]
-- ^ Number of nodes the decoration can be at maximum.
-- ^ If absent, the parameter 'height' is used as a constant.
spawn_by = "default:water",
- -- ^ Node that the decoration only spawns next to, in a 1-node square radius.
+ -- ^ Node that the decoration only spawns next to.
+ -- ^ The neighbours checked are the 8 nodes horizontally surrounding the lowest node of the
+ -- ^ decoration, and the 8 nodes horizontally surrounding the ground node below the 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.
projects / dragonfireclient.git / blobdiff