minetest
/
minetest
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve lua_api.txt a bunch

master
sfan5 2022-06-10 23:12:17 +02:00
parent c10fe7ec18
commit 804c255941
1 changed files with 211 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

412
doc/lua_api.txt
View File

@ -35,19 +35,16 @@ the `init.lua` scripts in a shared environment.
Paths Paths
----- -----
* `RUN_IN_PLACE=1` (Windows release, local build) Minetest keeps and looks for files mostly in two paths. `path_share` or `path_user`.
* `$path_user`: `<build directory>`
* `$path_share`: `<build directory>`
* `RUN_IN_PLACE=0`: (Linux release)
* `$path_share`:
* Linux: `/usr/share/minetest`
* Windows: `<install directory>/minetest-0.4.x`
* `$path_user`:
* Linux: `$HOME/.minetest`
* Windows: `C:/users/<user>/AppData/minetest` (maybe)
`path_share` contains possibly read-only content for the engine (incl. games and mods).
`path_user` contains mods or games installed by the user but also the users
worlds or settings.
With a local build (`RUN_IN_PLACE=1`) `path_share` and `path_user` both point to
the build directory. For system-wide builds on Linux the share path is usually at
`/usr/share/minetest` while the user path resides in `.minetest` in the home directory.
Paths on other operating systems will differ.
Games Games
===== =====
@ -214,8 +211,6 @@ A `Settings` file that provides meta information about the mod.
internal ID used to track versions. internal ID used to track versions.
* `title`: A human-readable title to address the mod. * `title`: A human-readable title to address the mod.
Note: to support 0.4.x, please also provide depends.txt.
### `screenshot.png` ### `screenshot.png`
A screenshot shown in the mod manager within the main menu. It should A screenshot shown in the mod manager within the main menu. It should
@ -304,8 +299,8 @@ Any mod can redefine `experimental:tnt` by using the name
:experimental:tnt :experimental:tnt
when registering it. That mod is required to have `experimental` as a when registering it. For this to work correctly, that mod must have
dependency. `experimental` as a dependency.
@ -346,9 +341,9 @@ of the game's nodes are to be used for core mapgen generation. For example:
#### Essential aliases #### Essential aliases
* mapgen_stone * `mapgen_stone`
* mapgen_water_source * `mapgen_water_source`
* mapgen_river_water_source * `mapgen_river_water_source`
`mapgen_river_water_source` is required for mapgens with sloping rivers where `mapgen_river_water_source` is required for mapgens with sloping rivers where
it is necessary to have a river liquid node with a short `liquid_range` and it is necessary to have a river liquid node with a short `liquid_range` and
@ -356,50 +351,56 @@ it is necessary to have a river liquid node with a short `liquid_range` and
#### Optional aliases #### Optional aliases
* mapgen_lava_source * `mapgen_lava_source`
Fallback lava node used if cave liquids are not defined in biome definitions. Fallback lava node used if cave liquids are not defined in biome definitions.
Deprecated for non-V6 mapgens, define cave liquids in biome definitions instead. Deprecated, define cave liquids in biome definitions instead.
* mapgen_cobble * `mapgen_cobble`
Fallback node used if dungeon nodes are not defined in biome definitions. Fallback node used if dungeon nodes are not defined in biome definitions.
Deprecated for non-V6 mapgens, define dungeon nodes in biome definitions instead. Deprecated, define dungeon nodes in biome definitions instead.
### Aliases needed for Mapgen V6 ### Aliases for Mapgen V6
* mapgen_stone #### Essential
* mapgen_water_source
* mapgen_lava_source
* mapgen_dirt
* mapgen_dirt_with_grass
* mapgen_sand
* mapgen_gravel
* mapgen_desert_stone
* mapgen_desert_sand
* mapgen_dirt_with_snow
* mapgen_snowblock
* mapgen_snow
* mapgen_ice
* mapgen_tree * `mapgen_stone`
* mapgen_leaves * `mapgen_water_source`
* mapgen_apple * `mapgen_lava_source`
* mapgen_jungletree * `mapgen_dirt`
* mapgen_jungleleaves * `mapgen_dirt_with_grass`
* mapgen_junglegrass * `mapgen_sand`
* mapgen_pine_tree
* mapgen_pine_needles
* mapgen_cobble * `mapgen_tree`
* mapgen_stair_cobble * `mapgen_leaves`
* mapgen_mossycobble * `mapgen_apple`
* mapgen_stair_desert_stone
* `mapgen_cobble`
#### Optional
* `mapgen_gravel` (falls back to stone)
* `mapgen_desert_stone` (falls back to stone)
* `mapgen_desert_sand` (falls back to sand)
* `mapgen_dirt_with_snow` (falls back to dirt_with_grass)
* `mapgen_snowblock` (falls back to dirt_with_grass)
* `mapgen_snow` (not placed if missing)
* `mapgen_ice` (falls back to water_source)
* `mapgen_jungletree` (falls back to tree)
* `mapgen_jungleleaves` (falls back to leaves)
* `mapgen_junglegrass` (not placed if missing)
* `mapgen_pine_tree` (falls back to tree)
* `mapgen_pine_needles` (falls back to leaves)
* `mapgen_stair_cobble` (falls back to cobble)
* `mapgen_mossycobble` (falls back to cobble)
* `mapgen_stair_desert_stone` (falls backto desert_stone)
### Setting the node used in Mapgen Singlenode ### Setting the node used in Mapgen Singlenode
By default the world is filled with air nodes. To set a different node use, for By default the world is filled with air nodes. To set a different node use e.g.:
example:
minetest.register_alias("mapgen_singlenode", "default:stone") minetest.register_alias("mapgen_singlenode", "default:stone")
@ -420,6 +421,9 @@ stripping out the file extension:
* e.g. `foomod_foothing.png` * e.g. `foomod_foothing.png`
* e.g. `foomod_foothing` * e.g. `foomod_foothing`
Supported texture formats are PNG (`.png`), JPEG (`.jpg`), Bitmap (`.bmp`)
and Targa (`.tga`).
Since better alternatives exist, the latter two may be removed in the future.
Texture modifiers Texture modifiers
----------------- -----------------
@ -982,15 +986,10 @@ Example:
All nodes register with `minetest.register_node` get added to the table All nodes register with `minetest.register_node` get added to the table
`minetest.registered_nodes`. `minetest.registered_nodes`.
If you want to check the drawtype of a node, you could do: If you want to check the drawtype of a node, you could do it like this:
local function get_nodedef_field(nodename, fieldname) local def = minetest.registered_nodes[nodename]
if not minetest.registered_nodes[nodename] then local drawtype = def and def.drawtype
return nil
end
return minetest.registered_nodes[nodename][fieldname]
end
local drawtype = get_nodedef_field(nodename, "drawtype")
@ -1966,21 +1965,21 @@ Tool capabilities define:
* Damage groups * Damage groups
* Punch attack uses (until the tool breaks) * Punch attack uses (until the tool breaks)
### Full punch interval ### Full punch interval `full_punch_interval`
When used as a weapon, the item will do full damage if this time is spent When used as a weapon, the item will do full damage if this time is spent
between punches. If e.g. half the time is spent, the item will do half between punches. If e.g. half the time is spent, the item will do half
damage. damage.
### Maximum drop level ### Maximum drop level `max_drop_level`
Suggests the maximum level of node, when dug with the item, that will drop Suggests the maximum level of node, when dug with the item, that will drop
its useful item. (e.g. iron ore to drop a lump of iron). its useful item. (e.g. iron ore to drop a lump of iron).
This is not automated; it is the responsibility of the node definition This value is not used in the engine; it is the responsibility of the game/mod
to implement this. code to implement this.
### Uses (tools only) ### Uses `uses` (tools only)
Determines how many uses the tool has when it is used for digging a node, Determines how many uses the tool has when it is used for digging a node,
of this group, of the maximum level. The maximum supported number of of this group, of the maximum level. The maximum supported number of
@ -1995,17 +1994,17 @@ node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
For non-tools, this has no effect. For non-tools, this has no effect.
### Maximum level ### Maximum level `maxlevel`
Tells what is the maximum level of a node of this group that the item will Tells what is the maximum level of a node of this group that the item will
be able to dig. be able to dig.
### Digging times ### Digging times `times`
List of digging times for different ratings of the group, for nodes of the List of digging times for different ratings of the group, for nodes of the
maximum level. maximum level.
For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would For example, as a Lua table, `times={[2]=2.00, [3]=0.70}`. This would
result in the item to be able to dig nodes that have a rating of `2` or `3` result in the item to be able to dig nodes that have a rating of `2` or `3`
for this group, and unable to dig the rating `1`, which is the toughest. for this group, and unable to dig the rating `1`, which is the toughest.
Unless there is a matching group that enables digging otherwise. Unless there is a matching group that enables digging otherwise.
@ -2033,12 +2032,9 @@ Example definition of the capabilities of an item
------------------------------------------------- -------------------------------------------------
tool_capabilities = { tool_capabilities = {
full_punch_interval=1.5,
max_drop_level=1,
groupcaps={ groupcaps={
crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
}, },
damage_groups = {fleshy=2},
} }
This makes the item capable of digging nodes that fulfil both of these: This makes the item capable of digging nodes that fulfil both of these:
@ -4296,15 +4292,15 @@ differences:
* The Mapgen VoxelManip object is retrieved using: * The Mapgen VoxelManip object is retrieved using:
`minetest.get_mapgen_object("voxelmanip")` `minetest.get_mapgen_object("voxelmanip")`
* This VoxelManip object already has the region of map just generated loaded * 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 into it; it's not necessary to call `VoxelManip:read_from_map()`.
a Mapgen VoxelManip. Note that the region of map it has loaded is NOT THE SAME as the `minp`, `maxp`
parameters of `on_generated()`. Refer to `minetest.get_mapgen_object` docs.
* The `on_generated()` callbacks of some mods may place individual nodes in the * The `on_generated()` callbacks of some mods may place individual nodes in the
generated area using non-VoxelManip map modification methods. Because the generated area using non-VoxelManip map modification methods. Because the
same Mapgen VoxelManip object is passed through each `on_generated()` same Mapgen VoxelManip object is passed through each `on_generated()`
callback, it becomes necessary for the Mapgen VoxelManip object to maintain callback, it becomes necessary for the Mapgen VoxelManip object to maintain
consistency with the current map state. For this reason, calling any of the consistency with the current map state. For this reason, calling any of
following functions: `minetest.add_node()`, `minetest.set_node()` or `minetest.swap_node()`
`minetest.add_node()`, `minetest.set_node()`, or `minetest.swap_node()`
will also update the Mapgen VoxelManip object's internal state active on the will also update the Mapgen VoxelManip object's internal state active on the
current thread. current thread.
* After modifying the Mapgen VoxelManip object's internal buffer, it may be * After modifying the Mapgen VoxelManip object's internal buffer, it may be
@ -4417,7 +4413,7 @@ Methods
----------- -----------
A helper class for voxel areas. A helper class for voxel areas.
It can be created via `VoxelArea:new{MinEdge = pmin, MaxEdge = pmax}`. It can be created via `VoxelArea:new({MinEdge = pmin, MaxEdge = pmax})`.
The coordinates are *inclusive*, like most other things in Minetest. The coordinates are *inclusive*, like most other things in Minetest.
### Methods ### Methods
@ -4465,7 +4461,7 @@ the axes in a voxel area:
If, for example: If, for example:
local area = VoxelArea:new{MinEdge = emin, MaxEdge = emax} local area = VoxelArea:new({MinEdge = emin, MaxEdge = emax})
The values of `ystride` and `zstride` can be obtained using `area.ystride` and The values of `ystride` and `zstride` can be obtained using `area.ystride` and
`area.zstride`. `area.zstride`.
@ -4539,11 +4535,11 @@ numeric unique decoration ID as returned by `minetest.get_decoration_id`.
Registered entities Registered entities
=================== ===================
Functions receive a "luaentity" as `self`: Functions receive a "luaentity" table as `self`:
* It has the member `.name`, which is the registered name `("mod:thing")` * It has the member `name`, which is the registered name `("mod:thing")`
* It has the member `.object`, which is an `ObjectRef` pointing to the object * It has the member `object`, which is an `ObjectRef` pointing to the object
* The original prototype stuff is visible directly via a metatable * The original prototype is visible directly via a metatable
Callbacks: Callbacks:
@ -4559,10 +4555,10 @@ Callbacks:
* Note that this won't be called if the object hasn't been activated in the first place. * 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, In particular, `minetest.clear_objects({mode = "full"})` won't call this,
whereas `minetest.clear_objects({mode = "quick"})` might call this. whereas `minetest.clear_objects({mode = "quick"})` might call this.
* `on_step(self, dtime)` * `on_step(self, dtime, moveresult)`
* Called on every server tick, after movement and collision processing. * Called on every server tick, after movement and collision processing.
`dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting * `dtime`: elapsed time since last call
in `minetest.conf`. * `moveresult`: table with collision info (only available if physical=true)
* `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir, damage)` * `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir, damage)`
* Called when somebody punches the object. * Called when somebody punches the object.
* Note that you probably want to handle most punches using the automatic * Note that you probably want to handle most punches using the automatic
@ -4593,6 +4589,30 @@ Callbacks:
* Should return a string that will be passed to `on_activate` when the * Should return a string that will be passed to `on_activate` when the
object is instantiated the next time. object is instantiated the next time.
Collision info passed to `on_step` (`moveresult` argument):
{
touching_ground = boolean,
-- Note that touching_ground is only true if the entity was moving and
-- collided with ground.
collides = boolean,
standing_on_object = boolean,
collisions = {
{
type = string, -- "node" or "object",
axis = string, -- "x", "y" or "z"
node_pos = vector, -- if type is "node"
object = ObjectRef, -- if type is "object"
old_velocity = vector,
new_velocity = vector,
},
...
}
-- `collisions` does not contain data of unloaded mapblock collisions
-- or when the velocity changes are negligibly small
}
@ -5394,8 +5414,7 @@ Environment access
* Deprecated: use `minetest.set_mapgen_setting(name, value, override)` * Deprecated: use `minetest.set_mapgen_setting(name, value, override)`
instead. instead.
* Set map generation parameters. * Set map generation parameters.
* Function cannot be called after the registration period; only * Function cannot be called after the registration period.
initialization and `on_mapgen_init`.
* Takes a table as an argument with the fields: * Takes a table as an argument with the fields:
* `mgname` * `mgname`
* `seed` * `seed`
@ -5701,14 +5720,19 @@ Item handling
* `width`: 0-3, 0 means shapeless recipe * `width`: 0-3, 0 means shapeless recipe
* `items`: indexed [1-9] table with recipe items * `items`: indexed [1-9] table with recipe items
* `output`: string with item name and quantity * `output`: string with item name and quantity
* Example query for `"default:gold_ingot"` will return table: * Example result for `"default:gold_ingot"` with two recipes:
{ {
[1]={method = "cooking", width = 3, output = "default:gold_ingot", {
items = {1 = "default:gold_lump"}}, method = "cooking", width = 3,
[2]={method = "normal", width = 1, output = "default:gold_ingot 9", output = "default:gold_ingot", items = {"default:gold_lump"}
items = {1 = "default:goldblock"}} },
{
method = "normal", width = 1,
output = "default:gold_ingot 9", items = {"default:goldblock"}
}
} }
* `minetest.handle_node_drops(pos, drops, digger)` * `minetest.handle_node_drops(pos, drops, digger)`
* `drops`: list of itemstrings * `drops`: list of itemstrings
* Handles drops from nodes after digging: Default action is to put them * Handles drops from nodes after digging: Default action is to put them
@ -6735,8 +6759,7 @@ object you are working with still exists.
* `set_hp(hp, reason)`: set number of health points * `set_hp(hp, reason)`: set number of health points
* See reason in register_on_player_hpchange * See reason in register_on_player_hpchange
* Is limited to the range of 0 ... 65535 (2^16 - 1) * Is limited to the range of 0 ... 65535 (2^16 - 1)
* For players: HP are also limited by `hp_max` specified in the player's * For players: HP are also limited by `hp_max` specified in object properties
object properties
* `get_inventory()`: returns an `InvRef` for players, otherwise returns `nil` * `get_inventory()`: returns an `InvRef` for players, otherwise returns `nil`
* `get_wield_list()`: returns the name of the inventory list the wielded item * `get_wield_list()`: returns the name of the inventory list the wielded item
is in. is in.
@ -7132,10 +7155,10 @@ object you are working with still exists.
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`) * in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
* `get_eye_offset()`: returns first and third person offsets. * `get_eye_offset()`: returns first and third person offsets.
* `send_mapblock(blockpos)`: * `send_mapblock(blockpos)`:
* Sends a server-side loaded mapblock to the player. * Sends an already loaded mapblock to the player.
* Returns `false` if failed. * Returns `false` if nothing was sent (note that this can also mean that
the client already has the block)
* Resource intensive - use sparsely * Resource intensive - use sparsely
* To get blockpos, integer divide pos by 16
* `set_lighting(light_definition)`: sets lighting for the player * `set_lighting(light_definition)`: sets lighting for the player
* `light_definition` is a table with the following optional fields: * `light_definition` is a table with the following optional fields:
* `shadows` is a table that controls ambient shadows * `shadows` is a table that controls ambient shadows
@ -7348,7 +7371,7 @@ The settings have the format `key = value`. Example:
Mod metadata: per mod metadata, saved automatically. Mod metadata: per mod metadata, saved automatically.
Can be obtained via `minetest.get_mod_storage()` during load time. Can be obtained via `minetest.get_mod_storage()` during load time.
WARNING: This storage backend is incaptable to save raw binary data due WARNING: This storage backend is incapable of saving raw binary data due
to restrictions of JSON. to restrictions of JSON.
### Methods ### Methods
@ -7370,8 +7393,10 @@ corresponding Lua entity using the given registration fields.
Player properties need to be saved manually. Player properties need to be saved manually.
{ {
hp_max = 1, hp_max = 10,
-- For players only. Defaults to `minetest.PLAYER_MAX_HP_DEFAULT`. -- Defines the maximum and default HP of the entity
-- For Lua entities the maximum is not enforced.
-- For players this defaults to `minetest.PLAYER_MAX_HP_DEFAULT`.
breath_max = 0, breath_max = 0,
-- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`. -- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`.
@ -7386,22 +7411,21 @@ Player properties need to be saved manually.
eye_height = 1.625, eye_height = 1.625,
-- For players only. Camera height above feet position in nodes. -- For players only. Camera height above feet position in nodes.
-- Defaults to 1.625.
physical = true, physical = false,
-- Collide with `walkable` nodes. -- Collide with `walkable` nodes.
collide_with_objects = true, collide_with_objects = true,
-- Collide with other objects if physical = true -- Collide with other objects if physical = true
collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, -- Default collisionbox = {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
selectionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, selectionbox = {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
-- Selection box uses collision box dimensions when not set. -- Selection box uses collision box dimensions when not set.
-- For both boxes: {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from -- For both boxes: {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from
-- object position. -- object position.
pointable = true, pointable = true,
-- Overrides selection box when false -- Whether the object can be pointed at
visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item", visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item",
-- "cube" is a node-sized cube. -- "cube" is a node-sized cube.
@ -7538,50 +7562,26 @@ Used by `minetest.register_entity`.
..., ...,
}, },
-- A table of object properties, see the `Object properties` section. -- A table of object properties, see the `Object properties` section.
-- Object properties being read directly from the entity definition -- The properties in this table are applied to the object
-- table is deprecated. Define object properties in this -- once when it is spawned.
-- `initial_properties` table instead.
-- Refer to the "Registered entities" section for explanations
on_activate = function(self, staticdata, dtime_s), on_activate = function(self, staticdata, dtime_s),
on_deactivate = function(self, removal),
on_step = function(self, dtime, moveresult), on_step = function(self, dtime, moveresult),
-- Called every server step on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir, damage),
-- dtime: Elapsed time on_death = function(self, killer),
-- moveresult: Table with collision info (only available if physical=true)
on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
on_rightclick = function(self, clicker), on_rightclick = function(self, clicker),
on_attach_child = function(self, child),
on_detach_child = function(self, child),
on_detach = function(self, parent),
get_staticdata = function(self), get_staticdata = function(self),
-- Called sometimes; the string returned is passed to on_activate when
-- the entity is re-activated from static state
_custom_field = whatever, _custom_field = whatever,
-- You can define arbitrary member variables here (see Item definition -- You can define arbitrary member variables here (see Item definition
-- for more info) by using a '_' prefix -- for more info) by using a '_' prefix
} }
Collision info passed to `on_step` (`moveresult` argument):
{
touching_ground = boolean,
collides = boolean,
standing_on_object = boolean,
collisions = {
{
type = string, -- "node" or "object",
axis = string, -- "x", "y" or "z"
node_pos = vector, -- if type is "node"
object = ObjectRef, -- if type is "object"
old_velocity = vector,
new_velocity = vector,
},
...
}
-- `collisions` does not contain data of unloaded mapblock collisions
-- or when the velocity changes are negligibly small
}
ABM (ActiveBlockModifier) definition ABM (ActiveBlockModifier) definition
------------------------------------ ------------------------------------
@ -7612,7 +7612,7 @@ Used by `minetest.register_abm`.
min_y = -32768, min_y = -32768,
max_y = 32767, max_y = 32767,
-- min and max height levels where ABM will be processed -- min and max height levels where ABM will be processed (inclusive)
-- can be used to reduce CPU usage -- can be used to reduce CPU usage
catch_up = true, catch_up = true,
@ -7646,6 +7646,7 @@ gets activated (not loaded!)
-- Definitions with identical labels will be listed as one. -- Definitions with identical labels will be listed as one.
name = "modname:replace_legacy_door", name = "modname:replace_legacy_door",
-- String or table with node names to trigger on
nodenames = {"default:lava_source"}, nodenames = {"default:lava_source"},
-- List of node names to trigger the LBM on. -- List of node names to trigger the LBM on.
@ -7658,6 +7659,7 @@ gets activated (not loaded!)
-- was introduced. -- was introduced.
action = function(pos, node), action = function(pos, node),
-- Function triggered for each qualifying node.
} }
Tile definition Tile definition
@ -7718,32 +7720,40 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
`minetest.register_tool`. `minetest.register_tool`.
{ {
description = "Steel Axe", description = "",
-- Can contain new lines. "\n" has to be used as new line character. -- Can contain new lines. "\n" has to be used as new line character.
-- See also: `get_description` in [`ItemStack`] -- See also: `get_description` in [`ItemStack`]
short_description = "Steel Axe", short_description = "",
-- Must not contain new lines. -- Must not contain new lines.
-- Defaults to nil. -- Defaults to nil.
-- Use an [`ItemStack`] to get the short description, eg: -- Use an [`ItemStack`] to get the short description, e.g.:
-- ItemStack(itemname):get_short_description() -- ItemStack(itemname):get_short_description()
groups = {}, groups = {},
-- key = name, value = rating; rating = 1..3. -- key = name, value = rating; rating = <number>.
-- If rating not applicable, use 1. -- If rating not applicable, use 1.
-- e.g. {wool = 1, fluffy = 3} -- e.g. {wool = 1, fluffy = 3}
-- {soil = 2, outerspace = 1, crumbly = 1} -- {soil = 2, outerspace = 1, crumbly = 1}
-- {bendy = 2, snappy = 1}, -- {bendy = 2, snappy = 1},
-- {hard = 1, metal = 1, spikes = 1} -- {hard = 1, metal = 1, spikes = 1}
inventory_image = "default_tool_steelaxe.png", inventory_image = "",
-- Texture shown in the inventory GUI
-- Defaults to a 3D rendering of the node if left empty.
inventory_overlay = "overlay.png", inventory_overlay = "",
-- An overlay which does not get colorized -- An overlay texture which is not affected by colorization
wield_image = "", wield_image = "",
-- Texture shown when item is held in hand
-- Defaults to a 3D rendering of the node if left empty.
wield_overlay = "", wield_overlay = "",
-- Like inventory_overlay but only used in the same situation as wield_image
wield_scale = {x = 1, y = 1, z = 1},
-- Scale for the item when held in hand
palette = "", palette = "",
-- An image file containing the palette of a node. -- An image file containing the palette of a node.
@ -7752,19 +7762,18 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
-- The palette is always stretched to fit indices between 0 and 255, to -- The palette is always stretched to fit indices between 0 and 255, to
-- ensure compatibility with "colorfacedir" and "colorwallmounted" nodes. -- ensure compatibility with "colorfacedir" and "colorwallmounted" nodes.
color = "0xFFFFFFFF", color = "#ffffffff",
-- The color of the item. The palette overrides this. -- Color the item is colorized with. The palette overrides this.
wield_scale = {x = 1, y = 1, z = 1},
-- The default value of 99 may be configured by
-- users using the setting "default_stack_max"
stack_max = 99, stack_max = 99,
-- Maximum amount of items that can be in a single stack.
-- The default can be changed by the setting `default_stack_max`
range = 4.0, range = 4.0,
-- Range of node and object pointing that is possible with this item held
liquids_pointable = false, liquids_pointable = false,
-- If true, item points to all liquid nodes (`liquidtype ~= "none"`), -- If true, item can point to all liquid nodes (`liquidtype ~= "none"`),
-- even those for which `pointable = false` -- even those for which `pointable = false`
light_source = 0, light_source = 0,
@ -7780,8 +7789,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
max_drop_level = 0, max_drop_level = 0,
groupcaps = { groupcaps = {
-- For example: -- For example:
choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2},
uses = 20, maxlevel = 2},
}, },
damage_groups = {groupname = damage}, damage_groups = {groupname = damage},
-- Damage values must be between -32768 and 32767 (2^15) -- Damage values must be between -32768 and 32767 (2^15)
@ -7801,16 +7809,16 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
-- If "" and item is anything, no prediction is made. -- If "" and item is anything, no prediction is made.
-- Otherwise should be name of node which the client immediately places -- Otherwise should be name of node which the client immediately places
-- on ground when the player places the item. Server will always update -- on ground when the player places the item. Server will always update
-- actual result to client in a short moment. -- with actual result shortly.
node_dig_prediction = "air", node_dig_prediction = "air",
-- if "", no prediction is made. -- if "", no prediction is made.
-- if "air", node is removed. -- if "air", node is removed.
-- Otherwise should be name of node which the client immediately places -- Otherwise should be name of node which the client immediately places
-- upon digging. Server will always update actual result shortly. -- upon digging. Server will always update with actual result shortly.
sound = { sound = {
-- Definition of items sounds to be played at various events. -- Definition of item sounds to be played at various events.
-- All fields in this table are optional. -- All fields in this table are optional.
breaks = <SimpleSoundSpec>, breaks = <SimpleSoundSpec>,
@ -7873,7 +7881,7 @@ Node definition
Used by `minetest.register_node`. Used by `minetest.register_node`.
{ {
-- <all fields allowed in item definitions>, -- <all fields allowed in item definitions>
drawtype = "normal", -- See "Node drawtypes" drawtype = "normal", -- See "Node drawtypes"
@ -7920,21 +7928,22 @@ Used by `minetest.register_node`.
-- If set to a boolean value (deprecated): true either sets it to blend -- If set to a boolean value (deprecated): true either sets it to blend
-- or clip, false sets it to clip or opaque mode depending on the drawtype. -- or clip, false sets it to clip or opaque mode depending on the drawtype.
palette = "palette.png", palette = "",
-- The node's `param2` is used to select a pixel from the image. -- The node's `param2` is used to select a pixel from the image.
-- Pixels are arranged from left to right and from top to bottom. -- Pixels are arranged from left to right and from top to bottom.
-- The node's color will be multiplied with the selected pixel's color. -- The node's color will be multiplied with the selected pixel's color.
-- Tiles can override this behavior. -- Tiles can override this behavior.
-- Only when `paramtype2` supports palettes. -- Only when `paramtype2` supports palettes.
post_effect_color = "green#0F", post_effect_color = "#00000000",
-- Screen tint if player is inside node, see "ColorSpec" -- Screen tint if player is inside node, see "ColorSpec"
paramtype = "none", -- See "Nodes" paramtype = "none", -- See "Nodes"
paramtype2 = "none", -- See "Nodes" paramtype2 = "none", -- See "Nodes"
place_param2 = nil, -- Force value for param2 when player places node place_param2 = 0,
-- Value for param2 that is set when player places node
is_ground_content = true, is_ground_content = true,
-- If false, the cave generator and dungeon generator will not carve -- If false, the cave generator and dungeon generator will not carve
@ -7952,7 +7961,7 @@ Used by `minetest.register_node`.
diggable = true, -- If false, can never be dug diggable = true, -- If false, can never be dug
climbable = false, -- If true, can be climbed on (ladder) climbable = false, -- If true, can be climbed on like a ladder
move_resistance = 0, move_resistance = 0,
-- Slows down movement of players through this node (max. 7). -- Slows down movement of players through this node (max. 7).
@ -7978,9 +7987,11 @@ Used by `minetest.register_node`.
-- If it's "source" or "flowing" and `liquid_range > 0`, then -- If it's "source" or "flowing" and `liquid_range > 0`, then
-- both `liquid_alternative_*` fields must be specified -- both `liquid_alternative_*` fields must be specified
liquid_alternative_flowing = "", -- Flowing version of source liquid liquid_alternative_flowing = "",
-- Node that represents the flowing version of the liquid
liquid_alternative_source = "", -- Source version of flowing liquid liquid_alternative_source = "",
-- Node that represents the source version of the liquid
liquid_viscosity = 0, liquid_viscosity = 0,
-- Controls speed at which the liquid spreads/flows (max. 7). -- Controls speed at which the liquid spreads/flows (max. 7).
@ -8000,7 +8011,6 @@ Used by `minetest.register_node`.
-- settings apply. -- settings apply.
-- * nil: Will be treated as true if `liquidype ~= "none"` -- * nil: Will be treated as true if `liquidype ~= "none"`
-- and as false otherwise. -- and as false otherwise.
-- Default: nil
leveled = 0, leveled = 0,
-- Only valid for "nodebox" drawtype with 'type = "leveled"'. -- Only valid for "nodebox" drawtype with 'type = "leveled"'.
@ -8024,37 +8034,29 @@ Used by `minetest.register_node`.
damage_per_second = 0, damage_per_second = 0,
-- If player is inside node, this damage is caused -- If player is inside node, this damage is caused
node_box = {type="regular"}, -- See "Node boxes" node_box = {type = "regular"}, -- See "Node boxes"
connects_to = nodenames, connects_to = {},
-- Used for nodebox nodes with the type == "connected". -- Used for nodebox nodes with the type == "connected".
-- Specifies to what neighboring nodes connections will be drawn. -- Specifies to what neighboring nodes connections will be drawn.
-- e.g. `{"group:fence", "default:wood"}` or `"default:stone"` -- e.g. `{"group:fence", "default:wood"}` or `"default:stone"`
connect_sides = { "top", "bottom", "front", "left", "back", "right" }, connect_sides = {},
-- Tells connected nodebox nodes to connect only to these sides of this -- Tells connected nodebox nodes to connect only to these sides of this
-- node -- node. possible: "top", "bottom", "front", "left", "back", "right"
mesh = "model.obj", mesh = "",
-- File name of mesh when using "mesh" drawtype -- File name of mesh when using "mesh" drawtype
selection_box = { selection_box = {
type = "fixed", -- see [Node boxes] for possibilities
fixed = {
{-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16},
-- Node box format: see [Node boxes]
},
}, },
-- Custom selection box definition. Multiple boxes can be defined. -- Custom selection box definition. Multiple boxes can be defined.
-- If "nodebox" drawtype is used and selection_box is nil, then node_box -- If "nodebox" drawtype is used and selection_box is nil, then node_box
-- definition is used for the selection box. -- definition is used for the selection box.
collision_box = { collision_box = {
type = "fixed", -- see [Node boxes] for possibilities
fixed = {
{-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16},
-- Node box format: see [Node boxes]
},
}, },
-- Custom collision box definition. Multiple boxes can be defined. -- Custom collision box definition. Multiple boxes can be defined.
-- If "nodebox" drawtype is used and collision_box is nil, then node_box -- If "nodebox" drawtype is used and collision_box is nil, then node_box
@ -8111,8 +8113,8 @@ Used by `minetest.register_node`.
drop = "", drop = "",
-- Name of dropped item when dug. -- Name of dropped item when dug.
-- Default dropped item is the node itself. -- Default dropped item is the node itself.
-- Using a table allows multiple items, drop chances and item filtering.
-- Item filtering by string matching is deprecated. -- Using a table allows multiple items, drop chances and item filtering:
drop = { drop = {
max_items = 1, max_items = 1,
-- Maximum number of item lists to drop. -- Maximum number of item lists to drop.
@ -8123,7 +8125,7 @@ Used by `minetest.register_node`.
-- equals 'max_items'. -- equals 'max_items'.
-- Therefore, entries should progress from low to high drop chance. -- Therefore, entries should progress from low to high drop chance.
items = { items = {
-- Entry examples. -- Examples:
{ {
-- 1 in 1000 chance of dropping a diamond. -- 1 in 1000 chance of dropping a diamond.
-- Default rarity is '1'. -- Default rarity is '1'.
@ -8279,8 +8281,8 @@ Used by `minetest.register_node`.
mod_origin = "modname", mod_origin = "modname",
-- stores which mod actually registered a node -- stores which mod actually registered a node
-- if it can not find a source, returns "??" -- If the source could not be determined it contains "??"
-- useful for getting what mod truly registered something -- Useful for getting which mod truly registered something
-- example: if a node is registered as ":othermodname:nodename", -- example: if a node is registered as ":othermodname:nodename",
-- nodename will show "othermodname", but mod_orgin will say "modname" -- nodename will show "othermodname", but mod_orgin will say "modname"
} }
@ -8333,7 +8335,7 @@ you want `additional_wear` to be negative.
The formula used to calculate the resulting wear is: The formula used to calculate the resulting wear is:
65536 - ( (65536 - tool_1_wear) + (65536 - tool_2_wear) + 65536 * additional_wear ) 65536 * (1 - ( (1 - tool_1_wear) + (1 - tool_2_wear) + additional_wear ))
The result is rounded and can't be lower than 0. If the result is 65536 or higher, The result is rounded and can't be lower than 0. If the result is 65536 or higher,
no crafting is possible. no crafting is possible.
@ -8356,6 +8358,10 @@ no crafting is possible.
replacements = {{"bucket:bucket_lava", "bucket:bucket_empty"}}, replacements = {{"bucket:bucket_lava", "bucket:bucket_empty"}},
} }
The engine does not implement anything specific to cooking or fuels, but the
recpies can be retrieved later using `minetest.get_craft_result` to have a
consistent interface across different games/mods.
Ore definition Ore definition
-------------- --------------
@ -8364,15 +8370,17 @@ Used by `minetest.register_ore`.
See [Ores] section above for essential information. See [Ores] section above for essential information.
{ {
ore_type = "scatter", ore_type = "",
-- Supported: "scatter", "sheet", "puff", "blob", "vein", "stratum"
ore = "default:stone_with_coal", ore = "",
-- Ore node to place
ore_param2 = 3, ore_param2 = 0,
-- Facedir rotation. Default is 0 (unchanged rotation) -- Param2 to set for ore (e.g. facedir rotation)
wherein = "default:stone", wherein = "",
-- A list of nodenames is supported too -- Node to place ore in. Multiple are possible by passing a list.
clust_scarcity = 8 * 8 * 8, clust_scarcity = 8 * 8 * 8,
-- Ore has a 1 out of clust_scarcity chance of spawning in a node. -- Ore has a 1 out of clust_scarcity chance of spawning in a node.
@ -8388,13 +8396,13 @@ See [Ores] section above for essential information.
-- nodes are coal ore. -- nodes are coal ore.
y_min = -31000, y_min = -31000,
y_max = 64, y_max = 31000,
-- Lower and upper limits for ore -- Lower and upper limits for ore (inclusive)
flags = "", flags = "",
-- Attributes for the ore generation, see 'Ore attributes' section above -- Attributes for the ore generation, see 'Ore attributes' section above
noise_threshold = 0.5, noise_threshold = 0,
-- If noise is above this threshold, ore is placed. Not needed for a -- If noise is above this threshold, ore is placed. Not needed for a
-- uniform distribution. -- uniform distribution.
@ -8421,12 +8429,12 @@ See [Ores] section above for essential information.
-- Type-specific parameters -- Type-specific parameters
-- sheet -- "sheet"
column_height_min = 1, column_height_min = 1,
column_height_max = 16, column_height_max = 16,
column_midpoint_factor = 0.5, column_midpoint_factor = 0.5,
-- puff -- "puff"
np_puff_top = { np_puff_top = {
offset = 4, offset = 4,
scale = 2, scale = 2,
@ -8444,10 +8452,10 @@ See [Ores] section above for essential information.
persistence = 0.7 persistence = 0.7
}, },
-- vein -- "vein"
random_factor = 1.0, random_factor = 1.0,
-- stratum -- "stratum"
np_stratum_thickness = { np_stratum_thickness = {
offset = 8, offset = 8,
scale = 4, scale = 4,
@ -8456,7 +8464,7 @@ See [Ores] section above for essential information.
octaves = 3, octaves = 3,
persistence = 0.7 persistence = 0.7
}, },
stratum_thickness = 8, stratum_thickness = 8, -- only used if no noise defined
} }
Biome definition Biome definition
@ -8559,12 +8567,13 @@ See [Decoration types]. Used by `minetest.register_decoration`.
{ {
deco_type = "simple", deco_type = "simple",
-- Type. "simple" or "schematic" supported
place_on = "default:dirt_with_grass", place_on = "default:dirt_with_grass",
-- Node (or list of nodes) that the decoration can be placed on -- Node (or list of nodes) that the decoration can be placed on
sidelen = 8, sidelen = 8,
-- Size of the square divisions of the mapchunk being generated. -- Size of the square (X / Z) divisions of the mapchunk being generated.
-- Determines the resolution of noise variation if used. -- Determines the resolution of noise variation if used.
-- If the chunk size is not evenly divisible by sidelen, sidelen is made -- If the chunk size is not evenly divisible by sidelen, sidelen is made
-- equal to the chunk size. -- equal to the chunk size.
@ -8600,7 +8609,7 @@ See [Decoration types]. Used by `minetest.register_decoration`.
y_min = -31000, y_min = -31000,
y_max = 31000, y_max = 31000,
-- Lower and upper limits for decoration. -- Lower and upper limits for decoration (inclusive).
-- These parameters refer to the Y co-ordinate of the 'place_on' node. -- These parameters refer to the Y co-ordinate of the 'place_on' node.
spawn_by = "default:water", spawn_by = "default:water",
@ -8690,6 +8699,7 @@ See [Decoration types]. Used by `minetest.register_decoration`.
-- See 'Schematic specifier' for details. -- See 'Schematic specifier' for details.
replacements = {["oldname"] = "convert_to", ...}, replacements = {["oldname"] = "convert_to", ...},
-- Map of node names to replace in the schematic after reading it.
flags = "place_center_x, place_center_y, place_center_z", flags = "place_center_x, place_center_y, place_center_z",
-- Flags for schematic decorations. See 'Schematic attributes'. -- Flags for schematic decorations. See 'Schematic attributes'.