default_cobble.png^[crack:10:1
-#### `[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>`
+#### `[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>:...`
* `<w>` = width
* `<h>` = height
-* `<x1>`/`<x2>` = x positions
-* `<y1>`/`<y1>` = y positions
-* `<file1>`/`<file2>` = textures to combine
+* `<x>` = x position
+* `<y>` = y position
+* `<file>` = texture to combine
-Create a texture of size `<w>` times `<h>` and blit `<file1>` to (`<x1>`,`<y1>`)
-and blit `<file2>` to (`<x2>`,`<y2>`).
+Creates a texture of size `<w>` times `<h>` and blits the listed files to their
+specified coordinates.
Example:
wall_bottom = box,
wall_side = box
}
+ {
+ -- A node that has optional boxes depending on neighbouring nodes'
+ -- presence and type. See also `connects_to`.
+ type = "connected",
+ fixed = box OR {box1, box2, ...}
+ connect_top = box OR {box1, box2, ...}
+ connect_bottom = box OR {box1, box2, ...}
+ connect_front = box OR {box1, box2, ...}
+ connect_left = box OR {box1, box2, ...}
+ connect_back = box OR {box1, box2, ...}
+ connect_right = box OR {box1, box2, ...}
+ }
A `box` is defined as:
instances of 3d perlin noise with diffferent seeds, both described by
`noise_params`. `random_factor` varies the influence random chance has on
placement of an ore inside the vein, which is `1` by default. Note that
-modifying this parameter may require adjusting `noise_threshhold`.
+modifying this parameter may require adjusting `noise_threshold`.
The parameters `clust_scarcity`, `clust_num_ores`, and `clust_size` are ignored
by this ore type. This ore type is difficult to control since it is sensitive
to small changes. The following is a decent set of parameters to work from:
persist = 0.5,
flags = "eased",
},
- noise_threshhold = 1.6
+ noise_threshold = 1.6
WARNING: Use this ore type *very* sparingly since it is ~200x more
computationally expensive than any other ore.
node. It is called "node metadata"; See "`NodeMetaRef`".
Metadata contains two things:
+
* A key-value store
* An inventory
Some of the values in the key-value store are handled specially:
+
* `formspec`: Defines a right-click inventory menu. See "Formspec".
* `infotext`: Text shown on the screen when the node is pointed at
* types: `text`, `image`, `color`, `indent`, `tree`
* `text`: show cell contents as text
* `image`: cell contents are an image index, use column options to define images
- * `colo`: cell contents are a ColorString and define color of following cell
+ * `color`: cell contents are a ColorString and define color of following cell
* `indent`: cell contents are a number and define indentation of following cell
* `tree`: same as indent, but user can open and close subtrees (treeview-like)
* column options:
`colorspec = "green"`
Spatial Vectors
---------------
-
-* `vector.new([x[, y, z]])`: returns a vector.
- * `x` is a table or the `x` position.
-
+---------------
+* `vector.new(a[, b, c])`: returns a vector:
+ * A copy of `a` if `a` is a vector.
+ * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
* `vector.direction(p1, p2)`: returns a vector
* `vector.distance(p1, p2)`: returns a number
* `vector.length(v)`: returns a number
* `vector.normalize(v)`: returns a vector
-* `vector.round(v)`: returns a vector
+* `vector.round(v)`: returns a vector, each dimension rounded to floor
* `vector.apply(v, func)`: returns a vector
* `vector.equals(v1, v2)`: returns a boolean
* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
Helper functions
------------------
+----------------
* `dump2(obj, name="_", dumped={})`
* Return object serialized as a string, handles reference loops
* `dump(obj, dumped={})`
* e.g. `string:split("a,b", ",") == {"a","b"}`
* `string:trim()`
* e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
-* `minetest.pos_to_string({x=X,y=Y,z=Z})`: returns `"(X,Y,Z)"`
+* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns `"(X,Y,Z)"`
* Convert position to a printable string
+ Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
* `minetest.string_to_pos(string)`: returns a position
* Same but in reverse. Returns `nil` if the string can't be parsed to a position.
* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
* `minetest.is_yes(arg)`
* returns whether `arg` can be interpreted as yes
* `minetest.get_us_time()`
- * returns time with microsecond precision
+ * returns time with microsecond precision. May not return wall time.
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
* `minetest.register_entity(name, prototype table)`
* `minetest.register_abm(abm definition)`
+* `minetest.register_lbm(lbm definition)`
* `minetest.register_node(name, node definition)`
* `minetest.register_tool(name, item definition)`
* `minetest.register_craftitem(name, item definition)`
* Should be called by the authentication handler if privileges changes.
* To report everybody, set `name=nil`.
* `minetest.get_password_hash(name, raw_password)`
- * Convert a name-password pair to a password hash that Minetest can use
+ * Convert a name-password pair to a password hash that Minetest can use.
+ * The returned value alone is not a good basis for password checks based
+ * on comparing the password hash in the database with the password hash
+ * from the function, with an externally provided password, as the hash
+ * in the db might use the new SRP verifier format.
* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
* Convert between two privilege representations
* `minetest.remove_node(pos)`
* Equivalent to `set_node(pos, "air")`
* `minetest.get_node(pos)`
- * Returns `{name="ignore", ...}` for unloaded area
+ * Returns the node at the given position as table in the format
+ `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
+ for unloaded areas.
* `minetest.get_node_or_nil(pos)`
- * Returns `nil` for unloaded area
+ * Same as `get_node` but returns `nil` for unloaded areas.
* `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
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
* `minetest.get_timeofday()`
* `minetest.get_gametime()`: returns the time, in seconds, since the world was created
+* `minetest.get_day_count()`: returns number days elapsed since world was created,
+ * accounting for time changes.
* `minetest.find_node_near(pos, radius, nodenames)`: returns pos or `nil`
* `radius`: using a maximum metric
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `minetest.generate_decorations(vm, pos1, pos2)`
* Generate all registered decorations within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
* `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
-* `minetest.clear_objects()`
- * clear all objects in the environments
+* `minetest.clear_objects([options])`
+ * Clear all objects in the environment
+ * Takes an optional table as an argument with the field `mode`.
+ * mode = `"full"`: Load and go through every mapblock, clearing objects (default).
+ * mode = `"quick"`: Clear objects immediately in loaded mapblocks;
+ clear objects in unloaded mapblocks only when the mapblocks are next activated.
* `minetest.emerge_area(pos1, pos2, [callback], [param])`
* Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be asynchronously
* fetched from memory, loaded from disk, or if inexistent, generates them.
* Convert a facedir back into a vector aimed directly out the "back" of a node
* `minetest.dir_to_wallmounted(dir)`
* Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"`
+* `minetest.wallmounted_to_dir(wallmounted)`
+ * Convert a wallmounted value back into a vector aimed directly out the "back" of a node
* `minetest.get_node_drops(nodename, toolname)`
* Returns list of item names.
* **Note**: This will be removed or modified in a future version.
### Timing
* `minetest.after(time, func, ...)`
- * Call the function `func` after `time` seconds
+ * Call the function `func` after `time` seconds, may be fractional
* Optional: Variable number of arguments that are passed to `func`
### Server
* If `lua_num_indent_spaces` is a nonzero number and `format` is "lua", the Lua code generated
* will use that number of spaces as indentation instead of a tab character.
+### HTTP Requests:
+* `minetest.request_http_api()`:
+ * returns `HTTPApiTable` containing http functions if the calling mod has been granted
+ access by being listed in the `secure.http_mods` or `secure.trusted_mods` setting,
+ otherwise returns `nil`.
+ * The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get`
+ described below.
+ * Only works at init time and must be called from the mod's main scope (not from a function).
+ * Function only exists if minetest server was built with cURL support.
+ * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
+ A LOCAL VARIABLE!**
+* `HTTPApiTable.fetch(HTTPRequest req, callback)`
+ * Performs given request asynchronously and calls callback upon completion
+ * callback: `function(HTTPRequestResult res)`
+ * Use this HTTP function if you are unsure, the others are for advanced use.
+* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
+ * Performs given request asynchronously and returns handle for `minetest.http_fetch_async_get`
+* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
+ * Return response data for given asynchronous HTTP request
+
### Misc.
* `minetest.get_connected_players()`: returns list of `ObjectRefs`
* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
* `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.
+ * Only works at init time and must be called from the mod's main scope (not from a function).
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN
A LOCAL VARIABLE!**
* Map of Lua entities, indexed by active object id
* `minetest.registered_ores`
* List of registered ore definitions.
+* `minetest.registered_biomes`
+ * List of registered biome definitions.
* `minetest.registered_decorations`
* List of registered decoration definitions.
* `set_properties(object property table)`
* `get_properties()`: returns object property table
* `is_player()`: returns true for players, false otherwise
+* `get_nametag_attributes()`
+ * returns a table with the attributes of the nametag of an object
+ * {
+ color = {a=0..255, r=0..255, g=0..255, b=0..255},
+ text = "",
+ }
+* `set_nametag_attributes(attributes)`
+ * sets the attributes of the nametag of an object
+ * `attributes`:
+ {
+ color = ColorSpec,
+ text = "My Nametag",
+ }
##### LuaEntitySAO-only (no-op for other objects)
* `setvelocity({x=num, y=num, z=num})`
* `"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
* 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.
* `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.
+* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID, or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area. `data` is a string stored with the area. If passed, `id` will be used as the internal area ID, it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it, or insertions are likely to fail due to conflicts.
* `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.
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
}
+* `to_string()`: Experimental. Returns area store serialized as a (binary) string.
+* `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to a file.
+* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore. Returns success and, optionally, an error message.
+* `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file.
### `ItemStack`
An `ItemStack` is a stack of items.
Inside of `on_generated()` callbacks, it is possible to retrieve the same VoxelManip object used by the
core's Map Generator (commonly abbreviated Mapgen). Most of the rules previously described still apply
but with a few differences:
+
* The Mapgen VoxelManip object is retrieved using: `minetest.get_mapgen_object("voxelmanip")`
* This VoxelManip object already has the region of map just generated loaded into it; it's not necessary
to call `VoxelManip:read_from_map()` before using a Mapgen VoxelManip.
* `update_map()`: Update map after writing chunk back to map.
* To be used only by `VoxelManip` objects created by the mod itself;
not a `VoxelManip` that was retrieved from `minetest.get_mapgen_object`
-* `set_lighting(light, p1, p2)`: Set the lighting within the `VoxelManip` to a uniform value
+* `set_lighting(light, [p1, p2])`: Set the lighting within the `VoxelManip` to a uniform value
* `light` is a table, `{day=<0...15>, night=<0...15>}`
* To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
* (`p1`, `p2`) is the area in which lighting is set;
* expects lighting data in the same format that `get_light_data()` returns
* `get_param2_data()`: Gets the raw `param2` data read into the `VoxelManip` object
* `set_param2_data(param2_data)`: Sets the `param2` contents of each node in the `VoxelManip`
-* `calc_lighting(p1, p2)`: Calculate lighting within the `VoxelManip`
+* `calc_lighting([p1, p2], [propagate_shadow])`: Calculate lighting within the `VoxelManip`
* To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
* (`p1`, `p2`) is the area in which lighting is set; defaults to the whole area
- if left out
+ if left out or nil
+ * `propagate_shadow` is an optional boolean deciding whether shadows in a generated
+ mapchunk above are propagated down into the mapchunk; defaults to `true` if left out
* `update_liquids()`: Update liquid flow
* `was_modified()`: Returns `true` or `false` if the data in the voxel manipulator
had been modified since the last read from map, due to a call to
stepheight = 0,
automatic_face_movement_dir = 0.0,
-- ^ automatically set yaw to movement direction; offset in degrees; false to disable
+ automatic_face_movement_max_rotation_per_sec = -1,
+ -- ^ limit automatic rotation to this value in degrees per second. values < 0 no limit
backface_culling = true, -- false to disable backface_culling for model
+ nametag = "", -- by default empty, for players their name is shown if empty
+ nametag_color = <color>, -- sets color of nametag as ColorSpec
+ infotext = "", -- by default empty, text to be shown when pointed at object
}
### Entity definition (`register_entity`)
action = func(pos, node, active_object_count, active_object_count_wider),
}
+### LBM (LoadingBlockModifier) definition (`register_lbm`)
+
+ {
+ name = "modname:replace_legacy_door",
+ nodenames = {"default:lava_source"},
+ -- ^ List of node names to trigger the LBM on.
+ -- Also non-registered nodes will work.
+ -- Groups (as of group:groupname) will work as well.
+ run_at_every_load = false,
+ -- ^ Whether to run the LBM's action every time a block gets loaded,
+ -- and not just for blocks that were saved last time before LBMs were
+ -- introduced to the world.
+ action = func(pos, node),
+ }
+
### Item definition (`register_node`, `register_craftitem`, `register_tool`)
{
--[[
^ Shall place item and return the leftover itemstack
^ default: minetest.item_place ]]
+ on_secondary_use = func(itemstack, user, pointed_thing),
+ --[[
+ ^ Same as on_place but called when pointing at nothing.
+ ^ pointed_thing : always { type = "nothing" }
+ ]]
on_drop = func(itemstack, dropper, pos),
--[[
^ Shall drop item and return the leftover itemstack
* `{name="image.png", animation={Tile Animation definition}}`
* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
tileable_horizontal=bool}`
- * backface culling only supported in special tiles.
+ * backface culling enabled by default for most nodes
* 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,
diggable = true, -- If false, can never be dug
climbable = false, -- If true, can be climbed on (ladder)
buildable_to = false, -- If true, placed nodes can replace this node
+ floodable = false, -- If true, liquids flow into and replace this node
liquidtype = "none", -- "none"/"source"/"flowing"
liquid_alternative_flowing = "", -- Flowing version of source liquid
liquid_alternative_source = "", -- Source version of flowing liquid
light_source = 0, -- Amount of light emitted by node
damage_per_second = 0, -- If player is inside node, this damage is caused
node_box = {type="regular"}, -- See "Node boxes"
+ connects_to = nodenames, --[[
+ * Used for nodebox nodes with the type == "connected"
+ * Specifies to what neighboring nodes connections will be drawn
+ * e.g. `{"group:fence", "default:wood"}` or `"default:stone"` ]]
+ connect_sides = { "top", "bottom", "front", "left", "back", "right" }, --[[
+ ^ Tells connected nodebox nodes to connect only to these sides of this node. ]]
mesh = "model",
selection_box = {type="regular"}, -- See "Node boxes" --[[
^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
y_max = 64,
flags = "",
-- ^ Attributes for this ore generation
- noise_threshhold = 0.5,
+ noise_threshold = 0.5,
-- ^ If noise is above this threshold, ore is placed. Not needed for a uniform distribution
noise_params = {offset=0, scale=1, spread={x=100, y=100, z=100}, seed=23, octaves=3, persist=0.70}
-- ^ NoiseParams structure describing the perlin noise used for ore distribution.
-- ^ Minimum and maximum `y` positions these decorations can be generated at.
-- ^ This parameter refers to the `y` position of the decoration base, so
-- the actual maximum height would be `height_max + size.Y`.
- flags = "liquid_surface",
+ flags = "liquid_surface, force_placement",
-- ^ Flags for all decoration types.
-- ^ "liquid_surface": Instead of placement on the highest solid surface
-- ^ in a mapchunk column, placement is on the highest liquid surface.
-- ^ Placement is disabled if solid nodes are found above the liquid surface.
+ -- ^ "force_placement": Nodes other than "air" and "ignore" are replaced by the decoration.
----- Simple-type parameters
decoration = "default:grass",
},
-- ^ See 'Schematic specifier' for details.
replacements = {["oldname"] = "convert_to", ...},
- flags = "place_center_x, place_center_y, place_center_z, force_placement",
+ flags = "place_center_x, place_center_y, place_center_z",
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
rotation = "90" -- rotate schematic 90 degrees on placement
-- ^ Rotation can be "0", "90", "180", "270", or "random".
playername = "singleplayer"
-- ^ Playername is optional, if specified spawns particle only on the player's client
}
+
+### `HTTPRequest` definition (`http_fetch`, `http_fetch_async`)
+
+ {
+ url = "http://example.org",
+ timeout = 10,
+ -- ^ Timeout for connection in seconds. Default is 3 seconds.
+ post_data = "Raw POST request data string" OR { field1 = "data1", field2 = "data2" },
+ -- ^ Optional, if specified a POST request with post_data is performed.
+ -- ^ Accepts both a string and a table. If a table is specified, encodes table
+ -- ^ as x-www-form-urlencoded key-value pairs.
+ -- ^ If post_data ist not specified, a GET request is performed instead.
+ user_agent = "ExampleUserAgent",
+ -- ^ Optional, if specified replaces the default minetest user agent with given string
+ extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
+ -- ^ Optional, if specified adds additional headers to the HTTP request. You must make sure
+ -- ^ that the header strings follow HTTP specification ("Key: Value").
+ multipart = boolean
+ -- ^ Optional, if true performs a multipart HTTP request. Default is false.
+ }
+
+### `HTTPRequestResult` definition (`http_fetch` callback, `http_fetch_async_get`)
+
+ {
+ completed = true,
+ -- ^ If true, the request has finished (either succeeded, failed or timed out)
+ succeeded = true,
+ -- ^ If true, the request was succesful
+ timeout = false,
+ -- ^ If true, the request timed out
+ code = 200,
+ -- ^ HTTP status code
+ data = "response"
+ }