-Minetest Lua Modding API Reference 0.4.16
+Minetest Lua Modding API Reference 0.5.0
=========================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
files are automatically transferred to the client.
If you see a deficiency in the API, feel free to attempt to add the
-functionality in the engine and API. You can send such improvements as
-source code patches to <celeron55@gmail.com>.
+functionality in the engine and API.
Programming in Lua
------------------
| | `-- modname_something_else.png
| |-- sounds
| |-- media
+ | |-- locale
| `-- <custom data>
`-- another
Media files (textures, sounds, whatever) that will be transferred to the
client and will be available for use by the mod.
+### `locale`
+Translation files for the clients. (See `Translations`)
+
Naming convention for registered textual names
----------------------------------------------
Registered names should generally be in this format:
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).
+To transfer the color to a special drop, you need a drop table.
+Example:
+
+ minetest.register_node("mod:stone", {
+ description = "Stone",
+ tiles = {"default_stone.png"},
+ paramtype2 = "color",
+ palette = "palette.png",
+ drop = {
+ items = {
+ -- assume that mod:cobblestone also has the same palette
+ {items = {"mod:cobblestone"}, inherit_color = true },
+ }
+ }
+ })
### Colored items in craft recipes
Craft recipes only support item strings, but fortunately item strings
tiles with overlays are drawn slower. Using too much overlays might
cause FPS loss.
-To define an overlay, simply set the `overlay_tiles` field of the node
+For inventory and wield images you can specify overlays which
+hardware coloring does not modify. You have to set `inventory_overlay`
+and `wield_overlay` fields to an image name.
+
+To define a node overlay, simply set the `overlay_tiles` field of the node
definition. These tiles are defined in the same way as plain tiles:
they can have a texture name, color etc.
To skip one face, set that overlay tile to an empty string.
* added to `minetest.registered_biome` with the key of `biome.name`
* if `biome.name` is nil, the key is the returned ID
+* `minetest.unregister_biome(name)`
+ * Unregisters the biome name from engine, and deletes the entry with key
+ * `name` from `minetest.registered_biome`
+
* `minetest.register_ore(ore definition)`
* returns an integer uniquely identifying the registered ore
* added to `minetest.registered_ores` with the key of `ore.name`
0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y-
facedir modulo 4 = rotation around that axis
paramtype2 == "leveled"
+ ^ Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted".
+ Leveled nodebox:
+ The level of the top face of the nodebox is stored in param2.
+ The other faces are defined by 'fixed = {}' like 'type = "fixed"' nodeboxes.
+ The nodebox height is (param2 / 64) nodes.
+ The maximum accepted value of param2 is 127.
+ Rooted plantlike:
+ The height of the 'plantlike' section is stored in param2.
+ The height is (param2 / 16) nodes.
paramtype2 == "degrotate"
^ The rotation of this node is stored in param2. Plants are rotated this way.
Values range 0 - 179. The value stored in param2 is multiplied by two to
The palette should have 32 pixels.
paramtype2 == "glasslikeliquidlevel"
^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes.
- param2 defines 64 levels of internal liquid.
+ param2 values 0-63 define 64 levels of internal liquid, 0 being empty and
+ 63 being full.
Liquid texture is defined using `special_tiles = {"modname_tilename.png"},`
Nodes can also contain extra data. See "Node Metadata".
Node drawtypes
----------------
+--------------
There are a bunch of different looking node types.
Look for examples in `games/minimal` or `games/minetest_game`.
* `firelike`
* `fencelike`
* `raillike`
-* `nodebox` -- See below. (**Experimental!**)
-* `mesh` -- use models for nodes
-* `plantlike_rooted`
+* `nodebox` -- See below
+* `mesh` -- Use models for nodes, see below
+* `plantlike_rooted` -- See below
`*_optional` drawtypes need less rendering time if deactivated (always client side).
Node boxes
------------
+----------
Node selection boxes are defined using "node boxes"
-The `nodebox` node drawtype allows defining visual of nodes consisting of
-arbitrary number of boxes. It allows defining stuff like stairs. Only the
-`fixed` and `leveled` box type is supported for these.
-
-Please note that this is still experimental, and may be incompatibly
-changed in the future.
+The `nodebox` node drawtype allows defining nodes consisting of an arbitrary
+number of boxes. It allows defining stuff like stairs and slabs.
A nodebox is defined as any of:
type = "regular"
}
{
- -- A fixed box (facedir param2 is used, if applicable)
+ -- A fixed box (or boxes) (facedir param2 is used, if applicable)
type = "fixed",
fixed = box OR {box1, box2, ...}
}
+ {
+ -- A variable height box (or boxes) with the top face position defined by
+ -- the node parameter 'leveled = ', or if 'paramtype2 == "leveled"' by
+ -- param2.
+ -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'.
+ type = "leveled",
+ fixed = box OR {box1, box2, ...}
+ }
{
-- A box like the selection box for torches
-- (wallmounted param2 is used, if applicable)
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
-`type = "leveled"` is same as `type = "fixed"`, but `y2` will be automatically
-set to level from `param2`.
-
-
Meshes
------
If drawtype `mesh` is used, tiles should hold model materials textures.
Only static meshes are implemented.
For supported model formats see Irrlicht engine documentation.
+Rooted plantlike drawtype
+-------------------------
+The `plantlike_rooted` drawtype was developed to enable underwater plants
+without air bubbles around the plants.
+It consists of a base cube at the co-ordinates of the node (the seabed /
+lakebed / riverbed node) plus a 'plantlike' extension above with a height
+defined by param2 (maximum height 16 nodes). This extension visually passes
+through any nodes above the base cube without affecting them.
+The node is dug by digging the base cube.
+The base cube texture tiles are defined as normal, the plantlike extension
+uses the defined 'special tile', for example:
+`special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},`
Noise Parameters
----------------
The vertical top and bottom displacement of each puff are determined by the noise
parameters `np_puff_top` and `np_puff_bottom`, respectively.
-
### `blob`
Creates a deformed sphere of ore according to 3d perlin noise described by
`noise_params`. The maximum size of the blob is `clust_size`, and
### `vein`
Creates veins of ore varying in density by according to the intersection of two
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_threshold`.
+`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_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:
+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:
noise_params = {
offset = 0,
**WARNING**: Use this ore type *very* sparingly since it is ~200x more
computationally expensive than any other ore.
+### `stratum`
+Creates a single undulating ore stratum that is continuous across mapchunk
+borders and horizontally spans the world.
+
+The 2D perlin noise described by `noise_params` varies the Y co-ordinate of the
+stratum midpoint. The 2D perlin noise described by `np_stratum_thickness`
+varies the stratum's vertical thickness (in units of nodes). Due to being
+continuous across mapchunk borders the stratum's vertical thickness is
+unlimited.
+
+`y_min` and `y_max` define the limits of the ore generation and for performance
+reasons should be set as close together as possible but without clipping the
+stratum's Y variation.
+
+If either of the 2 noise parameters are omitted the ore will occur from y_min
+to y_max in a simple horizontal stratum. As this does not compute noise
+performance improves, and is ideal for placing many layers.
+
+Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a
+solid-ore stratum would require a `clust_scarcity` of 1.
+
+The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and
+`random_factor` are ignored by this ore type.
+
Ore attributes
--------------
See section "Flag Specifier Format".
* `soil`: saplings will grow on nodes in this group
* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
connect to each other
+* `slippery`: Players and items will slide on the node.
+ Slipperiness rises steadily with `slippery` value, starting at 1.
+
### Known damage and digging time defining groups
* `crumbly`: dirt, sand
#### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
* Same as fields above, but with multi-line input
+* if the text overflows a vertical scrollbar is added
+* if the name is empty the textarea is readonly. The label is not displayed then
#### `label[<X>,<Y>;<label>]`
* `x` and `y` work as per field
Helper functions
----------------
-* `dump2(obj, name="_", dumped={})`
- * Return object serialized as a string, handles reference loops
-* `dump(obj, dumped={})`
- * Return object serialized as a string
+* `dump2(obj, name, dumped)`: returns a string which makes `obj` human readable,
+ handles reference loops
+ * `obj`: arbitrary variable
+ * `name`: string, default: `"_"`
+ * `dumped`: table, default: `{}`
+* `dump(obj, dumped)`: returns a string which makes `obj` human readable
+ * `obj`: arbitrary variable
+ * `dumped`: table, default: `{}`
* `math.hypot(x, y)`
* Get the hypotenuse of a triangle with legs x and y.
Useful for distance calculation.
-* `math.sign(x, tolerance)`
+* `math.sign(x, tolerance)`: returns `-1`, `0` or `1`
* Get the sign of a number.
- Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
-* `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
- * If `max_splits` is negative, do not limit splits.
- * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
- * e.g. `string:split("a,b", ",") == {"a","b"}`
-* `string:trim()`
- * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
-* `minetest.wrap_text(str, limit)`: returns a string
- * Adds new lines to the string to keep it within the specified character limit
- * limit: Maximal amount of characters in one line
-* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(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.
+ * tolerance: number, default: `0.0`
+ * If the absolute value of `x` is within the `tolerance` or `x` is NaN,
+ `0` is returned.
+* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)`
+ * `separator`: string, default: `","`
+ * `include_empty`: boolean, default: `false`
+ * `max_splits`: number, if it's positive, splits aren't limited,
+ default: `-1`
+ * `sep_is_pattern`: boolean, it specifies whether separator is a plain
+ string or a pattern (regex), default: `false`
+ * e.g. `"a,b":split","` returns `{"a","b"}`
+* `string:trim()`: returns the string whithout whitespace pre- and suffixes
+ * e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"`
+* `minetest.wrap_text(str, limit, as_table)`: returns a string or table
+ * Adds newlines to the string to keep it within the specified character
+ limit
+ * Note that the returned lines may be longer than the limit since it only
+ splits at word borders.
+ * `limit`: number, maximal amount of characters in one line
+ * `as_table`: boolean, if set to true, a table of lines instead of a string
+ is returned, default: `false`
+* `minetest.pos_to_string(pos, decimal_places)`: returns string `"(X,Y,Z)"`
+ * `pos`: table {x=X, y=Y, z=Z}
+ * Converts the position `pos` to a human-readable, printable string
+ * `decimal_places`: number, if specified, the x, y and z values of
+ the position are rounded to the given decimal place.
+* `minetest.string_to_pos(string)`: returns a position or `nil`
+ * Same but in reverse.
+ * If the string can't be parsed to a position, nothing is returned.
* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
* Converts a string representing an area box into two positions
* `minetest.formspec_escape(string)`: returns a string
* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
* returns the exact position on the surface of a pointed node
+Translations
+------------
+
+Texts can be translated client-side with the help of `minetest.translate` and translation files.
+
+### Translating a string
+Two functions are provided to translate strings: `minetest.translate` and `minetest.get_translator`.
+
+* `minetest.get_translator(textdomain)` is a simple wrapper around `minetest.translate`, and
+ `minetest.get_translator(textdomain)(str, ...)` is equivalent to `minetest.translate(textdomain, str, ...)`.
+ It is intended to be used in the following way, so that it avoids verbose repetitions of `minetest.translate`:
+
+ local S = minetest.get_translator(textdomain)
+ S(str, ...)
+
+ As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead.
+
+* `minetest.translate(textdomain, str, ...)` translates the string `str` with the given `textdomain`
+ for disambiguation. The textdomain must match the textdomain specified in the translation file in order
+ to get the string translated. This can be used so that a string is translated differently in different contexts.
+ It is advised to use the name of the mod as textdomain whenever possible, to avoid clashes with other mods.
+ This function must be given a number of arguments equal to the number of arguments the translated string expects.
+ Arguments are literal strings -- they will not be translated, so if you want them to be, they need to come as
+ outputs of `minetest.translate` as well.
+
+ For instance, suppose we want to translate "@1 Wool" with "@1" being replaced by the translation of "Red".
+ We can do the following:
+
+ local S = minetest.get_translator()
+ S("@1 Wool", S("Red"))
+
+ This will be displayed as "Red Wool" on old clients and on clients that do not have localization enabled.
+ However, if we have for instance a translation file named `wool.fr.tr` containing the following:
+
+ @1 Wool=Laine @1
+ Red=Rouge
+
+ this will be displayed as "Laine Rouge" on clients with a French locale.
+
+### Operations on translated strings
+
+The output of `minetest.translate` is a string, with escape sequences adding additional information to that string
+so that it can be translated on the different clients. In particular, you can't expect operations like string.length
+to work on them like you would expect them to, or string.gsub to work in the expected manner. However, string
+concatenation will still work as expected (note that you should only use this for things like formspecs; do not
+translate sentences by breaking them into parts; arguments should be used instead), and operations such as
+`minetest.colorize` which are only concatenation under the hood as well.
+
+### Translation file format
+A translation file has the suffix `.[lang].tr`, where `[lang]` is the language it corresponds to.
+The file should be a text file, with the following format:
+
+* Lines beginning with `# textdomain:` (the space is significant) can be used to specify the text
+ domain of all following translations in the file.
+* All other empty lines or lines beginning with `#` are ignored.
+* Other lines should be in the format `original=translated`. Both `original` and `translated` can
+ contain escape sequences beginning with `@` to insert arguments, literal `@`, `=` or newline
+ (See ### Escapes below). There must be no extraneous whitespace around the `=` or at the beginning
+ or the end of the line.
+
+### Escapes
+Strings that need to be translated can contain several escapes, preceded by `@`.
+* `@@` acts as a literal `@`.
+* `@n`, where `n` is a digit between 1 and 9, is an argument for the translated string that will be inlined
+ when translation. Due to how translations are implemented, the original translation string **must** have
+ its arguments in increasing order, without gaps or repetitions, starting from 1.
+* `@=` acts as a literal `=`. It is not required in strings given to `minetest.translate`, but is in translation
+ files to avoid begin confused with the `=` separating the original from the translation.
+* `@\n` (where the `\n` is a literal newline) acts as a literal newline. As with `@=`, this escape is not required
+ in strings given to `minetest.translate`, but is in translation files.
+* `@n` acts as a literal newline as well.
+
`minetest` namespace reference
------------------------------
reliable or verifyable. Compatible forks will have a different name and
version entirely. To check for the presence of engine features, test
whether the functions exported by the wanted features exist. For example:
- `if minetest.nodeupdate then ... end`.
+ `if minetest.check_for_falling then ... end`.
### Logging
* `minetest.debug(...)`
* `minetest.register_on_item_eat(func(hp_change, replace_with_item, itemstack, user, pointed_thing))`
* Called when an item is eaten, by `minetest.item_eat`
* Return `true` or `itemstack` to cancel the default item eat response (i.e.: hp increase)
+* `minetest.register_on_priv_grant(function(name, granter, priv))`
+ * Called when `granter` grants the priv `priv` to `name`.
+ * Note that the callback will be called twice if it's done by a player, once with granter being the player name,
+ and again with granter being nil.
+* `minetest.register_on_priv_revoke(function(name, revoker, priv))`
+ * Called when `revoker` revokes the priv `priv` from `name`.
+ * Note that the callback will be called twice if it's done by a player, once with revoker being the player name,
+ and again with revoker being nil.
+* `minetest.register_can_bypass_userlimit(function(name, ip))`
+ * Called when `name` user connects with `ip`.
+ * Return `true` to by pass the player limit
+* `minetest.register_on_modchannel_message(func(channel_name, sender, message))`
+ * Called when an incoming mod channel message is received
+ * You should have joined some channels to receive events.
+ * If message comes from a server mod, `sender` field is an empty string.
### Other registration functions
* `minetest.register_chatcommand(cmd, chatcommand definition)`
* `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
the default of `give_to_singleplayer` is true
* To allow players with `basic_privs` to grant, see `basic_privs` minetest.conf setting.
+ * `on_grant(name, granter_name)`: Called when given to player `name` by `granter_name`.
+ `granter_name` will be nil if the priv was granted by a mod.
+ * `on_revoke(name, revoker_name)`: Called when taken from player `name` by `revoker_name`.
+ `revoker_name` will be nil if the priv was revoked by a mod
+ * Note that the above two callbacks will be called twice if a player is responsible -
+ once with the player name, and then with a nil player name.
+ * Return true in the above callbacks to stop register_on_priv_grant or revoke being called.
* `minetest.register_authentication_handler(handler)`
* See `minetest.builtin_auth_handler` in `builtin.lua` for reference
### Authentication
* `minetest.notify_authentication_modified(name)`
* Should be called by the authentication handler if privileges changes.
- * To report everybody, set `name=nil`.
+ * `name`: string, if ommited, everybody is reported
* `minetest.check_password_entry(name, entry, password)`
* Returns true if the "db entry" for a player with name matches given
* password, false otherwise.
### Environment access
* `minetest.set_node(pos, node)`
-* `minetest.add_node(pos, node): alias set_node(pos, node)`
- * Set node at position (`node = {name="foo", param1=0, param2=0}`)
+* `minetest.add_node(pos, node): alias to `minetest.set_node`
+ * Set node at position `pos`
+ * `node`: table `{name=string, param1=number, param2=number}`
+ * If param1 or param2 is omitted, it's set to `0`.
+ * e.g. `minetest.set_node({x=0, y=10, z=0}, {name="default:wood"})`
* `minetest.swap_node(pos, node)`
* Set node at position, but don't remove metadata
* `minetest.remove_node(pos)`
- * Equivalent to `set_node(pos, "air")`
+ * By default it does the same as `minetest.set_node(pos, {name="air"})`
* `minetest.get_node(pos)`
* 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}`
* `minetest.add_item(pos, item)`: Spawn item
* Returns `ObjectRef`, or `nil` if failed
* `minetest.get_player_by_name(name)`: Get an `ObjectRef` to a player
-* `minetest.get_objects_inside_radius(pos, radius)`
+* `minetest.get_objects_inside_radius(pos, radius)`: returns a list of ObjectRefs
* `radius`: using an euclidean metric
* `minetest.set_timeofday(val)`
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
* spread these updates to neighbours and can cause a cascade
of nodes to fall.
+### Mod channels
+You can find mod channels communication scheme in `docs/mod_channels.png`.
+
+* `minetest.mod_channel_join(channel_name)`
+ * Server joins channel `channel_name`, and creates it if necessary. You
+ should listen from incoming messages with `minetest.register_on_modchannel_message`
+ call to receive incoming messages
+
### Inventory
`minetest.get_inventory(location)`: returns an `InvRef`
* Convert a vector into a yaw (angle)
* `minetest.yaw_to_dir(yaw)`
* Convert yaw (angle) to a vector
+* `minetest.is_colored_paramtype(ptype)`
+ * Returns a boolean. Returns `true` if the given `paramtype2` contains color
+ information (`color`, `colorwallmounted` or `colorfacedir`).
+* `minetest.strip_param2_color(param2, paramtype2)`
+ * Removes everything but the color information from the
+ given `param2` value.
+ * Returns `nil` if the given `paramtype2` does not contain color information
* `minetest.get_node_drops(nodename, toolname)`
* Returns list of item names.
* **Note**: This will be removed or modified in a future version.
### Schematics
* `minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)`
* Create a schematic from the volume of map specified by the box formed by p1 and p2.
- * Apply the specified probability values to the specified nodes in `probability_list`.
+ * Apply the specified probability and per-node force-place to the specified nodes
+ according to the `probability_list`.
* `probability_list` is an array of tables containing two fields, `pos` and `prob`.
* `pos` is the 3D vector specifying the absolute coordinates of the
node being modified,
- * `prob` is the integer value from `0` to `255` of the probability (see: Schematic specifier).
+ * `prob` is an integer value from `0` to `255` that encodes probability and
+ per-node force-place. Probability has levels 0-127, then 128 is added to
+ encode per-node force-place.
+ For probability stated as 0-255, divide by 2 and round down to get values
+ 0-127, then add 128 to apply per-node force-place.
* If there are two or more entries with the same pos value, the
last entry is used.
* If `pos` is not inside the box formed by `p1` and `p2`, it is ignored.
* If `probability_list` equals `nil`, no probabilities are applied.
- * Slice probability works in the same manner, except takes a field
- called `ypos` instead which
- indicates the y position of the slice with a probability applied.
+ * Apply the specified probability to the specified horizontal slices according to the
+ `slice_prob_list`.
+ * `slice_prob_list` is an array of tables containing two fields, `ypos` and `prob`.
+ * `ypos` indicates the y position of the slice with a probability applied,
+ the lowest slice being `ypos = 0`.
* If slice probability list equals `nil`, no slice probabilities are applied.
* Saves schematic in the Minetest Schematic format to filename.
* Replaces definition of a builtin hud element
* `name`: `"breath"` or `"health"`
* `hud_definition`: definition to replace builtin definition
-* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
+* `minetest.send_join_message(player_name)`
+ * This function can be overridden by mods to change the join message.
+* `minetest.send_leave_message(player_name, timed_out)`
+ * This function can be overridden by mods to change the leave message.
+* `minetest.hash_node_position(pos)`: returns an 48-bit integer
+ * `pos`: table {x=number, y=number, z=number},
* Gives a unique hash number for a node position (16+16+16=48bit)
* `minetest.get_position_from_hash(hash)`: returns a position
* Inverse transform of `minetest.hash_node_position`
Class reference
---------------
+### ModChannel
+
+An interface to use mod channels on client and server
+
+#### Methods
+* `leave()`: leave the mod channel.
+ * Server leaves channel `channel_name`.
+ * No more incoming or outgoing messages can be sent to this channel from server mods.
+ * This invalidate all future object usage
+ * Ensure your set mod_channel to nil after that to free Lua resources
+* `is_writeable()`: returns true if channel is writeable and mod can send over it.
+* `send_all(message)`: Send `message` though the mod channel.
+ * If mod channel is not writeable or invalid, message will be dropped.
+ * Message size is limited to 65535 characters by protocol.
+
### `MetaDataRef`
See `StorageRef`, `NodeMetaRef` and `ItemStackMetaRef`.
* `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, frame_loop=true)`
+* `set_animation(frame_range, frame_speed, frame_blend, frame_loop)`
+ * `frame_range`: table {x=num, y=num}, default: `{x=1, y=1}`
+ * `frame_speed`: number, default: `15.0`
+ * `frame_blend`: number, default: `0.0`
+ * `frame_loop`: boolean, default: `true`
* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and `frame_loop`
+* `set_animation_frame_speed(frame_speed)`
+ * `frame_speed`: number, default: `15.0`
* `set_attach(parent, bone, position, rotation)`
* `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative)
- * `rotation`: `{x=num, y=num, z=num}`
+ * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees
* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't attached
* `set_detach()`
* `set_bone_position(bone, position, rotation)`
}
##### LuaEntitySAO-only (no-op for other objects)
-* `set_velocity({x=num, y=num, z=num})`
-* `get_velocity()`: returns `{x=num, y=num, z=num}`
-* `set_acceleration({x=num, y=num, z=num})`
-* `get_acceleration()`: returns `{x=num, y=num, z=num}`
+* `set_velocity(vel)`
+ * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
+* `get_velocity()`: returns the velocity, a vector
+* `set_acceleration(acc)`
+ * `acc` is a vector
+* `get_acceleration()`: returns the acceleration, a vector
* `set_yaw(radians)`
* `get_yaw()`: returns number in radians
* `set_texture_mod(mod)`
* `get_texture_mod()` returns current texture modifier
-* `set_sprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
- select_horiz_by_yawpitch=false)`
- * Select sprite from spritesheet with optional animation and DM-style
- texture selection based on yaw relative to camera
+* `set_sprite(p, num_frames, framelength, select_horiz_by_yawpitch)`
+ * Select sprite from spritesheet with optional animation and Dungeon Master
+ style texture selection based on yaw relative to camera
+ * `p`: {x=number, y=number}, the coordinate of the first frame
+ (x: column, y: row), default: `{x=0, y=0}`
+ * `num_frames`: number, default: `1`
+ * `framelength`: number, default: `0.2`
+ * `select_horiz_by_yawpitch`: boolean, this was once used for the Dungeon
+ Master mob, default: `false`
* `get_entity_name()` (**Deprecated**: Will be removed in a future version)
* `get_luaentity()`
* `get_breath()`: returns players breath
* `set_breath(value)`: sets players breath
* values:
- * `0`: player is drowning,
- * `1`-`10`: remaining number of bubbles
- * `11`: bubbles bar is not shown
+ * `0`: player is drowning
+ * max: bubbles bar is not shown
+ * See Object Properties for more information
* `set_attribute(attribute, value)`:
* Sets an extra attribute with value on player.
* `value` must be a string.
* Should usually be called in `on_joinplayer`
* `get_inventory_formspec()`: returns a formspec string
* `get_player_control()`: returns table with player pressed keys
- * `{jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}`
+ * The table consists of fields with boolean value representing the pressed
+ keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down and up
+ * example: `{jump=false, right=true, left=false, LMB=false, RMB=false,
+ sneak=true, aux1=false, down=false, up=false}`
* `get_player_control_bits()`: returns integer with bit packed player pressed keys
- * bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB
+ * bit nr/meaning: 0/up, 1/down, 2/left, 3/right, 4/jump, 5/aux1, 6/sneak,
+ 7/LMB, 8/RMB
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
* 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`, `minimap`
+ * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`, `breathbar`,
+ `minimap`, `minimap_radar`
* 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
+ * minimap `radar` is only usable when `minimap` is true
* `hud_get_flags()`: returns a table containing status of hud flags
- * returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true, minimap=true }`
+ * returns `{hotbar=true, healthbar=true, crosshair=true, wielditem=true,
+ breathbar=true, minimap=true, minimap_radar=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
an itemstring, a table or `nil`.
#### Methods
-* `is_empty()`: Returns `true` if stack is empty.
-* `get_name()`: Returns item name (e.g. `"default:stone"`).
-* `set_name(item_name)`: Returns boolean whether item was cleared
+* `is_empty()`: returns `true` if stack is empty.
+* `get_name()`: returns item name (e.g. `"default:stone"`).
+* `set_name(item_name)`: returns a boolean indicating whether the item was cleared
* `get_count()`: Returns number of items on the stack.
-* `set_count(count)`: Returns boolean whether item was cleared
-* `get_wear()`: Returns tool wear (`0`-`65535`), `0` for non-tools.
-* `set_wear(wear)`: Returns boolean whether item was cleared
-* `get_meta()`: Returns ItemStackMetaRef. See section for more details
+* `set_count(count)`: returns a boolean indicating whether the item was cleared
+ * `count`: number, unsigned 16 bit integer
+* `get_wear()`: returns tool wear (`0`-`65535`), `0` for non-tools.
+* `set_wear(wear)`: returns boolean indicating whether item was cleared
+ * `wear`: number, unsigned 16 bit integer
+* `get_meta()`: returns ItemStackMetaRef. See section for more details
* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true.
* `clear()`: removes all items from the stack, making it empty.
* `replace(item)`: replace the contents of this stack.
* `item` can also be an itemstring or table.
-* `to_string()`: Returns the stack in itemstring form.
-* `to_table()`: Returns the stack in Lua table form.
-* `get_stack_max()`: Returns the maximum size of the stack (depends on the item).
-* `get_free_space()`: Returns `get_stack_max() - get_count()`.
-* `is_known()`: Returns `true` if the item name refers to a defined item type.
-* `get_definition()`: Returns the item definition table.
-* `get_tool_capabilities()`: Returns the digging properties of the item,
- or those of the hand if none are defined for this item type
-* `add_wear(amount)`: Increases wear by `amount` if the item is a tool.
-* `add_item(item)`: Put some item or stack onto this stack.
- Returns leftover `ItemStack`.
-* `item_fits(item)`: Returns `true` if item or stack can be fully added to
- this one.
-* `take_item(n=1)`: Take (and remove) up to `n` items from this stack.
- Returns taken `ItemStack`.
-* `peek_item(n=1)`: copy (don't remove) up to `n` items from this stack.
- Returns taken `ItemStack`.
+* `to_string()`: returns the stack in itemstring form.
+* `to_table()`: returns the stack in Lua table form.
+* `get_stack_max()`: returns the maximum size of the stack (depends on the item).
+* `get_free_space()`: returns `get_stack_max() - get_count()`.
+* `is_known()`: returns `true` if the item name refers to a defined item type.
+* `get_definition()`: returns the item definition table.
+* `get_tool_capabilities()`: returns the digging properties of the item,
+ or those of the hand if none are defined for this item type
+* `add_wear(amount)`
+ * Increases wear by `amount` if the item is a tool
+ * `amount`: number, integer
+* `add_item(item)`: returns leftover `ItemStack`
+ * Put some item or stack onto this stack
+* `item_fits(item)`: returns `true` if item or stack can be fully added to
+ this one.
+* `take_item(n)`: returns taken `ItemStack`
+ * Take (and remove) up to `n` items from this stack
+ * `n`: number, default: `1`
+* `peek_item(n)`: returns taken `ItemStack`
+ * Copy (don't remove) up to `n` items from this stack
+ * `n`: number, default: `1`
### `PseudoRandom`
A 16-bit pseudorandom number generator.
* `tool_capabilities`: capability table of used tool (can be `nil`)
* `dir`: unit vector of direction of punch. Always defined. Points from
the puncher to the punched.
+ `on_death(self, killer)`
+ * Called when the object dies.
+ * `killer`: an `ObjectRef` (can be `nil`)
* `on_rightclick(self, clicker)`
* `get_staticdata(self)`
* Should return a string that will be passed to `on_activate` when
{
hp_max = 1,
+ -- ^ For players: Defaults to `minetest.PLAYER_MAX_HP_DEFAULT`
+ breath_max = 0,
+ -- ^ For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`
+ can_zoom = true,
+ -- ^ For players only. Enables the zoom feature. Defaults to true
physical = true,
collide_with_objects = true, -- collide with other objects if physical = true
weight = 5,
collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
+ selectionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
+ -- ^ Default, uses collision box dimensions when not set
+ pointable = true, -- overrides selection box when false
visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem",
visual_size = {x = 1, y = 1},
mesh = "model",
-- ^ Limit automatic rotation to this value in degrees per second,
-- value < 0 no limit.
backface_culling = true, -- false to disable backface_culling for model
+ glow = 0,
+ -- ^ Add this much extra lighting when calculating texture color.
+ value < 0 disables light's effect on texture color.
+ For faking self-lighting, UI style entities, or programmatic coloring in mods.
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
+ static_save = true,
+ -- ^ If false, never save this object statically. It will simply be deleted when the block gets unloaded.
+ -- ^ The get_staticdata() callback is never called then.
+ -- ^ Defaults to 'true'
}
### Entity definition (`register_entity`)
{bendy = 2, snappy = 1},
{hard = 1, metal = 1, spikes = 1}
inventory_image = "default_tool_steelaxe.png",
+ inventory_overlay = "overlay.png", -- an overlay which does not get colorized
wield_image = "",
+ wield_overlay = "",
palette = "",
--[[
^ An image file containing the palette of a node.
on ground when the player places the item. Server will always update
actual result to client in a short moment.
]]
+ node_dig_prediction = "air",
+ --[[
+ ^ if "", no prediction is made
+ ^ if "air", node is removed
+ ^ Otherwise should be name of node which the client immediately places
+ upon digging. Server will always update actual result shortly.
+ ]]
sound = {
breaks = "default_tool_break", -- tools only
place = --[[<SimpleSoundSpec>]],
^ base tiles. You can use this to colorize only specific parts of
^ your texture. If the texture name is an empty string, that
^ overlay is not drawn. Since such tiles are drawn twice, it
- ^ is not recommended to use overlays on very common nodes.
+ ^ is not recommended to use overlays on very common nodes. ]]
special_tiles = {tile definition 1, Tile definition 2}, --[[
^ Special textures of node; used rarely (old field name: special_materials)
^ List can be shortened to needed length ]]
liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
liquid_renewable = true, --[[
^ If true, a new liquid source can be created by placing two or more sources nearby ]]
- leveled = 0, --[[
- ^ Block contains level in param2. Value is default level, used for snow.
- ^ Don't forget to use "leveled" type nodebox. ]]
+ leveled = 16, --[[
+ ^ Only valid for "nodebox" drawtype with 'type = "leveled"'.
+ ^ Allows defining the nodebox height without using param2.
+ ^ The nodebox height is 'leveled' / 64 nodes.
+ ^ The maximum value of 'leveled' is 127. ]]
liquid_range = 8, -- number of flowing nodes around source (max. 8)
drowning = 0, -- Player will take this amount of damage if no bubbles are left
light_source = 0, --[[
{
items = {"foo:bar", "baz:frob"}, -- Items to drop.
rarity = 1, -- Probability of dropping is 1 / rarity.
+ inherit_color = true, -- To inherit palette color from the node
},
},
},
^ By default: Calls minetest.register_on_punchnode callbacks ]]
on_rightclick = func(pos, node, clicker, itemstack, pointed_thing), --[[
^ default: nil
- ^ if defined, itemstack will hold clicker's wielded item
+ ^ itemstack will hold clicker's wielded item
^ Shall return the leftover itemstack
- ^ Note: pointed_thing can be nil, if a mod calls this function ]]
+ ^ Note: pointed_thing can be nil, if a mod calls this function
+ This function does not get triggered by clients <=0.4.16 if the
+ "formspec" node metadata field is set ]]
on_dig = func(pos, node, digger), --[[
^ default: minetest.node_dig
{
ore_type = "scatter", -- See "Ore types"
ore = "default:stone_with_coal",
+ ore_param2 = 3,
+ -- ^ Facedir rotation. Default is 0 (unchanged rotation)
wherein = "default:stone",
-- ^ a list of nodenames is supported too
clust_scarcity = 8*8*8,
-- ^ Number of ores in a cluster
clust_size = 3,
-- ^ Size of the bounding box of the cluster
- -- ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore
+ -- ^ 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,
- -- ^ 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.
- -- ^ Needed for sheet ore_type. Omit from scatter ore_type for a uniform ore distribution
+ -- ^ 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.7
+ },
+ -- ^ NoiseParams structure describing one of the perlin noises used for ore
+ -- ^ distribution.
+ -- ^ Omit from "scatter" ore for a uniform ore distribution.
+ -- ^ Omit from "stratum ore for a simple horizontal strata from y_min to y_max.
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.
-- ^ 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,
- -- ^ and ignored if the Mapgen being used does not support biomes.
+ -- ^ List of biomes in which this decoration occurs.
+ -- ^ Occurs in all biomes if this is omitted, and ignored if the Mapgen being
+ -- ^ used does not support biomes.
-- ^ Can be a list of (or a single) biome names, IDs, or definitions.
}
### Biome definition (`register_biome`)
-**Note**
-The Biome API is still in an experimental phase and subject to change.
-
{
name = "tundra",
node_dust = "default:snow",
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
- -- ^ top and at each of these surfaces:
- -- ^ Ground below air, water below air, ground below water.
- -- ^ The selected biome then stays in effect for all nodes below until
- -- ^ column base or the next biome recalculation.
heat_point = 0,
humidity_point = 50,
-- ^ Characteristic average temperature and humidity for the biome.
y_min = -31000
y_max = 31000
-- ^ 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",
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
rotation = "90" -- rotate schematic 90 degrees on placement
-- ^ Rotation can be "0", "90", "180", "270", or "random".
+ place_offset_y = 0,
+ -- ^ Y offset of the schematic base node layer relative to the 'place_on'
+ -- ^ node.
+ -- ^ Can be positive or negative. Default is 0.
+ -- ^ If the flag 'place_center_y' is set this parameter is ignored.
+ -- ^ If absent or 0 the schematic base node layer will be placed level
+ -- ^ with the 'place_on' node.
}
### Chat command definition (`register_chatcommand`)
projects / oweals / minetest.git / blobdiff