-Minetest Lua Modding API Reference 0.4.12
+Minetest Lua Modding API Reference 0.4.13
=========================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
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:
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
* `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
* Returns `{name="ignore", ...}` for unloaded area
* `minetest.get_node_or_nil(pos)`
* Returns `nil` for unloaded area
-* `minetest.get_node_light(pos, timeofday)` returns a number between `0` and `15` or `nil`
+* `minetest.get_node_light(pos, timeofday)`
+ * Gets the light value at the given position. Note that the light value
+ "inside" the node at the given position is returned, so you usually want
+ to get the light value of a neighbor.
+ * `pos`: The position where to measure the light.
* `timeofday`: `nil` for current time, `0` for night, `0.5` for day
-
+ * Returns a number between `0` and `15` or `nil`
* `minetest.place_node(pos, node)`
* Place node with the same effects that a player would cause
* `minetest.dig_node(pos)`
`{ 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)
* Optional: Variable number of arguments that are passed to `func`
### Server
-* `minetest.request_shutdown()`: request for server shutdown
+* `minetest.request_shutdown([message],[reconnect])`: request for server shutdown. Will display `message` to clients,
+ and `reconnect` == true displays a reconnect button.
* `minetest.get_server_status()`: returns server status string
### Bans
* `minetest.add_particlespawner(particlespawner definition)`
* Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
- * Returns an `id`
+ * Returns an `id`, and -1 if adding didn't succeed
* `Deprecated: minetest.add_particlespawner(amount, time,
minpos, maxpos,
minvel, maxvel,
* currently supported.
* `...` indicates method-specific arguments. Currently, no methods use this.
* `minetest.is_protected(pos, name)`: returns boolean
+ * Returns true, if player `name` shouldn't be abled to dig at `pos` or do other
+ actions, defineable by mods, due to some mod-defined ownership-like concept.
+ Returns false or nil, if the player is allowed to do such actions.
* This function should be overridden by protection mods and should be used to
check if a player can interact at a position.
* This function should call the old version of itself if the position is not
* `set_wielded_item(item)`: replaces the wielded item, returns `true` if successful
* `set_armor_groups({group1=rating, group2=rating, ...})`
* `get_armor_groups()`: returns a table with the armor group ratings
-* `set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)`
-* `get_animation()`: returns range, frame_speed and frame_blend
+* `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)
##### Player-only (no-op for other objects)
* `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)
* element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
* `hud_get(id)`: gets the HUD element definition structure of the specified ID
* `hud_set_flags(flags)`: sets specified HUD flags to `true`/`false`
- * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`
+ * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`, `minimap`
* pass a table containing a `true`/`false` value of each flag to be set or unset
* if a flag equals `nil`, the flag is not modified
+ * note that setting `minimap` modifies the client's permission to view the minimap -
+ * the client may locally elect to not view the minimap
* `hud_get_flags()`: returns a table containing status of hud flags
- * returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true }`
+ * returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true, minimap=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
* `get_location()`: returns a location compatible to `minetest.get_inventory(location)`
* returns `{type="undefined"}` in case location is not known
+### `AreaStore`
+A fast access data structure to store areas, and find areas near a given position or area.
+Every area has a `data` string attribute to store additional information.
+You can create an empty `AreaStore` by calling `AreaStore()`, or `AreaStore(type_name)`.
+If you chose the parameter-less constructor, a fast implementation will be automatically chosen for you.
+
+#### Methods
+* `get_area(id, include_borders, include_data)`: returns the area with the id `id`. (optional) Boolean values `include_borders` and `include_data` control what's copied.
+* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain the position `pos`. (optional) Boolean values `include_borders` and `include_data` control what's copied.
+* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`: returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive). If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area. (optional) Boolean values `include_borders` and `include_data` control what's copied.
+* `insert_area(edge1, edge2, data)`: inserts an area into the store. Returns the id if successful, nil otherwise. The (inclusive) positions `edge1` and `edge2` describe the area, `data`
+is a string stored with the area.
+* `reserve(count)`: reserves resources for at most `count` many contained areas. Only needed for efficiency, and only some implementations profit.
+* `remove_area(id)`: removes the area with the given id from the store, returns success.
+* `set_cache_params(params)`: sets params for the included prefiltering cache. Calling invalidates the cache, so that its elements have to be newly generated.
+ * `params`:
+ {
+ enabled = boolean, -- whether to enable, default true
+ block_radius = number, -- the radius (in nodes) of the areas the cache generates prefiltered lists for, minimum 16, default 64
+ limit = number, -- the cache's size, minimum 20, default 1000
+ }
+
### `ItemStack`
An `ItemStack` is a stack of items.
### 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)
-- ^ 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 / oweals / minetest.git / blobdiff