-Minetest Lua Modding API Reference 0.4.15
+Minetest Lua Modding API Reference 0.4.16
=========================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
If the `ItemStack`'s metadata contains the `color` field, it will be
lost on placement, because nodes on the map can only use palettes.
-If the `ItemStack`'s metadata contains the `palette_index` field, you
-currently must manually convert between it and the node's `param2` with
-custom `on_place` and `on_dig` callbacks.
+If the `ItemStack`'s metadata contains the `palette_index` field, it is
+automatically transferred between node and item forms by the engine,
+when a player digs or places a colored node.
+You can disable this feature by setting the `drop` field of the node
+to itself (without metadata).
### Colored items in craft recipes
Craft recipes only support item strings, but fortunately item strings
can also contain metadata. Example craft recipe registration:
- local stack = ItemStack("wool:block")
- dyed:get_meta():set_int("palette_index", 3) -- add index
minetest.register_craft({
- output = dyed:to_string(), -- convert to string
+ output = minetest.itemstring_with_palette("wool:block", 3),
type = "shapeless",
recipe = {
"wool:block",
},
})
+To set the `color` field, you can use `minetest.itemstring_with_color`.
+
Metadata field filtering in the `recipe` field are not supported yet,
so the craft output is independent of the color of the ingredients.
description = "Dirt with Grass",
-- Regular tiles, as usual
-- The dirt tile disables palette coloring
- tiles = {{name = "default_grass.png"},
+ tiles = {{name = "default_grass.png"},
{name = "default_dirt.png", color = "white"}},
-- Overlay tiles: define them in the same style
-- The top and bottom tile does not have overlay
{
gain = 1.0, -- default
fade = 0.0, -- default, change to a value > 0 to fade the sound in
+ pitch = 1.0, -- default
}
-- Play locationless to one player
{
to_player = name,
gain = 1.0, -- default
fade = 0.0, -- default, change to a value > 0 to fade the sound in
+ pitch = 1.0, -- default
}
-- Play locationless to one player, looped
{
* e.g. `{}`
* e.g. `{name = "default_place_node"}`
* e.g. `{name = "default_place_node", gain = 1.0}`
+* e.g. `{name = "default_place_node", gain = 1.0, pitch = 1.0}`
Registered definitions of stuff
-------------------------------
* `raillike`
* `nodebox` -- See below. (**Experimental!**)
* `mesh` -- use models for nodes
+* `plantlike_rooted`
`*_optional` drawtypes need less rendering time if deactivated (always client side).
See section "Flag Specifier Format".
Currently supported flags:
-`absheight`, `puff_cliffs`, `puff_additive_composition`.
-
-### `absheight`
-Also produce this same ore between the height range of `-y_max` and `-y_min`.
-
-Useful for having ore in sky realms without having to duplicate ore entries.
+`puff_cliffs`, `puff_additive_composition`.
### `puff_cliffs`
If set, puff ore generation will not taper down large differences in displacement
* Clickable button. When clicked, fields will be sent.
* `x`, `y` and `name` work as per field
* `w` and `h` are the size of the button
+* Fixed button height. It will be vertically centred on `h`
* `label` is the text on the button
* Position and size units are inventory slots
`minetest.get_color_escape_sequence(color) ..
message ..
minetest.get_color_escape_sequence("#ffffff")`
-* `color.get_background_escape_sequence(color)`
+* `minetest.get_background_escape_sequence(color)`
* `color` is a ColorString
* The escape sequence sets the background of the whole text element to
`color`. Only defined for item descriptions and tooltips.
-* `color.strip_foreground_colors(str)`
+* `minetest.strip_foreground_colors(str)`
* Removes foreground colors added by `get_color_escape_sequence`.
-* `color.strip_background_colors(str)`
+* `minetest.strip_background_colors(str)`
* Removes background colors added by `get_background_escape_sequence`.
-* `color.strip_colors(str)`
+* `minetest.strip_colors(str)`
* Removes all color escape sequences.
Spatial Vectors
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `search_center` is an optional boolean (default: `false`)
If true `pos` is also checked for the nodes
-* `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
+* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of positions
* `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
+ * First return value: Table with all node positions
+ * Second return value: Table with the count of each node with the node name as index
+* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a list of positions
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
+ * Return value: Table with all node positions with a node air above
* `minetest.get_perlin(noiseparams)`
* `minetest.get_perlin(seeddiff, octaves, persistence, scale)`
* Return world-specific perlin noise (`int(worldseed)+seeddiff`)
* `pos2`: Second position
* `stepsize`: smaller gives more accurate results but requires more computing
time. Default is `1`.
+* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast`
+ * Creates a `Raycast` object.
+ * `pos1`: start of the ray
+ * `pos2`: end of the ray
+ * `objects` : if false, only nodes will be returned. Default is `true`.
+ * `liquids' : if false, liquid nodes won't be returned. Default is `false`.
* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)`
* returns table containing path
* returns a table of 3D points representing a path from `pos1` to `pos2` or `nil`
* Example query for `"default:gold_ingot"` will return table:
{
- [1]={type = "cooking", width = 3, output = "default:gold_ingot",
+ [1]={method = "cooking", width = 3, output = "default:gold_ingot",
items = {1 = "default:gold_lump"}},
- [2]={type = "normal", width = 1, output = "default:gold_ingot 9",
+ [2]={method = "normal", width = 1, output = "default:gold_ingot 9",
items = {1 = "default:goldblock"}}
}
* `minetest.handle_node_drops(pos, drops, digger)`
digger's inventory
* Can be overridden to get different functionality (e.g. dropping items on
ground)
+* `minetest.itemstring_with_palette(item, palette_index)`: returns an item string
+ * Creates an item string which contains palette index information
+ for hardware colorization. You can use the returned string
+ as an output in a craft recipe.
+ * `item`: the item stack which becomes colored. Can be in string,
+ table and native form.
+ * `palette_index`: this index is added to the item stack
+* `minetest.itemstring_with_color(item, colorstring)`: returns an item string
+ * Creates an item string which contains static color information
+ for hardware colorization. Use this method if you wish to colorize
+ an item that does not own a palette. You can use the returned string
+ as an output in a craft recipe.
+ * `item`: the item stack which becomes colored. Can be in string,
+ table and native form.
+ * `colorstring`: the new color of the item stack
### Rollback
* `minetest.rollback_get_node_actions(pos, range, seconds, limit)`:
* `minetest.get_server_status()`: returns server status string
* `minetest.get_server_uptime()`: returns the server uptime in seconds
* `minetest.remove_player(name)`: remove player from database (if he is not connected).
+ * Does not remove player authentication data, minetest.player_exists will continue to return true.
* Returns a code (0: successful, 1: no such player, 2: player is connected)
### Bans
* See documentation on `minetest.compress()` for supported compression methods.
* currently supported.
* `...` indicates method-specific arguments. Currently, no methods use this.
+* `minetest.rgba(red, green, blue[, alpha])`: returns a string
+ * Each argument is a 8 Bit unsigned integer
+ * Returns the ColorString from rgb or rgba values
+ * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
* `minetest.encode_base64(string)`: returns string encoded in base64
* Encodes a string in base64.
* `minetest.decode_base64(string)`: returns string
* `add_item(listname, stack)`: add item somewhere in list, returns leftover `ItemStack`
* `room_for_item(listname, stack):` returns `true` if the stack of items
can be fully added to the list
-* `contains_item(listname, stack)`: returns `true` if the stack of items
- can be fully taken from the list
+* `contains_item(listname, stack, [match_meta])`: returns `true` if
+ the stack of items can be fully taken from the list.
+ If `match_meta` is false, only the items' names are compared (default: `false`).
* `remove_item(listname, stack)`: take as many items as specified from the list,
returns the items that were actually removed (as an `ItemStack`) -- note that
any item metadata is ignored, so attempting to remove a specific unique
* Writes changes to file.
* `to_table()`: returns `{[key1]=value1,...}`
+### `Raycast`
+A raycast on the map. It works with selection boxes.
+Can be used as an iterator in a for loop.
+
+The map is loaded as the ray advances. If the
+map is modified after the `Raycast` is created,
+the changes may or may not have an effect on
+the object.
+
+It can be created via `Raycast(pos1, pos2, objects, liquids)` or
+`minetest.raycast(pos1, pos2, objects, liquids)` where:
+ * `pos1`: start of the ray
+ * `pos2`: end of the ray
+ * `objects` : if false, only nodes will be returned. Default is true.
+ * `liquids' : if false, liquid nodes won't be returned. Default is false.
+
+#### Methods
+* `next()`: returns a `pointed_thing`
+ * Returns the next thing pointed by the ray or nil.
+
Mapgen objects
--------------
A mapgen object is a construct used in map generation. Mapgen objects can be used
-- ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore
y_min = -31000,
y_max = 64,
+ -- ^ Lower and upper limits for ore.
+ -- ^ Limits are relative to y = water_level - 1 for core mapgen, or
+ -- ^ relative to y = 0 for minetest.generate_ores().
flags = "",
-- ^ Attributes for this ore generation
noise_threshold = 0.5,
-- ^ Needed for sheet ore_type. Omit from scatter ore_type for a uniform ore distribution
random_factor = 1.0,
-- ^ Multiplier of the randomness contribution to the noise value at any
- -- given point to decide if ore should be placed. Set to 0 for solid veins.
+ -- ^ given point to decide if ore should be placed. Set to 0 for solid veins.
-- ^ This parameter is only valid for ore_type == "vein".
biomes = {"desert", "rainforest"}
-- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted,
y_min = 1,
y_max = 31000,
-- ^ Lower and upper limits for biome.
+ -- ^ Limits are relative to y = water_level - 1.
-- ^ Because biome is not recalculated for every node in a node column
-- ^ some biome materials can exceed their limits, especially stone.
-- ^ For each node column in a mapchunk, biome is only recalculated at column
-- ^ Can be a list of (or a single) biome names, IDs, or definitions.
y_min = -31000
y_max = 31000
- -- ^ 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`.
+ -- ^ Lower and upper limits for decoration.
+ -- ^ Limits are relative to y = water_level - 1 for core mapgen, or
+ -- ^ relative to y = 0 for minetest.generate_decorations().
+ -- ^ This parameter refers to the `y` position of the decoration base, so
+ -- the actual maximum height would be `height_max + size.Y`.
spawn_by = "default:water",
-- ^ Node (or list of nodes) that the decoration only spawns next to.
-- ^ Checks two horizontal planes of neighbouring nodes (including diagonal neighbours),
projects / oweals / minetest.git / blobdiff