* `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
+ * `default_dig_<groupname>`: Default node digging sound (gain = 0.5)
(see node sound definition for details)
Registered definitions
### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
* `item name` is the registered name of an item/node
+* `name` is non-optional and must be unique, or else tooltips are broken.
* The item description will be used as the tooltip. This can be overridden with
a tooltip element.
* `hand`: list containing an override for the empty hand
* Is not created automatically, use `InvRef:set_size`
* Is only used to enhance the empty hand's tool capabilities
+* `offhand`: list containing the offhand wielded item.
+ * Is not created automatically, use `InvRef:set_size`
+ * Will be used for placements and secondary uses if the
+ main hand does not have any node_place_prediction, on_place
+ or on_secondary_use callbacks.
+ * Is passed to on_place and on_secondary_use callbacks; make sure
+ mods are aware of the itemstack not neccessarily being
+ located in the main hand.
+ * The offhand item cannot have its own range or liquids_pointable and
+ will always reuse the characteristics from the hand item.
Colors
======
* Returns a vector where the function `func` has been applied to each
component.
* `vector.combine(v, w, func)`:
- * Returns a vector where the function `func` has combined both components of `v` and `w`
- for each component
+ * Returns a vector where the function `func` has combined both components of `v` and `w`
+ for each component
* `vector.equals(v1, v2)`:
* Returns a boolean, `true` if the vectors are identical.
* `vector.sort(v1, v2)`:
* `math.round(x)`: Returns `x` rounded to the nearest integer.
* At a multiple of 0.5, rounds away from zero.
* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)`
- * `separator`: string, default: `","`
+ * `separator`: string, cannot be empty, default: `","`
* `include_empty`: boolean, default: `false`
* `max_splits`: number, if it's negative, splits aren't limited,
default: `-1`
used for updating the entity state.
* `on_deactivate(self, removal)`
* Called when the object is about to get removed or unloaded.
- * `removal`: boolean indicating whether the object is about to get removed.
- Calling `object:remove()` on an active object will call this with `removal=true`.
- The mapblock the entity resides in being unloaded will call this with `removal=false`.
- * Note that this won't be called if the object hasn't been activated in the first place.
- In particular, `minetest.clear_objects({mode = "full"})` won't call this,
- whereas `minetest.clear_objects({mode = "quick"})` might call this.
+ * `removal`: boolean indicating whether the object is about to get removed.
+ Calling `object:remove()` on an active object will call this with `removal=true`.
+ The mapblock the entity resides in being unloaded will call this with `removal=false`.
+ * Note that this won't be called if the object hasn't been activated in the first place.
+ In particular, `minetest.clear_objects({mode = "full"})` won't call this,
+ whereas `minetest.clear_objects({mode = "quick"})` might call this.
* `on_step(self, dtime, moveresult)`
* Called on every server tick, after movement and collision processing.
* `dtime`: elapsed time since last call
or checking if a mod is enabled.
* `minetest.get_modnames()`: returns a list of enabled mods, sorted alphabetically.
* Does not include disabled mods, even if they are installed.
+* `minetest.get_game_info()`: returns a table containing information about the
+ current game. Note that other meta information (e.g. version/release number)
+ can be manually read from `game.conf` in the game's root directory.
+
+ {
+ id = string,
+ title = string,
+ author = string,
+ -- The root directory of the game
+ path = string,
+ }
+
* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
* Useful for storing custom data
* `minetest.is_singleplayer()`
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
--vers_string = "0.4.9-git", -- full version string
--state = "Active" -- current client state
}
+* `minetest.get_player_window_information(player_name)`:
+
+ -- Will only be present if the client sent this information (requires v5.7+)
+ --
+ -- Note that none of these things are constant, they are likely to change during a client
+ -- connection as the player resizes the window and moves it between monitors
+ --
+ -- real_gui_scaling and real_hud_scaling can be used instead of DPI.
+ -- OSes don't necessarily give the physical DPI, as they may allow user configuration.
+ -- real_*_scaling is just OS DPI / 96 but with another level of user configuration.
+ {
+ -- Current size of the in-game render target (pixels).
+ --
+ -- This is usually the window size, but may be smaller in certain situations,
+ -- such as side-by-side mode.
+ size = {
+ x = 1308,
+ y = 577,
+ },
+
+ -- Estimated maximum formspec size before Minetest will start shrinking the
+ -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than
+ -- this and `padding[-0.01,-0.01]`.
+ max_formspec_size = {
+ x = 20,
+ y = 11.25
+ },
+
+ -- GUI Scaling multiplier
+ -- Equal to the setting `gui_scaling` multiplied by `dpi / 96`
+ real_gui_scaling = 1,
+
+ -- HUD Scaling multiplier
+ -- Equal to the setting `hud_scaling` multiplied by `dpi / 96`
+ real_hud_scaling = 1,
+ }
* `minetest.mkdir(path)`: returns success.
* Creates a directory specified by `path`, creating parent directories
* `pos_list` is an array of all modified positions.
* `node_list` is an array of the old node that was previously at the position
with the corresponding index in pos_list.
+* `minetest.register_on_mapblocks_changed(function(modified_blocks, modified_block_count))`
+ * Called soon after any nodes or node metadata have been modified. No
+ modifications will be missed, but there may be false positives.
+ * Will never be called more than once per server step.
+ * `modified_blocks` is the set of modified mapblock position hashes. These
+ are in the same format as those produced by `minetest.hash_node_position`,
+ and can be converted to positions with `minetest.get_position_from_hash`.
+ The set is a table where the keys are hashes and the values are `true`.
+ * `modified_block_count` is the number of entries in the set.
+ * Note: callbacks must be registered at mod load time.
Setting-related
---------------
prefix `"no"` is attached, clears instead.
* `flags` is in the same format and has the same options as `mg_flags` in
`minetest.conf`.
+* `minetest.get_mapgen_edges([mapgen_limit[, chunksize]])`
+ * Returns the minimum and maximum possible generated node positions
+ in that order.
+ * `mapgen_limit` is an optional number. If it is absent, its value is that
+ of the *active* mapgen setting `"mapgen_limit"`.
+ * `chunksize` is an optional number. If it is absent, its value is that
+ of the *active* mapgen setting `"chunksize"`.
* `minetest.get_mapgen_setting(name)`
* Gets the *active* mapgen setting (or nil if none exists) in string
format with the following order of precedence:
* You may want to cache and call the old function to allow multiple mods to
change knockback behavior.
-* `minetest.forceload_block(pos[, transient])`
+* `minetest.forceload_block(pos[, transient[, limit]])`
* forceloads the position `pos`.
* returns `true` if area could be forceloaded
* If `transient` is `false` or absent, the forceload will be persistent
(saved between server runs). If `true`, the forceload will be transient
(not saved between server runs).
+ * `limit` is an optional limit on the number of blocks that can be
+ forceloaded at once. If `limit` is negative, there is no limit. If it is
+ absent, the limit is the value of the setting `"max_forceloaded_blocks"`.
+ If the call would put the number of blocks over the limit, the call fails.
* `minetest.forceload_free_block(pos[, transient])`
* stops forceloading the position `pos`
Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`],
and [`PlayerMetaRef`].
+Note: If a metadata value is in the format `${k}`, an attempt to get the value
+will return the value associated with key `k`. There is a low recursion limit.
+This behavior is **deprecated** and will be removed in a future version. Usage
+of the `${k}` syntax in formspecs is not deprecated.
+
### Methods
* `contains(key)`: Returns true if key present, otherwise false.
* `basic_debug`: Allow showing basic debug info that might give a gameplay advantage.
This includes map seed, player position, look direction, the pointed node and block bounds.
Does not affect players with the `debug` privilege.
+ * `chat`: Modifies the client's permission to view chat on the HUD.
+ The client may locally elect to not view chat. Does not affect the console.
* If a flag equals `nil`, the flag is not modified
* `hud_get_flags()`: returns a table of player HUD flags with boolean values.
* See `hud_set_flags` for a list of flags that can be toggled.
* `sky_parameters` is a table with the following optional fields:
* `base_color`: ColorSpec, changes fog in "skybox" and "plain".
(default: `#ffffff`)
+ * `body_orbit_tilt`: Float, angle of sun/moon orbit in degrees, relative to Y axis.
+ Valid range [-60.0,60.0] (default: 0.0)
* `type`: Available types:
* `"regular"`: Uses 0 textures, `base_color` ignored
* `"skybox"`: Uses 6 textures, `base_color` used as fog.
* Resource intensive - use sparsely
* `set_lighting(light_definition)`: sets lighting for the player
* `light_definition` is a table with the following optional fields:
+ * `saturation` sets the saturation (vividness).
+ values > 1 increase the saturation
+ values in [0,1) decrease the saturation
+ * This value has no effect on clients who have the "Tone Mapping" shader disabled.
* `shadows` is a table that controls ambient shadows
* `intensity` sets the intensity of the shadows from 0 (no shadows, default) to 1 (blackness)
+ * This value has no effect on clients who have the "Dynamic Shadows" shader disabled.
+ * `exposure` is a table that controls automatic exposure.
+ The basic exposure factor equation is `e = 2^exposure_correction / clamp(luminance, 2^luminance_min, 2^luminance_max)`
+ * `luminance_min` set the lower luminance boundary to use in the calculation
+ * `luminance_max` set the upper luminance boundary to use in the calculation
+ * `exposure_correction` correct observed exposure by the given EV value
+ * `speed_dark_bright` set the speed of adapting to bright light
+ * `speed_bright_dark` set the speed of adapting to dark scene
+ * `center_weight_power` set the power factor for center-weighted luminance measurement
+
* `get_lighting()`: returns the current state of lighting for the player.
* Result is a table with the same fields as `light_definition` in `set_lighting`.
* `respawn()`: Respawns the player using the same mechanism as the death screen,
collisionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 }, -- default
selectionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5, rotate = false },
- -- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position.
+ -- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position.
-- Collision boxes cannot rotate, setting `rotate = true` on it has no effect.
-- If not set, the selection box copies the collision box, and will also not rotate.
-- If `rotate = false`, the selection box will not rotate with the object itself, remaining fixed to the axes.
-- If `rotate = true`, it will match the object's rotation and any attachment rotations.
-- Raycasts use the selection box and object's rotation, but do *not* obey attachment rotations.
-
+
pointable = true,
-- Whether the object can be pointed at
-- If left out or empty, any neighbor will do.
-- `group:groupname` can also be used here.
- interval = 1.0,
+ interval = 10.0,
-- Operation interval in seconds
- chance = 1,
- -- Chance of triggering `action` per-node per-interval is 1.0 / this
- -- value
+ chance = 50,
+ -- Chance of triggering `action` per-node per-interval is 1.0 / chance
min_y = -32768,
max_y = 32767,
-- and not only the first time the block gets activated after the LBM
-- was introduced.
- action = function(pos, node),
+ action = function(pos, node, dtime_s),
-- Function triggered for each qualifying node.
+ -- `dtime_s` is the in-game time (in seconds) elapsed since the block
+ -- was last active
}
Tile definition
},
on_place = function(itemstack, placer, pointed_thing),
- -- When the 'place' key was pressed with the item in hand
+ -- When the 'place' key was pressed with the item one of the hands
-- and a node was pointed at.
+ -- 'itemstack' may be the offhand item in cases where the main hand has
+ -- no on_place handler and no node_placement_prediction.
-- 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.
+ -- Same as on_place but called when not pointing at a node,
+ -- whereas `user` is the same as `placer` above.
-- default: nil
on_drop = function(itemstack, dropper, pos),
dig = <SimpleSoundSpec> or "__group",
-- While digging node.
-- If `"__group"`, then the sound will be
- -- `default_dig_<groupname>`, where `<groupname>` is the
+ -- `{name = "default_dig_<groupname>", gain = 0.5}` , where `<groupname>` is the
-- name of the item's digging group with the fastest digging time.
-- In case of a tie, one of the sounds will be played (but we
-- cannot predict which one)
Used by `minetest.register_chatcommand`.
+Specifies the function to be called and the privileges required when a player
+issues the command. A help message that is the concatenation of the params and
+description fields is shown when the "/help" chatcommand is issued.
+
{
- params = "<name> <privilege>", -- Short parameter description
+ params = "",
+ -- Short parameter description. See the below note.
- description = "Remove privilege from player", -- Full description
+ description = "",
+ -- General description of the command's purpose.
- privs = {privs=true}, -- Require the "privs" privilege to run
+ privs = {},
+ -- Required privileges to run. See `minetest.check_player_privs()` for
+ -- the format and see [Privileges] for an overview of privileges.
func = function(name, param),
- -- Called when command is run. Returns boolean success and text output.
- -- Special case: The help message is shown to the player if `func`
- -- returns false without a text output.
+ -- Called when command is run.
+ -- * `name` is the name of the player who issued the command.
+ -- * `param` is a string with the full arguments to the command.
+ -- Returns a boolean for success and a string value.
+ -- The string is shown to the issuing player upon exit of `func` or,
+ -- if `func` returns `false` and no string, the help message is shown.
}
-Note that in params, use of symbols is as follows:
+Note that in params, the conventional use of symbols is as follows:
* `<>` signifies a placeholder to be replaced when the command is used. For
example, when a player name is needed: `<name>`
* `()` signifies grouping. For example, when param1 and param2 are both
required, or only param3 is required: `(<param1> <param2>) | <param3>`
+Example:
+
+ {
+ params = "<name> <privilege>",
+
+ description = "Remove privilege from player",
+
+ privs = {privs=true}, -- Require the "privs" privilege to run
+
+ func = function(name, param),
+ }
+
Privilege definition
--------------------
All of the properties in this list can be animated with `*_tween` tables
unless otherwise specified. For example, `jitter` can be tweened by setting
a `jitter_tween` table instead of (or in addition to) a `jitter` table/value.
+In this section, a float range is a table defined as so: { min = A, max = B }
+A and B are your supplemented values. For a vec3 range this means they are vectors.
Types used are defined in the previous section.
* vec3 range `pos`: the position at which particles can appear
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.
+
+Error Handling
+--------------
+
+When an error occurs that is not caught, Minetest calls the function
+`minetest.error_handler` with the error object as its first argument. The second
+argument is the stack level where the error occurred. The return value is the
+error string that should be shown. By default this is a backtrace from
+`debug.traceback`. If the error object is not a string, it is first converted
+with `tostring` before being displayed. This means that you can use tables as
+error objects so long as you give them `__tostring` metamethods.
+
+You can override `minetest.error_handler`. You should call the previous handler
+with the correct stack level in your implementation.
projects / minetest.git / blobdiff