mirror of
https://github.com/minetest/minetest.git
synced 2024-09-12 00:26:50 +02:00
Introduces two functions to unregister and override chatcommands. minetest.unregister_chatcommand("<name>") and minetest.override_chatcommand("<name>", {<redifinition>})
4264 lines
185 KiB
Plaintext
4264 lines
185 KiB
Plaintext
Minetest Lua Modding API Reference 0.4.15
|
||
=========================================
|
||
* More information at <http://www.minetest.net/>
|
||
* Developer Wiki: <http://dev.minetest.net/>
|
||
|
||
Introduction
|
||
------------
|
||
Content and functionality can be added to Minetest 0.4 by using Lua
|
||
scripting in run-time loaded mods.
|
||
|
||
A mod is a self-contained bunch of scripts, textures and other related
|
||
things that is loaded by and interfaces with Minetest.
|
||
|
||
Mods are contained and ran solely on the server side. Definitions and media
|
||
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>.
|
||
|
||
Programming in Lua
|
||
------------------
|
||
If you have any difficulty in understanding this, please read
|
||
[Programming in Lua](http://www.lua.org/pil/).
|
||
|
||
Startup
|
||
-------
|
||
Mods are loaded during server startup from the mod load paths by running
|
||
the `init.lua` scripts in a shared environment.
|
||
|
||
Paths
|
||
-----
|
||
* `RUN_IN_PLACE=1` (Windows release, local build)
|
||
* `$path_user`:
|
||
* Linux: `<build directory>`
|
||
* Windows: `<build directory>`
|
||
* `$path_share`
|
||
* Linux: `<build directory>`
|
||
* Windows: `<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)
|
||
|
||
Games
|
||
-----
|
||
Games are looked up from:
|
||
|
||
* `$path_share/games/gameid/`
|
||
* `$path_user/games/gameid/`
|
||
|
||
where `gameid` is unique to each game.
|
||
|
||
The game directory contains the file `game.conf`, which contains these fields:
|
||
|
||
name = <Human-readable full name of the game>
|
||
|
||
e.g.
|
||
|
||
name = Minetest
|
||
|
||
The game directory can contain the file minetest.conf, which will be used
|
||
to set default settings when running the particular game.
|
||
It can also contain a settingtypes.txt in the same format as the one in builtin.
|
||
This settingtypes.txt will be parsed by the menu and the settings will be displayed
|
||
in the "Games" category in the settings tab.
|
||
|
||
### Menu images
|
||
|
||
Games can provide custom main menu images. They are put inside a `menu` directory
|
||
inside the game directory.
|
||
|
||
The images are named `$identifier.png`, where `$identifier` is
|
||
one of `overlay,background,footer,header`.
|
||
If you want to specify multiple images for one identifier, add additional images named
|
||
like `$identifier.$n.png`, with an ascending number $n starting with 1, and a random
|
||
image will be chosen from the provided ones.
|
||
|
||
|
||
Mod load path
|
||
-------------
|
||
Generic:
|
||
|
||
* `$path_share/games/gameid/mods/`
|
||
* `$path_share/mods/`
|
||
* `$path_user/games/gameid/mods/`
|
||
* `$path_user/mods/` (User-installed mods)
|
||
* `$worldpath/worldmods/`
|
||
|
||
In a run-in-place version (e.g. the distributed windows version):
|
||
|
||
* `minetest-0.4.x/games/gameid/mods/`
|
||
* `minetest-0.4.x/mods/` (User-installed mods)
|
||
* `minetest-0.4.x/worlds/worldname/worldmods/`
|
||
|
||
On an installed version on Linux:
|
||
|
||
* `/usr/share/minetest/games/gameid/mods/`
|
||
* `$HOME/.minetest/mods/` (User-installed mods)
|
||
* `$HOME/.minetest/worlds/worldname/worldmods`
|
||
|
||
Mod load path for world-specific games
|
||
--------------------------------------
|
||
It is possible to include a game in a world; in this case, no mods or
|
||
games are loaded or checked from anywhere else.
|
||
|
||
This is useful for e.g. adventure worlds.
|
||
|
||
This happens if the following directory exists:
|
||
|
||
$world/game/
|
||
|
||
Mods should be then be placed in:
|
||
|
||
$world/game/mods/
|
||
|
||
Modpack support
|
||
----------------
|
||
Mods can be put in a subdirectory, if the parent directory, which otherwise
|
||
should be a mod, contains a file named `modpack.txt`. This file shall be
|
||
empty, except for lines starting with `#`, which are comments.
|
||
|
||
Mod directory structure
|
||
------------------------
|
||
|
||
mods
|
||
|-- modname
|
||
| |-- depends.txt
|
||
| |-- screenshot.png
|
||
| |-- description.txt
|
||
| |-- settingtypes.txt
|
||
| |-- init.lua
|
||
| |-- models
|
||
| |-- textures
|
||
| | |-- modname_stuff.png
|
||
| | `-- modname_something_else.png
|
||
| |-- sounds
|
||
| |-- media
|
||
| `-- <custom data>
|
||
`-- another
|
||
|
||
|
||
### modname
|
||
The location of this directory can be fetched by using
|
||
`minetest.get_modpath(modname)`.
|
||
|
||
### `depends.txt`
|
||
List of mods that have to be loaded before loading this mod.
|
||
|
||
A single line contains a single modname.
|
||
|
||
Optional dependencies can be defined by appending a question mark
|
||
to a single modname. Their meaning is that if the specified mod
|
||
is missing, that does not prevent this mod from being loaded.
|
||
|
||
### `screenshot.png`
|
||
A screenshot shown in the mod manager within the main menu. It should
|
||
have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
|
||
|
||
### `description.txt`
|
||
A File containing description to be shown within mainmenu.
|
||
|
||
### `settingtypes.txt`
|
||
A file in the same format as the one in builtin. It will be parsed by the
|
||
settings menu and the settings will be displayed in the "Mods" category.
|
||
|
||
### `init.lua`
|
||
The main Lua script. Running this script should register everything it
|
||
wants to register. Subsequent execution depends on minetest calling the
|
||
registered callbacks.
|
||
|
||
`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
|
||
to read custom or existing settings at load time, if necessary.
|
||
|
||
### `models`
|
||
Models for entities or meshnodes.
|
||
|
||
### `textures`, `sounds`, `media`
|
||
Media files (textures, sounds, whatever) that will be transferred to the
|
||
client and will be available for use by the mod.
|
||
|
||
Naming convention for registered textual names
|
||
----------------------------------------------
|
||
Registered names should generally be in this format:
|
||
|
||
"modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
|
||
|
||
This is to prevent conflicting names from corrupting maps and is
|
||
enforced by the mod loader.
|
||
|
||
### Example
|
||
In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
|
||
So the name should be `experimental:tnt`.
|
||
|
||
Enforcement can be overridden by prefixing the name with `:`. This can
|
||
be used for overriding the registrations of some other mod.
|
||
|
||
Example: Any mod can redefine `experimental:tnt` by using the name
|
||
|
||
:experimental:tnt
|
||
|
||
when registering it.
|
||
(also that mod is required to have `experimental` as a dependency)
|
||
|
||
The `:` prefix can also be used for maintaining backwards compatibility.
|
||
|
||
### Aliases
|
||
Aliases can be added by using `minetest.register_alias(name, convert_to)` or
|
||
`minetest.register_alias_force(name, convert_to).
|
||
|
||
This will make Minetest to convert things called name to things called
|
||
`convert_to`.
|
||
|
||
The only difference between `minetest.register_alias` and
|
||
`minetest.register_alias_force` is that if an item called `name` exists,
|
||
`minetest.register_alias` will do nothing while
|
||
`minetest.register_alias_force` will unregister it.
|
||
|
||
This can be used for maintaining backwards compatibility.
|
||
|
||
This can be also used for setting quick access names for things, e.g. if
|
||
you have an item called `epiclylongmodname:stuff`, you could do
|
||
|
||
minetest.register_alias("stuff", "epiclylongmodname:stuff")
|
||
|
||
and be able to use `/giveme stuff`.
|
||
|
||
Textures
|
||
--------
|
||
Mods should generally prefix their textures with `modname_`, e.g. given
|
||
the mod name `foomod`, a texture could be called:
|
||
|
||
foomod_foothing.png
|
||
|
||
Textures are referred to by their complete name, or alternatively by
|
||
stripping out the file extension:
|
||
|
||
* e.g. `foomod_foothing.png`
|
||
* e.g. `foomod_foothing`
|
||
|
||
Texture modifiers
|
||
-----------------
|
||
There are various texture modifiers that can be used
|
||
to generate textures on-the-fly.
|
||
|
||
### Texture overlaying
|
||
Textures can be overlaid by putting a `^` between them.
|
||
|
||
Example:
|
||
|
||
default_dirt.png^default_grass_side.png
|
||
|
||
`default_grass_side.png` is overlayed over `default_dirt.png`.
|
||
The texture with the lower resolution will be automatically upscaled to
|
||
the higher resolution texture.
|
||
|
||
### Texture grouping
|
||
Textures can be grouped together by enclosing them in `(` and `)`.
|
||
|
||
Example: `cobble.png^(thing1.png^thing2.png)`
|
||
|
||
A texture for `thing1.png^thing2.png` is created and the resulting
|
||
texture is overlaid on top of `cobble.png`.
|
||
|
||
### Escaping
|
||
Modifiers that accept texture names (e.g. `[combine`) accept escaping to allow
|
||
passing complex texture names as arguments. Escaping is done with backslash and
|
||
is required for `^` and `:`.
|
||
|
||
Example: `cobble.png^[lowpart:50:color.png\^[mask\:trans.png`
|
||
|
||
The lower 50 percent of `color.png^[mask:trans.png` are overlaid
|
||
on top of `cobble.png`.
|
||
|
||
### Advanced texture modifiers
|
||
|
||
#### `[crack:<n>:<p>`
|
||
* `<n>` = animation frame count
|
||
* `<p>` = current animation frame
|
||
|
||
Draw a step of the crack animation on the texture.
|
||
|
||
Example:
|
||
|
||
default_cobble.png^[crack:10:1
|
||
|
||
#### `[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>:...`
|
||
* `<w>` = width
|
||
* `<h>` = height
|
||
* `<x>` = x position
|
||
* `<y>` = y position
|
||
* `<file>` = texture to combine
|
||
|
||
Creates a texture of size `<w>` times `<h>` and blits the listed files to their
|
||
specified coordinates.
|
||
|
||
Example:
|
||
|
||
[combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
|
||
|
||
#### `[resize:<w>x<h>`
|
||
Resizes the texture to the given dimensions.
|
||
|
||
Example:
|
||
|
||
default_sandstone.png^[resize:16x16
|
||
|
||
#### `[opacity:<r>`
|
||
Makes the base image transparent according to the given ratio.
|
||
r must be between 0 and 255.
|
||
0 means totally transparent.
|
||
255 means totally opaque.
|
||
|
||
Example:
|
||
|
||
default_sandstone.png^[opacity:127
|
||
|
||
#### `[invert:<mode>`
|
||
Inverts the given channels of the base image.
|
||
Mode may contain the characters "r", "g", "b", "a".
|
||
Only the channels that are mentioned in the mode string will be inverted.
|
||
|
||
Example:
|
||
|
||
default_apple.png^[invert:rgb
|
||
|
||
#### `[brighten`
|
||
Brightens the texture.
|
||
|
||
Example:
|
||
|
||
tnt_tnt_side.png^[brighten
|
||
|
||
#### `[noalpha`
|
||
Makes the texture completely opaque.
|
||
|
||
Example:
|
||
|
||
default_leaves.png^[noalpha
|
||
|
||
#### `[makealpha:<r>,<g>,<b>`
|
||
Convert one color to transparency.
|
||
|
||
Example:
|
||
|
||
default_cobble.png^[makealpha:128,128,128
|
||
|
||
#### `[transform<t>`
|
||
* `<t>` = transformation(s) to apply
|
||
|
||
Rotates and/or flips the image.
|
||
|
||
`<t>` can be a number (between 0 and 7) or a transform name.
|
||
Rotations are counter-clockwise.
|
||
|
||
0 I identity
|
||
1 R90 rotate by 90 degrees
|
||
2 R180 rotate by 180 degrees
|
||
3 R270 rotate by 270 degrees
|
||
4 FX flip X
|
||
5 FXR90 flip X then rotate by 90 degrees
|
||
6 FY flip Y
|
||
7 FYR90 flip Y then rotate by 90 degrees
|
||
|
||
Example:
|
||
|
||
default_stone.png^[transformFXR90
|
||
|
||
#### `[inventorycube{<top>{<left>{<right>`
|
||
Escaping does not apply here and `^` is replaced by `&` in texture names instead.
|
||
|
||
Create an inventory cube texture using the side textures.
|
||
|
||
Example:
|
||
|
||
[inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png
|
||
|
||
Creates an inventorycube with `grass.png`, `dirt.png^grass_side.png` and
|
||
`dirt.png^grass_side.png` textures
|
||
|
||
#### `[lowpart:<percent>:<file>`
|
||
Blit the lower `<percent>`% part of `<file>` on the texture.
|
||
|
||
Example:
|
||
|
||
base.png^[lowpart:25:overlay.png
|
||
|
||
#### `[verticalframe:<t>:<n>`
|
||
* `<t>` = animation frame count
|
||
* `<n>` = current animation frame
|
||
|
||
Crops the texture to a frame of a vertical animation.
|
||
|
||
Example:
|
||
|
||
default_torch_animated.png^[verticalframe:16:8
|
||
|
||
#### `[mask:<file>`
|
||
Apply a mask to the base image.
|
||
|
||
The mask is applied using binary AND.
|
||
|
||
#### `[sheet:<w>x<h>:<x>,<y>`
|
||
Retrieves a tile at position x,y from the base image
|
||
which it assumes to be a tilesheet with dimensions w,h.
|
||
|
||
|
||
#### `[colorize:<color>:<ratio>`
|
||
Colorize the textures with the given color.
|
||
`<color>` is specified as a `ColorString`.
|
||
`<ratio>` is an int ranging from 0 to 255 or the word "`alpha`". If
|
||
it is an int, then it specifies how far to interpolate between the
|
||
colors where 0 is only the texture color and 255 is only `<color>`. If
|
||
omitted, the alpha of `<color>` will be used as the ratio. If it is
|
||
the word "`alpha`", then each texture pixel will contain the RGB of
|
||
`<color>` and the alpha of `<color>` multiplied by the alpha of the
|
||
texture pixel.
|
||
|
||
Sounds
|
||
------
|
||
Only Ogg Vorbis files are supported.
|
||
|
||
For positional playing of sounds, only single-channel (mono) files are
|
||
supported. Otherwise OpenAL will play them non-positionally.
|
||
|
||
Mods should generally prefix their sounds with `modname_`, e.g. given
|
||
the mod name "`foomod`", a sound could be called:
|
||
|
||
foomod_foosound.ogg
|
||
|
||
Sounds are referred to by their name with a dot, a single digit and the
|
||
file extension stripped out. When a sound is played, the actual sound file
|
||
is chosen randomly from the matching sounds.
|
||
|
||
When playing the sound `foomod_foosound`, the sound is chosen randomly
|
||
from the available ones of the following files:
|
||
|
||
* `foomod_foosound.ogg`
|
||
* `foomod_foosound.0.ogg`
|
||
* `foomod_foosound.1.ogg`
|
||
* (...)
|
||
* `foomod_foosound.9.ogg`
|
||
|
||
Examples of sound parameter tables:
|
||
|
||
-- Play locationless on all clients
|
||
{
|
||
gain = 1.0, -- default
|
||
}
|
||
-- Play locationless to one player
|
||
{
|
||
to_player = name,
|
||
gain = 1.0, -- default
|
||
}
|
||
-- Play locationless to one player, looped
|
||
{
|
||
to_player = name,
|
||
gain = 1.0, -- default
|
||
loop = true,
|
||
}
|
||
-- Play in a location
|
||
{
|
||
pos = {x = 1, y = 2, z = 3},
|
||
gain = 1.0, -- default
|
||
max_hear_distance = 32, -- default, uses an euclidean metric
|
||
}
|
||
-- Play connected to an object, looped
|
||
{
|
||
object = <an ObjectRef>,
|
||
gain = 1.0, -- default
|
||
max_hear_distance = 32, -- default, uses an euclidean metric
|
||
loop = true,
|
||
}
|
||
|
||
Looped sounds must either be connected to an object or played locationless to
|
||
one player using `to_player = name,`
|
||
|
||
### `SimpleSoundSpec`
|
||
* e.g. `""`
|
||
* e.g. `"default_place_node"`
|
||
* e.g. `{}`
|
||
* e.g. `{name = "default_place_node"}`
|
||
* e.g. `{name = "default_place_node", gain = 1.0}`
|
||
|
||
Registered definitions of stuff
|
||
-------------------------------
|
||
Anything added using certain `minetest.register_*` functions get added to
|
||
the global `minetest.registered_*` tables.
|
||
|
||
* `minetest.register_entity(name, prototype table)`
|
||
* added to `minetest.registered_entities[name]`
|
||
|
||
* `minetest.register_node(name, node definition)`
|
||
* added to `minetest.registered_items[name]`
|
||
* added to `minetest.registered_nodes[name]`
|
||
|
||
* `minetest.register_tool(name, item definition)`
|
||
* added to `minetest.registered_items[name]`
|
||
|
||
* `minetest.register_craftitem(name, item definition)`
|
||
* added to `minetest.registered_items[name]`
|
||
|
||
* `minetest.unregister_item(name)`
|
||
* Unregisters the item name from engine, and deletes the entry with key
|
||
* `name` from `minetest.registered_items` and from the associated item
|
||
* table according to its nature: minetest.registered_nodes[] etc
|
||
|
||
* `minetest.register_biome(biome definition)`
|
||
* returns an integer uniquely identifying the registered biome
|
||
* added to `minetest.registered_biome` with the key of `biome.name`
|
||
* if `biome.name` is nil, the key is the returned ID
|
||
|
||
* `minetest.register_ore(ore definition)`
|
||
* returns an integer uniquely identifying the registered ore
|
||
* added to `minetest.registered_ores` with the key of `ore.name`
|
||
* if `ore.name` is nil, the key is the returned ID
|
||
|
||
* `minetest.register_decoration(decoration definition)`
|
||
* returns an integer uniquely identifying the registered decoration
|
||
* added to `minetest.registered_decorations` with the key of `decoration.name`
|
||
* if `decoration.name` is nil, the key is the returned ID
|
||
|
||
* `minetest.register_schematic(schematic definition)`
|
||
* returns an integer uniquely identifying the registered schematic
|
||
* added to `minetest.registered_schematic` with the key of `schematic.name`
|
||
* if `schematic.name` is nil, the key is the returned ID
|
||
* if the schematic is loaded from a file, schematic.name is set to the filename
|
||
* if the function is called when loading the mod, and schematic.name is a relative
|
||
path, then the current mod path will be prepended to the schematic filename
|
||
|
||
* `minetest.clear_registered_biomes()`
|
||
* clears all biomes currently registered
|
||
|
||
* `minetest.clear_registered_ores()`
|
||
* clears all ores currently registered
|
||
|
||
* `minetest.clear_registered_decorations()`
|
||
* clears all decorations currently registered
|
||
|
||
* `minetest.clear_registered_schematics()`
|
||
* clears all schematics currently registered
|
||
|
||
Note that in some cases you will stumble upon things that are not contained
|
||
in these tables (e.g. when a mod has been removed). Always check for
|
||
existence before trying to access the fields.
|
||
|
||
Example: If you want to check the drawtype of a node, you could do:
|
||
|
||
local function get_nodedef_field(nodename, fieldname)
|
||
if not minetest.registered_nodes[nodename] then
|
||
return nil
|
||
end
|
||
return minetest.registered_nodes[nodename][fieldname]
|
||
end
|
||
local drawtype = get_nodedef_field(nodename, "drawtype")
|
||
|
||
Example: `minetest.get_item_group(name, group)` has been implemented as:
|
||
|
||
function minetest.get_item_group(name, group)
|
||
if not minetest.registered_items[name] or not
|
||
minetest.registered_items[name].groups[group] then
|
||
return 0
|
||
end
|
||
return minetest.registered_items[name].groups[group]
|
||
end
|
||
|
||
Nodes
|
||
-----
|
||
Nodes are the bulk data of the world: cubes and other things that take the
|
||
space of a cube. Huge amounts of them are handled efficiently, but they
|
||
are quite static.
|
||
|
||
The definition of a node is stored and can be accessed by name in
|
||
|
||
minetest.registered_nodes[node.name]
|
||
|
||
See "Registered definitions of stuff".
|
||
|
||
Nodes are passed by value between Lua and the engine.
|
||
They are represented by a table:
|
||
|
||
{name="name", param1=num, param2=num}
|
||
|
||
`param1` and `param2` are 8-bit integers. The engine uses them for certain
|
||
automated functions. If you don't use these functions, you can use them to
|
||
store arbitrary values.
|
||
|
||
The functions of `param1` and `param2` are determined by certain fields in the
|
||
node definition:
|
||
|
||
`param1` is reserved for the engine when `paramtype != "none"`:
|
||
|
||
paramtype = "light"
|
||
^ The value stores light with and without sun in its upper and lower 4 bits
|
||
respectively. Allows light to propagate from or through the node with
|
||
light value falling by 1 per node. This is essential for a light source
|
||
node to spread its light.
|
||
|
||
`param2` is reserved for the engine when any of these are used:
|
||
|
||
liquidtype == "flowing"
|
||
^ The level and some flags of the liquid is stored in param2
|
||
drawtype == "flowingliquid"
|
||
^ The drawn liquid level is read from param2
|
||
drawtype == "torchlike"
|
||
drawtype == "signlike"
|
||
paramtype2 == "wallmounted"
|
||
^ The rotation of the node is stored in param2. You can make this value
|
||
by using minetest.dir_to_wallmounted().
|
||
paramtype2 == "facedir"
|
||
^ The rotation of the node is stored in param2. Furnaces and chests are
|
||
rotated this way. Can be made by using minetest.dir_to_facedir().
|
||
Values range 0 - 23
|
||
facedir / 4 = axis direction:
|
||
0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y-
|
||
facedir modulo 4 = rotation around that axis
|
||
paramtype2 == "leveled"
|
||
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
|
||
get the actual rotation of the node.
|
||
paramtype2 == "meshoptions"
|
||
^ Only valid for "plantlike". The value of param2 becomes a bitfield which can
|
||
be used to change how the client draws plantlike nodes. Bits 0, 1 and 2 form
|
||
a mesh selector. Currently the following meshes are choosable:
|
||
0 = a "x" shaped plant (ordinary plant)
|
||
1 = a "+" shaped plant (just rotated 45 degrees)
|
||
2 = a "*" shaped plant with 3 faces instead of 2
|
||
3 = a "#" shaped plant with 4 faces instead of 2
|
||
4 = a "#" shaped plant with 4 faces that lean outwards
|
||
5-7 are unused and reserved for future meshes.
|
||
Bits 3 through 7 are optional flags that can be combined and give these
|
||
effects:
|
||
bit 3 (0x08) - Makes the plant slightly vary placement horizontally
|
||
bit 4 (0x10) - Makes the plant mesh 1.4x larger
|
||
bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
|
||
bits 6-7 are reserved for future use.
|
||
collision_box = {
|
||
type = "fixed",
|
||
fixed = {
|
||
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
|
||
},
|
||
},
|
||
^ defines list of collision boxes for the node. If empty, collision boxes
|
||
will be the same as nodeboxes, in case of any other nodes will be full cube
|
||
as in the example above.
|
||
|
||
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`.
|
||
|
||
* `normal`
|
||
* `airlike`
|
||
* `liquid`
|
||
* `flowingliquid`
|
||
* `glasslike`
|
||
* `glasslike_framed`
|
||
* `glasslike_framed_optional`
|
||
* `allfaces`
|
||
* `allfaces_optional`
|
||
* `torchlike`
|
||
* `signlike`
|
||
* `plantlike`
|
||
* `firelike`
|
||
* `fencelike`
|
||
* `raillike`
|
||
* `nodebox` -- See below. (**Experimental!**)
|
||
* `mesh` -- use models for nodes
|
||
|
||
`*_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.
|
||
|
||
A nodebox is defined as any of:
|
||
|
||
{
|
||
-- A normal cube; the default in most things
|
||
type = "regular"
|
||
}
|
||
{
|
||
-- A fixed box (facedir param2 is used, if applicable)
|
||
type = "fixed",
|
||
fixed = box OR {box1, box2, ...}
|
||
}
|
||
{
|
||
-- A box like the selection box for torches
|
||
-- (wallmounted param2 is used, if applicable)
|
||
type = "wallmounted",
|
||
wall_top = box,
|
||
wall_bottom = box,
|
||
wall_side = box
|
||
}
|
||
{
|
||
-- A node that has optional boxes depending on neighbouring nodes'
|
||
-- presence and type. See also `connects_to`.
|
||
type = "connected",
|
||
fixed = box OR {box1, box2, ...}
|
||
connect_top = box OR {box1, box2, ...}
|
||
connect_bottom = box OR {box1, box2, ...}
|
||
connect_front = box OR {box1, box2, ...}
|
||
connect_left = box OR {box1, box2, ...}
|
||
connect_back = box OR {box1, box2, ...}
|
||
connect_right = box OR {box1, box2, ...}
|
||
}
|
||
|
||
A `box` is defined as:
|
||
|
||
{x1, y1, z1, x2, y2, z2}
|
||
|
||
A box of a regular node would look like:
|
||
|
||
{-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.
|
||
|
||
|
||
Noise Parameters
|
||
----------------
|
||
Noise Parameters, or commonly called "`NoiseParams`", define the properties of
|
||
perlin noise.
|
||
|
||
### `offset`
|
||
Offset that the noise is translated by (i.e. added) after calculation.
|
||
|
||
### `scale`
|
||
Factor that the noise is scaled by (i.e. multiplied) after calculation.
|
||
|
||
### `spread`
|
||
Vector containing values by which each coordinate is divided by before calculation.
|
||
Higher spread values result in larger noise features.
|
||
|
||
A value of `{x=250, y=250, z=250}` is common.
|
||
|
||
### `seed`
|
||
Random seed for the noise. Add the world seed to a seed offset for world-unique noise.
|
||
In the case of `minetest.get_perlin()`, this value has the world seed automatically added.
|
||
|
||
### `octaves`
|
||
Number of times the noise gradient is accumulated into the noise.
|
||
|
||
Increase this number to increase the amount of detail in the resulting noise.
|
||
|
||
A value of `6` is common.
|
||
|
||
### `persistence`
|
||
Factor by which the effect of the noise gradient function changes with each successive octave.
|
||
|
||
Values less than `1` make the details of successive octaves' noise diminish, while values
|
||
greater than `1` make successive octaves stronger.
|
||
|
||
A value of `0.6` is common.
|
||
|
||
### `lacunarity`
|
||
Factor by which the noise feature sizes change with each successive octave.
|
||
|
||
A value of `2.0` is common.
|
||
|
||
### `flags`
|
||
Leave this field unset for no special handling.
|
||
|
||
Currently supported are `defaults`, `eased` and `absvalue`.
|
||
|
||
#### `defaults`
|
||
Specify this if you would like to keep auto-selection of eased/not-eased while specifying
|
||
some other flags.
|
||
|
||
#### `eased`
|
||
Maps noise gradient values onto a quintic S-curve before performing interpolation.
|
||
This results in smooth, rolling noise. Disable this (`noeased`) for sharp-looking noise.
|
||
If no flags are specified (or defaults is), 2D noise is eased and 3D noise is not eased.
|
||
|
||
#### `absvalue`
|
||
Accumulates the absolute value of each noise gradient result.
|
||
|
||
Noise parameters format example for 2D or 3D perlin noise or perlin noise maps:
|
||
np_terrain = {
|
||
offset = 0,
|
||
scale = 1,
|
||
spread = {x=500, y=500, z=500},
|
||
seed = 571347,
|
||
octaves = 5,
|
||
persist = 0.63,
|
||
lacunarity = 2.0,
|
||
flags = "defaults, absvalue"
|
||
}
|
||
^ A single noise parameter table can be used to get 2D or 3D noise,
|
||
when getting 2D noise spread.z is ignored.
|
||
|
||
|
||
Ore types
|
||
---------
|
||
These tell in what manner the ore is generated.
|
||
|
||
All default ores are of the uniformly-distributed scatter type.
|
||
|
||
### `scatter`
|
||
Randomly chooses a location and generates a cluster of ore.
|
||
|
||
If `noise_params` is specified, the ore will be placed if the 3D perlin noise at
|
||
that point is greater than the `noise_threshold`, giving the ability to create
|
||
a non-equal distribution of ore.
|
||
|
||
### `sheet`
|
||
Creates a sheet of ore in a blob shape according to the 2D perlin noise
|
||
described by `noise_params` and `noise_threshold`. This is essentially an
|
||
improved version of the so-called "stratus" ore seen in some unofficial mods.
|
||
|
||
This sheet consists of vertical columns of uniform randomly distributed height,
|
||
varying between the inclusive range `column_height_min` and `column_height_max`.
|
||
If `column_height_min` is not specified, this parameter defaults to 1.
|
||
If `column_height_max` is not specified, this parameter defaults to `clust_size`
|
||
for reverse compatibility. New code should prefer `column_height_max`.
|
||
|
||
The `column_midpoint_factor` parameter controls the position of the column at which
|
||
ore eminates from. If 1, columns grow upward. If 0, columns grow downward. If 0.5,
|
||
columns grow equally starting from each direction. `column_midpoint_factor` is a
|
||
decimal number ranging in value from 0 to 1. If this parameter is not specified,
|
||
the default is 0.5.
|
||
|
||
The ore parameters `clust_scarcity` and `clust_num_ores` are ignored for this ore type.
|
||
|
||
### `puff`
|
||
Creates a sheet of ore in a cloud-like puff shape.
|
||
|
||
As with the `sheet` ore type, the size and shape of puffs are described by
|
||
`noise_params` and `noise_threshold` and are placed at random vertical positions
|
||
within the currently generated chunk.
|
||
|
||
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
|
||
`clust_scarcity` has the same meaning as with the `scatter` type.
|
||
|
||
### `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`.
|
||
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:
|
||
|
||
noise_params = {
|
||
offset = 0,
|
||
scale = 3,
|
||
spread = {x=200, y=200, z=200},
|
||
seed = 5390,
|
||
octaves = 4,
|
||
persist = 0.5,
|
||
flags = "eased",
|
||
},
|
||
noise_threshold = 1.6
|
||
|
||
WARNING: Use this ore type *very* sparingly since it is ~200x more
|
||
computationally expensive than any other ore.
|
||
|
||
Ore attributes
|
||
--------------
|
||
See section "Flag Specifier Format".
|
||
|
||
Currently supported flags: `absheight`
|
||
|
||
### `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`
|
||
If set, puff ore generation will not taper down large differences in displacement
|
||
when approaching the edge of a puff. This flag has no effect for ore types other
|
||
than `puff`.
|
||
|
||
### `puff_additive_composition`
|
||
By default, when noise described by `np_puff_top` or `np_puff_bottom` results in a
|
||
negative displacement, the sub-column at that point is not generated. With this
|
||
attribute set, puff ore generation will instead generate the absolute difference in
|
||
noise displacement values. This flag has no effect for ore types other than `puff`.
|
||
|
||
Decoration types
|
||
----------------
|
||
The varying types of decorations that can be placed.
|
||
|
||
### `simple`
|
||
Creates a 1 times `H` times 1 column of a specified node (or a random node from
|
||
a list, if a decoration list is specified). Can specify a certain node it must
|
||
spawn next to, such as water or lava, for example. Can also generate a
|
||
decoration of random height between a specified lower and upper bound.
|
||
This type of decoration is intended for placement of grass, flowers, cacti,
|
||
papyri, waterlilies and so on.
|
||
|
||
### `schematic`
|
||
Copies a box of `MapNodes` from a specified schematic file (or raw description).
|
||
Can specify a probability of a node randomly appearing when placed.
|
||
This decoration type is intended to be used for multi-node sized discrete
|
||
structures, such as trees, cave spikes, rocks, and so on.
|
||
|
||
|
||
Schematic specifier
|
||
--------------------
|
||
A schematic specifier identifies a schematic by either a filename to a
|
||
Minetest Schematic file (`.mts`) or through raw data supplied through Lua,
|
||
in the form of a table. This table specifies the following fields:
|
||
|
||
* The `size` field is a 3D vector containing the dimensions of the provided schematic. (required)
|
||
* The `yslice_prob` field is a table of {ypos, prob} which sets the `ypos`th vertical slice
|
||
of the schematic to have a `prob / 256 * 100` chance of occuring. (default: 255)
|
||
* The `data` field is a flat table of MapNode tables making up the schematic,
|
||
in the order of `[z [y [x]]]`. (required)
|
||
Each MapNode table contains:
|
||
* `name`: the name of the map node to place (required)
|
||
* `prob` (alias `param1`): the probability of this node being placed (default: 255)
|
||
* `param2`: the raw param2 value of the node being placed onto the map (default: 0)
|
||
* `force_place`: boolean representing if the node should forcibly overwrite any
|
||
previous contents (default: false)
|
||
|
||
About probability values:
|
||
* A probability value of `0` or `1` means that node will never appear (0% chance).
|
||
* A probability value of `254` or `255` means the node will always appear (100% chance).
|
||
* If the probability value `p` is greater than `1`, then there is a
|
||
`(p / 256 * 100)` percent chance that node will appear when the schematic is
|
||
placed on the map.
|
||
|
||
|
||
Schematic attributes
|
||
--------------------
|
||
See section "Flag Specifier Format".
|
||
|
||
Currently supported flags: `place_center_x`, `place_center_y`, `place_center_z`,
|
||
`force_placement`.
|
||
|
||
* `place_center_x`: Placement of this decoration is centered along the X axis.
|
||
* `place_center_y`: Placement of this decoration is centered along the Y axis.
|
||
* `place_center_z`: Placement of this decoration is centered along the Z axis.
|
||
* `force_placement`: Schematic nodes other than "ignore" will replace existing nodes.
|
||
|
||
|
||
HUD element types
|
||
-----------------
|
||
The position field is used for all element types.
|
||
|
||
To account for differing resolutions, the position coordinates are the percentage
|
||
of the screen, ranging in value from `0` to `1`.
|
||
|
||
The name field is not yet used, but should contain a description of what the
|
||
HUD element represents. The direction field is the direction in which something
|
||
is drawn.
|
||
|
||
`0` draws from left to right, `1` draws from right to left, `2` draws from
|
||
top to bottom, and `3` draws from bottom to top.
|
||
|
||
The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
|
||
with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
|
||
Fractional values can be used.
|
||
|
||
The `offset` field specifies a pixel offset from the position. Contrary to position,
|
||
the offset is not scaled to screen size. This allows for some precisely-positioned
|
||
items in the HUD.
|
||
|
||
**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor!
|
||
|
||
Below are the specific uses for fields in each type; fields not listed for that type are ignored.
|
||
|
||
**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
|
||
in the experimental stages.
|
||
|
||
### `image`
|
||
Displays an image on the HUD.
|
||
|
||
* `scale`: The scale of the image, with 1 being the original texture size.
|
||
Only the X coordinate scale is used (positive values).
|
||
Negative values represent that percentage of the screen it
|
||
should take; e.g. `x=-100` means 100% (width).
|
||
* `text`: The name of the texture that is displayed.
|
||
* `alignment`: The alignment of the image.
|
||
* `offset`: offset in pixels from position.
|
||
|
||
### `text`
|
||
Displays text on the HUD.
|
||
|
||
* `scale`: Defines the bounding rectangle of the text.
|
||
A value such as `{x=100, y=100}` should work.
|
||
* `text`: The text to be displayed in the HUD element.
|
||
* `number`: An integer containing the RGB value of the color used to draw the text.
|
||
Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
|
||
* `alignment`: The alignment of the text.
|
||
* `offset`: offset in pixels from position.
|
||
|
||
### `statbar`
|
||
Displays a horizontal bar made up of half-images.
|
||
|
||
* `text`: The name of the texture that is used.
|
||
* `number`: The number of half-textures that are displayed.
|
||
If odd, will end with a vertically center-split texture.
|
||
* `direction`
|
||
* `offset`: offset in pixels from position.
|
||
* `size`: If used, will force full-image size to this value (override texture pack image size)
|
||
|
||
### `inventory`
|
||
* `text`: The name of the inventory list to be displayed.
|
||
* `number`: Number of items in the inventory to be displayed.
|
||
* `item`: Position of item that is selected.
|
||
* `direction`
|
||
* `offset`: offset in pixels from position.
|
||
|
||
### `waypoint`
|
||
Displays distance to selected world position.
|
||
|
||
* `name`: The name of the waypoint.
|
||
* `text`: Distance suffix. Can be blank.
|
||
* `number:` An integer containing the RGB value of the color used to draw the text.
|
||
* `world_pos`: World position of the waypoint.
|
||
|
||
Representations of simple things
|
||
--------------------------------
|
||
|
||
### Position/vector
|
||
|
||
{x=num, y=num, z=num}
|
||
|
||
For helper functions see "Vector helpers".
|
||
|
||
### `pointed_thing`
|
||
* `{type="nothing"}`
|
||
* `{type="node", under=pos, above=pos}`
|
||
* `{type="object", ref=ObjectRef}`
|
||
|
||
Flag Specifier Format
|
||
---------------------
|
||
Flags using the standardized flag specifier format can be specified in either of
|
||
two ways, by string or table.
|
||
|
||
The string format is a comma-delimited set of flag names; whitespace and
|
||
unrecognized flag fields are ignored. Specifying a flag in the string sets the
|
||
flag, and specifying a flag prefixed by the string `"no"` explicitly
|
||
clears the flag from whatever the default may be.
|
||
|
||
In addition to the standard string flag format, the schematic flags field can
|
||
also be a table of flag names to boolean values representing whether or not the
|
||
flag is set. Additionally, if a field with the flag name prefixed with `"no"`
|
||
is present, mapped to a boolean of any value, the specified flag is unset.
|
||
|
||
E.g. A flag field of value
|
||
|
||
{place_center_x = true, place_center_y=false, place_center_z=true}
|
||
|
||
is equivalent to
|
||
|
||
{place_center_x = true, noplace_center_y=true, place_center_z=true}
|
||
|
||
which is equivalent to
|
||
|
||
"place_center_x, noplace_center_y, place_center_z"
|
||
|
||
or even
|
||
|
||
"place_center_x, place_center_z"
|
||
|
||
since, by default, no schematic attributes are set.
|
||
|
||
Items
|
||
-----
|
||
|
||
### Item types
|
||
There are three kinds of items: nodes, tools and craftitems.
|
||
|
||
* Node (`register_node`): A node from the world.
|
||
* Tool (`register_tool`): A tool/weapon that can dig and damage
|
||
things according to `tool_capabilities`.
|
||
* Craftitem (`register_craftitem`): A miscellaneous item.
|
||
|
||
### Item formats
|
||
Items and item stacks can exist in three formats: Serializes, table format
|
||
and `ItemStack`.
|
||
|
||
#### Serialized
|
||
This is called "stackstring" or "itemstring":
|
||
|
||
* e.g. `'default:dirt 5'`
|
||
* e.g. `'default:pick_wood 21323'`
|
||
* e.g. `'default:apple'`
|
||
|
||
#### Table format
|
||
Examples:
|
||
|
||
5 dirt nodes:
|
||
|
||
{name="default:dirt", count=5, wear=0, metadata=""}
|
||
|
||
A wooden pick about 1/3 worn out:
|
||
|
||
{name="default:pick_wood", count=1, wear=21323, metadata=""}
|
||
|
||
An apple:
|
||
|
||
{name="default:apple", count=1, wear=0, metadata=""}
|
||
|
||
#### `ItemStack`
|
||
A native C++ format with many helper methods. Useful for converting
|
||
between formats. See the Class reference section for details.
|
||
|
||
When an item must be passed to a function, it can usually be in any of
|
||
these formats.
|
||
|
||
|
||
Groups
|
||
------
|
||
In a number of places, there is a group table. Groups define the
|
||
properties of a thing (item, node, armor of entity, capabilities of
|
||
tool) in such a way that the engine and other mods can can interact with
|
||
the thing without actually knowing what the thing is.
|
||
|
||
### Usage
|
||
Groups are stored in a table, having the group names with keys and the
|
||
group ratings as values. For example:
|
||
|
||
groups = {crumbly=3, soil=1}
|
||
-- ^ Default dirt
|
||
|
||
groups = {crumbly=2, soil=1, level=2, outerspace=1}
|
||
-- ^ A more special dirt-kind of thing
|
||
|
||
Groups always have a rating associated with them. If there is no
|
||
useful meaning for a rating for an enabled group, it shall be `1`.
|
||
|
||
When not defined, the rating of a group defaults to `0`. Thus when you
|
||
read groups, you must interpret `nil` and `0` as the same value, `0`.
|
||
|
||
You can read the rating of a group for an item or a node by using
|
||
|
||
minetest.get_item_group(itemname, groupname)
|
||
|
||
### Groups of items
|
||
Groups of items can define what kind of an item it is (e.g. wool).
|
||
|
||
### Groups of nodes
|
||
In addition to the general item things, groups are used to define whether
|
||
a node is destroyable and how long it takes to destroy by a tool.
|
||
|
||
### Groups of entities
|
||
For entities, groups are, as of now, used only for calculating damage.
|
||
The rating is the percentage of damage caused by tools with this damage group.
|
||
See "Entity damage mechanism".
|
||
|
||
object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
|
||
object.set_armor_groups({fleshy=30, cracky=80})
|
||
|
||
### Groups of tools
|
||
Groups in tools define which groups of nodes and entities they are
|
||
effective towards.
|
||
|
||
### Groups in crafting recipes
|
||
An example: Make meat soup from any meat, any water and any bowl:
|
||
|
||
{
|
||
output = 'food:meat_soup_raw',
|
||
recipe = {
|
||
{'group:meat'},
|
||
{'group:water'},
|
||
{'group:bowl'},
|
||
},
|
||
-- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
|
||
}
|
||
|
||
Another example: Make red wool from white wool and red dye:
|
||
|
||
{
|
||
type = 'shapeless',
|
||
output = 'wool:red',
|
||
recipe = {'wool:white', 'group:dye,basecolor_red'},
|
||
}
|
||
|
||
### Special groups
|
||
* `immortal`: Disables the group damage system for an entity
|
||
* `level`: Can be used to give an additional sense of progression in the game.
|
||
* A larger level will cause e.g. a weapon of a lower level make much less
|
||
damage, and get worn out much faster, or not be able to get drops
|
||
from destroyed nodes.
|
||
* `0` is something that is directly accessible at the start of gameplay
|
||
* There is no upper limit
|
||
* `dig_immediate`: (player can always pick up node without tool wear)
|
||
* `2`: node is removed without tool wear after 0.5 seconds or so
|
||
(rail, sign)
|
||
* `3`: node is removed without tool wear immediately (torch)
|
||
* `disable_jump`: Player (and possibly other things) cannot jump from node
|
||
* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
|
||
* `bouncy`: value is bounce speed in percent
|
||
* `falling_node`: if there is no walkable block under the node it will fall
|
||
* `attached_node`: if the node under it is not a walkable block the node will be
|
||
dropped as an item. If the node is wallmounted the wallmounted direction is
|
||
checked.
|
||
* `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
|
||
|
||
### Known damage and digging time defining groups
|
||
* `crumbly`: dirt, sand
|
||
* `cracky`: tough but crackable stuff like stone.
|
||
* `snappy`: something that can be cut using fine tools; e.g. leaves, small
|
||
plants, wire, sheets of metal
|
||
* `choppy`: something that can be cut using force; e.g. trees, wooden planks
|
||
* `fleshy`: Living things like animals and the player. This could imply
|
||
some blood effects when hitting.
|
||
* `explody`: Especially prone to explosions
|
||
* `oddly_breakable_by_hand`:
|
||
Can be added to nodes that shouldn't logically be breakable by the
|
||
hand but are. Somewhat similar to `dig_immediate`, but times are more
|
||
like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the
|
||
speed of a tool if the tool can dig at a faster speed than this
|
||
suggests for the hand.
|
||
|
||
### Examples of custom groups
|
||
Item groups are often used for defining, well, _groups of items_.
|
||
* `meat`: any meat-kind of a thing (rating might define the size or healing
|
||
ability or be irrelevant -- it is not defined as of yet)
|
||
* `eatable`: anything that can be eaten. Rating might define HP gain in half
|
||
hearts.
|
||
* `flammable`: can be set on fire. Rating might define the intensity of the
|
||
fire, affecting e.g. the speed of the spreading of an open fire.
|
||
* `wool`: any wool (any origin, any color)
|
||
* `metal`: any metal
|
||
* `weapon`: any weapon
|
||
* `heavy`: anything considerably heavy
|
||
|
||
### Digging time calculation specifics
|
||
Groups such as `crumbly`, `cracky` and `snappy` are used for this
|
||
purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies
|
||
faster digging time.
|
||
|
||
The `level` group is used to limit the toughness of nodes a tool can dig
|
||
and to scale the digging times / damage to a greater extent.
|
||
|
||
**Please do understand this**, otherwise you cannot use the system to it's
|
||
full potential.
|
||
|
||
Tools define their properties by a list of parameters for groups. They
|
||
cannot dig other groups; thus it is important to use a standard bunch of
|
||
groups to enable interaction with tools.
|
||
|
||
#### Tools definition
|
||
Tools define:
|
||
|
||
* Full punch interval
|
||
* Maximum drop level
|
||
* For an arbitrary list of groups:
|
||
* Uses (until the tool breaks)
|
||
* Maximum level (usually `0`, `1`, `2` or `3`)
|
||
* Digging times
|
||
* Damage groups
|
||
|
||
#### Full punch interval
|
||
When used as a weapon, the tool will do full damage if this time is spent
|
||
between punches. If e.g. half the time is spent, the tool will do half
|
||
damage.
|
||
|
||
#### Maximum drop level
|
||
Suggests the maximum level of node, when dug with the tool, that will drop
|
||
it's useful item. (e.g. iron ore to drop a lump of iron).
|
||
|
||
This is not automated; it is the responsibility of the node definition
|
||
to implement this.
|
||
|
||
#### Uses
|
||
Determines how many uses the tool has when it is used for digging a node,
|
||
of this group, of the maximum level. For lower leveled nodes, the use count
|
||
is multiplied by `3^leveldiff`.
|
||
|
||
* `uses=10, leveldiff=0`: actual uses: 10
|
||
* `uses=10, leveldiff=1`: actual uses: 30
|
||
* `uses=10, leveldiff=2`: actual uses: 90
|
||
|
||
#### Maximum level
|
||
Tells what is the maximum level of a node of this group that the tool will
|
||
be able to dig.
|
||
|
||
#### Digging times
|
||
List of digging times for different ratings of the group, for nodes of the
|
||
maximum level.
|
||
|
||
For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would
|
||
result in the tool 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.
|
||
Unless there is a matching group that enables digging otherwise.
|
||
|
||
#### Damage groups
|
||
List of damage for groups of entities. See "Entity damage mechanism".
|
||
|
||
#### Example definition of the capabilities of a tool
|
||
|
||
tool_capabilities = {
|
||
full_punch_interval=1.5,
|
||
max_drop_level=1,
|
||
groupcaps={
|
||
crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
|
||
}
|
||
damage_groups = {fleshy=2},
|
||
}
|
||
|
||
This makes the tool be able to dig nodes that fulfil both of these:
|
||
|
||
* Have the `crumbly` group
|
||
* Have a `level` group less or equal to `2`
|
||
|
||
Table of resulting digging times:
|
||
|
||
crumbly 0 1 2 3 4 <- level
|
||
-> 0 - - - - -
|
||
1 0.80 1.60 1.60 - -
|
||
2 0.60 1.20 1.20 - -
|
||
3 0.40 0.80 0.80 - -
|
||
|
||
level diff: 2 1 0 -1 -2
|
||
|
||
Table of resulting tool uses:
|
||
|
||
-> 0 - - - - -
|
||
1 180 60 20 - -
|
||
2 180 60 20 - -
|
||
3 180 60 20 - -
|
||
|
||
**Notes**:
|
||
|
||
* At `crumbly==0`, the node is not diggable.
|
||
* At `crumbly==3`, the level difference digging time divider kicks in and makes
|
||
easy nodes to be quickly breakable.
|
||
* At `level > 2`, the node is not diggable, because it's `level > maxlevel`
|
||
|
||
Entity damage mechanism
|
||
-----------------------
|
||
Damage calculation:
|
||
|
||
damage = 0
|
||
foreach group in cap.damage_groups:
|
||
damage += cap.damage_groups[group] * limit(actual_interval /
|
||
cap.full_punch_interval, 0.0, 1.0)
|
||
* (object.armor_groups[group] / 100.0)
|
||
-- Where object.armor_groups[group] is 0 for inexistent values
|
||
return damage
|
||
|
||
Client predicts damage based on damage groups. Because of this, it is able to
|
||
give an immediate response when an entity is damaged or dies; the response is
|
||
pre-defined somehow (e.g. by defining a sprite animation) (not implemented;
|
||
TODO).
|
||
Currently a smoke puff will appear when an entity dies.
|
||
|
||
The group `immortal` completely disables normal damage.
|
||
|
||
Entities can define a special armor group, which is `punch_operable`. This
|
||
group disables the regular damage mechanism for players punching it by hand or
|
||
a non-tool item, so that it can do something else than take damage.
|
||
|
||
On the Lua side, every punch calls:
|
||
|
||
entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction)
|
||
|
||
This should never be called directly, because damage is usually not handled by
|
||
the entity itself.
|
||
|
||
* `puncher` is the object performing the punch. Can be `nil`. Should never be
|
||
accessed unless absolutely required, to encourage interoperability.
|
||
* `time_from_last_punch` is time from last punch (by `puncher`) or `nil`.
|
||
* `tool_capabilities` can be `nil`.
|
||
* `direction` is a unit vector, pointing from the source of the punch to
|
||
the punched object.
|
||
|
||
To punch an entity/object in Lua, call:
|
||
|
||
object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
|
||
|
||
* Return value is tool wear.
|
||
* Parameters are equal to the above callback.
|
||
* If `direction` equals `nil` and `puncher` does not equal `nil`,
|
||
`direction` will be automatically filled in based on the location of `puncher`.
|
||
|
||
Node Metadata
|
||
-------------
|
||
The instance of a node in the world normally only contains the three values
|
||
mentioned in "Nodes". However, it is possible to insert extra data into a
|
||
node. It is called "node metadata"; See "`NodeMetaRef`".
|
||
|
||
Metadata contains two things:
|
||
|
||
* A key-value store
|
||
* An inventory
|
||
|
||
Some of the values in the key-value store are handled specially:
|
||
|
||
* `formspec`: Defines a right-click inventory menu. See "Formspec".
|
||
* `infotext`: Text shown on the screen when the node is pointed at
|
||
|
||
Example stuff:
|
||
|
||
local meta = minetest.get_meta(pos)
|
||
meta:set_string("formspec",
|
||
"size[8,9]"..
|
||
"list[context;main;0,0;8,4;]"..
|
||
"list[current_player;main;0,5;8,4;]")
|
||
meta:set_string("infotext", "Chest");
|
||
local inv = meta:get_inventory()
|
||
inv:set_size("main", 8*4)
|
||
print(dump(meta:to_table()))
|
||
meta:from_table({
|
||
inventory = {
|
||
main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "",
|
||
[5] = "", [6] = "", [7] = "", [8] = "", [9] = "",
|
||
[10] = "", [11] = "", [12] = "", [13] = "",
|
||
[14] = "default:cobble", [15] = "", [16] = "", [17] = "",
|
||
[18] = "", [19] = "", [20] = "default:cobble", [21] = "",
|
||
[22] = "", [23] = "", [24] = "", [25] = "", [26] = "",
|
||
[27] = "", [28] = "", [29] = "", [30] = "", [31] = "",
|
||
[32] = ""}
|
||
},
|
||
fields = {
|
||
formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
|
||
infotext = "Chest"
|
||
}
|
||
})
|
||
|
||
Formspec
|
||
--------
|
||
Formspec defines a menu. Currently not much else than inventories are
|
||
supported. It is a string, with a somewhat strange format.
|
||
|
||
Spaces and newlines can be inserted between the blocks, as is used in the
|
||
examples.
|
||
|
||
### Examples
|
||
|
||
#### Chest
|
||
|
||
size[8,9]
|
||
list[context;main;0,0;8,4;]
|
||
list[current_player;main;0,5;8,4;]
|
||
|
||
#### Furnace
|
||
|
||
size[8,9]
|
||
list[context;fuel;2,3;1,1;]
|
||
list[context;src;2,1;1,1;]
|
||
list[context;dst;5,1;2,2;]
|
||
list[current_player;main;0,5;8,4;]
|
||
|
||
#### Minecraft-like player inventory
|
||
|
||
size[8,7.5]
|
||
image[1,0.6;1,2;player.png]
|
||
list[current_player;main;0,3.5;8,4;]
|
||
list[current_player;craft;3,0;3,3;]
|
||
list[current_player;craftpreview;7,1;1,1;]
|
||
|
||
### Elements
|
||
|
||
#### `size[<W>,<H>,<fixed_size>]`
|
||
* Define the size of the menu in inventory slots
|
||
* `fixed_size`: `true`/`false` (optional)
|
||
* deprecated: `invsize[<W>,<H>;]`
|
||
|
||
#### `container[<X>,<Y>]`
|
||
* Start of a container block, moves all physical elements in the container by (X, Y)
|
||
* Must have matching container_end
|
||
* Containers can be nested, in which case the offsets are added
|
||
(child containers are relative to parent containers)
|
||
|
||
#### `container_end[]`
|
||
* End of a container, following elements are no longer relative to this container
|
||
|
||
#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
|
||
* Show an inventory list
|
||
|
||
#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
|
||
* Show an inventory list
|
||
|
||
#### `listring[<inventory location>;<list name>]`
|
||
* Allows to create a ring of inventory lists
|
||
* Shift-clicking on items in one element of the ring
|
||
will send them to the next inventory list inside the ring
|
||
* The first occurrence of an element inside the ring will
|
||
determine the inventory where items will be sent to
|
||
|
||
#### `listring[]`
|
||
* Shorthand for doing `listring[<inventory location>;<list name>]`
|
||
for the last two inventory lists added by list[...]
|
||
|
||
#### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
|
||
* Sets background color of slots as `ColorString`
|
||
* Sets background color of slots on mouse hovering
|
||
|
||
#### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
|
||
* Sets background color of slots as `ColorString`
|
||
* Sets background color of slots on mouse hovering
|
||
* Sets color of slots border
|
||
|
||
#### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
|
||
* Sets background color of slots as `ColorString`
|
||
* Sets background color of slots on mouse hovering
|
||
* Sets color of slots border
|
||
* Sets default background color of tooltips
|
||
* Sets default font color of tooltips
|
||
|
||
#### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
|
||
* Adds tooltip for an element
|
||
* `<bgcolor>` tooltip background color as `ColorString` (optional)
|
||
* `<fontcolor>` tooltip font color as `ColorString` (optional)
|
||
|
||
#### `image[<X>,<Y>;<W>,<H>;<texture name>]`
|
||
* Show an image
|
||
* Position and size units are inventory slots
|
||
|
||
#### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
|
||
* Show an inventory image of registered item/node
|
||
* Position and size units are inventory slots
|
||
|
||
#### `bgcolor[<color>;<fullscreen>]`
|
||
* Sets background color of formspec as `ColorString`
|
||
* If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
|
||
|
||
#### `background[<X>,<Y>;<W>,<H>;<texture name>]`
|
||
* Use a background. Inventory rectangles are not drawn then.
|
||
* Position and size units are inventory slots
|
||
* Example for formspec 8x4 in 16x resolution: image shall be sized
|
||
8 times 16px times 4 times 16px.
|
||
|
||
#### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
|
||
* Use a background. Inventory rectangles are not drawn then.
|
||
* Position and size units are inventory slots
|
||
* Example for formspec 8x4 in 16x resolution:
|
||
image shall be sized 8 times 16px times 4 times 16px
|
||
* If `true` the background is clipped to formspec size
|
||
(`x` and `y` are used as offset values, `w` and `h` are ignored)
|
||
|
||
#### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
|
||
* Textual password style field; will be sent to server when a button is clicked
|
||
* When enter is pressed in field, fields.key_enter_field will be sent with the name
|
||
of this field.
|
||
* `x` and `y` position the field relative to the top left of the menu
|
||
* `w` and `h` are the size of the field
|
||
* Fields are a set height, but will be vertically centred on `h`
|
||
* Position and size units are inventory slots
|
||
* `name` is the name of the field as returned in fields to `on_receive_fields`
|
||
* `label`, if not blank, will be text printed on the top left above the field
|
||
* See field_close_on_enter to stop enter closing the formspec
|
||
|
||
#### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
|
||
* Textual field; will be sent to server when a button is clicked
|
||
* When enter is pressed in field, fields.key_enter_field will be sent with the name
|
||
of this field.
|
||
* `x` and `y` position the field relative to the top left of the menu
|
||
* `w` and `h` are the size of the field
|
||
* Fields are a set height, but will be vertically centred on `h`
|
||
* Position and size units are inventory slots
|
||
* `name` is the name of the field as returned in fields to `on_receive_fields`
|
||
* `label`, if not blank, will be text printed on the top left above the field
|
||
* `default` is the default value of the field
|
||
* `default` may contain variable references such as `${text}'` which
|
||
will fill the value from the metadata value `text`
|
||
* **Note**: no extra text or more than a single variable is supported ATM.
|
||
* See field_close_on_enter to stop enter closing the formspec
|
||
|
||
#### `field[<name>;<label>;<default>]`
|
||
* As above, but without position/size units
|
||
* When enter is pressed in field, fields.key_enter_field will be sent with the name
|
||
of this field.
|
||
* Special field for creating simple forms, such as sign text input
|
||
* Must be used without a `size[]` element
|
||
* A "Proceed" button will be added automatically
|
||
* See field_close_on_enter to stop enter closing the formspec
|
||
|
||
#### `field_close_on_enter[<name>;<close_on_enter>]`
|
||
* <name> is the name of the field
|
||
* if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
|
||
* defaults to true when not specified (ie: no tag for a field)
|
||
|
||
#### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
|
||
* Same as fields above, but with multi-line input
|
||
|
||
#### `label[<X>,<Y>;<label>]`
|
||
* `x` and `y` work as per field
|
||
* `label` is the text on the label
|
||
* Position and size units are inventory slots
|
||
|
||
#### `vertlabel[<X>,<Y>;<label>]`
|
||
* Textual label drawn vertically
|
||
* `x` and `y` work as per field
|
||
* `label` is the text on the label
|
||
* Position and size units are inventory slots
|
||
|
||
#### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
|
||
* 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
|
||
* `label` is the text on the button
|
||
* Position and size units are inventory slots
|
||
|
||
#### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
|
||
* `x`, `y`, `w`, `h`, and `name` work as per button
|
||
* `texture name` is the filename of an image
|
||
* Position and size units are inventory slots
|
||
|
||
#### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
|
||
* `x`, `y`, `w`, `h`, and `name` work as per button
|
||
* `texture name` is the filename of an image
|
||
* Position and size units are inventory slots
|
||
* `noclip=true` means the image button doesn't need to be within specified formsize
|
||
* `drawborder`: draw button border or not
|
||
* `pressed texture name` is the filename of an image on pressed state
|
||
|
||
#### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
|
||
* `x`, `y`, `w`, `h`, `name` and `label` work as per button
|
||
* `item name` is the registered name of an item/node,
|
||
tooltip will be made out of its description
|
||
to override it use tooltip element
|
||
* Position and size units are inventory slots
|
||
|
||
#### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
|
||
* When clicked, fields will be sent and the form will quit.
|
||
|
||
#### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
|
||
* When clicked, fields will be sent and the form will quit.
|
||
|
||
#### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
|
||
* Scrollable item list showing arbitrary text elements
|
||
* `x` and `y` position the itemlist relative to the top left of the menu
|
||
* `w` and `h` are the size of the itemlist
|
||
* `name` fieldname sent to server on doubleclick value is current selected element
|
||
* `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
|
||
* if you want a listelement to start with "#" write "##".
|
||
|
||
#### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
|
||
* Scrollable itemlist showing arbitrary text elements
|
||
* `x` and `y` position the item list relative to the top left of the menu
|
||
* `w` and `h` are the size of the item list
|
||
* `name` fieldname sent to server on doubleclick value is current selected element
|
||
* `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
|
||
* if you want a listelement to start with "#" write "##"
|
||
* Index to be selected within textlist
|
||
* `true`/`false`: draw transparent background
|
||
* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
|
||
|
||
#### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
|
||
* Show a tab**header** at specific position (ignores formsize)
|
||
* `x` and `y` position the itemlist relative to the top left of the menu
|
||
* `name` fieldname data is transferred to Lua
|
||
* `caption 1`...: name shown on top of tab
|
||
* `current_tab`: index of selected tab 1...
|
||
* `transparent` (optional): show transparent
|
||
* `draw_border` (optional): draw border
|
||
|
||
#### `box[<X>,<Y>;<W>,<H>;<color>]`
|
||
* Simple colored semitransparent box
|
||
* `x` and `y` position the box relative to the top left of the menu
|
||
* `w` and `h` are the size of box
|
||
* `color` is color specified as a `ColorString`
|
||
|
||
#### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
|
||
* Show a dropdown field
|
||
* **Important note**: There are two different operation modes:
|
||
1. handle directly on change (only changed dropdown is submitted)
|
||
2. read the value on pressing a button (all dropdown values are available)
|
||
* `x` and `y` position of dropdown
|
||
* Width of dropdown
|
||
* Fieldname data is transferred to Lua
|
||
* Items to be shown in dropdown
|
||
* Index of currently selected dropdown item
|
||
|
||
#### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
|
||
* Show a checkbox
|
||
* `x` and `y`: position of checkbox
|
||
* `name` fieldname data is transferred to Lua
|
||
* `label` to be shown left of checkbox
|
||
* `selected` (optional): `true`/`false`
|
||
|
||
#### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
|
||
* Show a scrollbar
|
||
* There are two ways to use it:
|
||
1. handle the changed event (only changed scrollbar is available)
|
||
2. read the value on pressing a button (all scrollbars are available)
|
||
* `x` and `y`: position of trackbar
|
||
* `w` and `h`: width and height
|
||
* `orientation`: `vertical`/`horizontal`
|
||
* Fieldname data is transferred to Lua
|
||
* Value this trackbar is set to (`0`-`1000`)
|
||
* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
|
||
|
||
#### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
|
||
* Show scrollable table using options defined by the previous `tableoptions[]`
|
||
* Displays cells as defined by the previous `tablecolumns[]`
|
||
* `x` and `y`: position the itemlist relative to the top left of the menu
|
||
* `w` and `h` are the size of the itemlist
|
||
* `name`: fieldname sent to server on row select or doubleclick
|
||
* `cell 1`...`cell n`: cell contents given in row-major order
|
||
* `selected idx`: index of row to be selected within table (first row = `1`)
|
||
* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
|
||
|
||
#### `tableoptions[<opt 1>;<opt 2>;...]`
|
||
* Sets options for `table[]`
|
||
* `color=#RRGGBB`
|
||
* default text color (`ColorString`), defaults to `#FFFFFF`
|
||
* `background=#RRGGBB`
|
||
* table background color (`ColorString`), defaults to `#000000`
|
||
* `border=<true/false>`
|
||
* should the table be drawn with a border? (default: `true`)
|
||
* `highlight=#RRGGBB`
|
||
* highlight background color (`ColorString`), defaults to `#466432`
|
||
* `highlight_text=#RRGGBB`
|
||
* highlight text color (`ColorString`), defaults to `#FFFFFF`
|
||
* `opendepth=<value>`
|
||
* all subtrees up to `depth < value` are open (default value = `0`)
|
||
* only useful when there is a column of type "tree"
|
||
|
||
#### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
|
||
* Sets columns for `table[]`
|
||
* Types: `text`, `image`, `color`, `indent`, `tree`
|
||
* `text`: show cell contents as text
|
||
* `image`: cell contents are an image index, use column options to define images
|
||
* `color`: cell contents are a ColorString and define color of following cell
|
||
* `indent`: cell contents are a number and define indentation of following cell
|
||
* `tree`: same as indent, but user can open and close subtrees (treeview-like)
|
||
* Column options:
|
||
* `align=<value>`
|
||
* for `text` and `image`: content alignment within cells.
|
||
Available values: `left` (default), `center`, `right`, `inline`
|
||
* `width=<value>`
|
||
* for `text` and `image`: minimum width in em (default: `0`)
|
||
* for `indent` and `tree`: indent width in em (default: `1.5`)
|
||
* `padding=<value>`: padding left of the column, in em (default `0.5`).
|
||
Exception: defaults to 0 for indent columns
|
||
* `tooltip=<value>`: tooltip text (default: empty)
|
||
* `image` column options:
|
||
* `0=<value>` sets image for image index 0
|
||
* `1=<value>` sets image for image index 1
|
||
* `2=<value>` sets image for image index 2
|
||
* and so on; defined indices need not be contiguous empty or
|
||
non-numeric cells are treated as `0`.
|
||
* `color` column options:
|
||
* `span=<value>`: number of following columns to affect (default: infinite)
|
||
|
||
**Note**: do _not_ use a element name starting with `key_`; those names are reserved to
|
||
pass key press events to formspec!
|
||
|
||
Inventory locations
|
||
-------------------
|
||
* `"context"`: Selected node metadata (deprecated: `"current_name"`)
|
||
* `"current_player"`: Player to whom the menu is shown
|
||
* `"player:<name>"`: Any player
|
||
* `"nodemeta:<X>,<Y>,<Z>"`: Any node metadata
|
||
* `"detached:<name>"`: A detached inventory
|
||
|
||
Player Inventory lists
|
||
----------------------
|
||
* `main`: list containing the default inventory
|
||
* `craft`: list containing the craft input
|
||
* `craftpreview`: list containing the craft output
|
||
* `hand`: list containing an override for the empty hand
|
||
|
||
`ColorString`
|
||
-------------
|
||
`#RGB` defines a color in hexadecimal format.
|
||
|
||
`#RGBA` defines a color in hexadecimal format and alpha channel.
|
||
|
||
`#RRGGBB` defines a color in hexadecimal format.
|
||
|
||
`#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
|
||
|
||
Named colors are also supported and are equivalent to
|
||
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
|
||
To specify the value of the alpha channel, append `#AA` to the end of the color name
|
||
(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
|
||
value must (always) be two hexadecimal digits.
|
||
|
||
`ColorSpec`
|
||
-----------
|
||
A ColorSpec specifies a 32-bit color. It can be written in either:
|
||
table form, each element ranging from 0..255 (a, if absent, defaults to 255):
|
||
`colorspec = {a=255, r=0, g=255, b=0}`
|
||
numerical form, the raw integer value of an ARGB8 quad:
|
||
`colorspec = 0xFF00FF00`
|
||
or string form, a ColorString (defined above):
|
||
`colorspec = "green"`
|
||
|
||
Escape sequences
|
||
----------------
|
||
Most text can contain escape sequences, that can for example color the text.
|
||
There are a few exceptions: tab headers, dropdowns and vertical labels can't.
|
||
The following functions provide escape sequences:
|
||
* `core.get_color_escape_sequence(color)`:
|
||
* `color` is a ColorString
|
||
* The escape sequence sets the text color to `color`
|
||
* `core.colorize(color, message)`:
|
||
* Equivalent to:
|
||
`core.get_color_escape_sequence(color) ..
|
||
message ..
|
||
core.get_color_escape_sequence("#ffffff")`
|
||
* `color.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.
|
||
|
||
Spatial Vectors
|
||
---------------
|
||
* `vector.new(a[, b, c])`: returns a vector:
|
||
* A copy of `a` if `a` is a vector.
|
||
* `{x = a, y = b, z = c}`, if all `a, b, c` are defined
|
||
* `vector.direction(p1, p2)`: returns a vector
|
||
* `vector.distance(p1, p2)`: returns a number
|
||
* `vector.length(v)`: returns a number
|
||
* `vector.normalize(v)`: returns a vector
|
||
* `vector.floor(v)`: returns a vector, each dimension rounded down
|
||
* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
|
||
* `vector.apply(v, func)`: returns a vector
|
||
* `vector.equals(v1, v2)`: returns a boolean
|
||
|
||
For the following functions `x` can be either a vector or a number:
|
||
|
||
* `vector.add(v, x)`: returns a vector
|
||
* `vector.subtract(v, x)`: returns a vector
|
||
* `vector.multiply(v, x)`: returns a scaled vector or Schur product
|
||
* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
|
||
|
||
Helper functions
|
||
----------------
|
||
* `dump2(obj, name="_", dumped={})`
|
||
* Return object serialized as a string, handles reference loops
|
||
* `dump(obj, dumped={})`
|
||
* Return object serialized as a string
|
||
* `math.hypot(x, y)`
|
||
* Get the hypotenuse of a triangle with legs x and y.
|
||
Useful for distance calculation.
|
||
* `math.sign(x, tolerance)`
|
||
* 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.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns `"(X,Y,Z)"`
|
||
* Convert position to a printable string
|
||
Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
|
||
* `minetest.string_to_pos(string)`: returns a position
|
||
* Same but in reverse. Returns `nil` if the string can't be parsed to a position.
|
||
* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
|
||
* Converts a string representing an area box into two positions
|
||
* `minetest.formspec_escape(string)`: returns a string
|
||
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
|
||
* `minetest.is_yes(arg)`
|
||
* returns whether `arg` can be interpreted as yes
|
||
* `minetest.get_us_time()`
|
||
* returns time with microsecond precision. May not return wall time.
|
||
* `table.copy(table)`: returns a table
|
||
* returns a deep copy of `table`
|
||
|
||
`minetest` namespace reference
|
||
------------------------------
|
||
|
||
### Utilities
|
||
|
||
* `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
|
||
* `minetest.get_modpath(modname)`: returns e.g. `"/home/user/.minetest/usermods/modname"`
|
||
* Useful for loading additional `.lua` modules or static data from mod
|
||
* `minetest.get_modnames()`: returns a list of installed mods
|
||
* Return a list of installed mods, sorted alphabetically
|
||
* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
|
||
* Useful for storing custom data
|
||
* `minetest.is_singleplayer()`
|
||
* `minetest.features`
|
||
* Table containing API feature flags: `{foo=true, bar=true}`
|
||
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
|
||
* `arg`: string or table in format `{foo=true, bar=true}`
|
||
* `missing_features`: `{foo=true, bar=true}`
|
||
* `minetest.get_player_information(player_name)`: returns a table containing
|
||
information about player. Example return value:
|
||
{
|
||
address = "127.0.0.1", -- IP address of client
|
||
ip_version = 4, -- IPv4 / IPv6
|
||
min_rtt = 0.01, -- minimum round trip time
|
||
max_rtt = 0.2, -- maximum round trip time
|
||
avg_rtt = 0.02, -- average round trip time
|
||
min_jitter = 0.01, -- minimum packet time jitter
|
||
max_jitter = 0.5, -- maximum packet time jitter
|
||
avg_jitter = 0.03, -- average packet time jitter
|
||
connection_uptime = 200, -- seconds since client connected
|
||
|
||
-- following information is available on debug build only!!!
|
||
-- DO NOT USE IN MODS
|
||
--ser_vers = 26, -- serialization version used by client
|
||
--prot_vers = 23, -- protocol version used by client
|
||
--major = 0, -- major version number
|
||
--minor = 4, -- minor version number
|
||
--patch = 10, -- patch version number
|
||
--vers_string = "0.4.9-git", -- full version string
|
||
--state = "Active" -- current client state
|
||
}
|
||
* `minetest.mkdir(path)`: returns success.
|
||
* Creates a directory specified by `path`, creating parent directories
|
||
if they don't exist.
|
||
* `minetest.get_dir_list(path, [is_dir])`: returns list of entry names
|
||
* is_dir is one of:
|
||
* nil: return all entries,
|
||
* true: return only subdirectory names, or
|
||
* false: return only file names.
|
||
* `minetest.get_version()`: returns a table containing components of the
|
||
engine version. Components:
|
||
* `project`: Name of the project, eg, "Minetest"
|
||
* `string`: Simple version, eg, "1.2.3-dev"
|
||
* `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
|
||
Use this for informational purposes only. The information in the returned
|
||
table does not represent the capabilities of the engine, nor is it
|
||
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 core.nodeupdate then ... end`.
|
||
|
||
### Logging
|
||
* `minetest.debug(...)`
|
||
* Equivalent to `minetest.log(table.concat({...}, "\t"))`
|
||
* `minetest.log([level,] text)`
|
||
* `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
|
||
`"info"`, or `"verbose"`. Default is `"none"`.
|
||
|
||
### Registration functions
|
||
Call these functions only at load time!
|
||
|
||
* `minetest.register_entity(name, prototype table)`
|
||
* `minetest.register_abm(abm definition)`
|
||
* `minetest.register_lbm(lbm definition)`
|
||
* `minetest.register_node(name, node definition)`
|
||
* `minetest.register_tool(name, item definition)`
|
||
* `minetest.register_craftitem(name, item definition)`
|
||
* `minetest.unregister_item(name)`
|
||
* `minetest.register_alias(name, convert_to)`
|
||
* `minetest.register_alias_force(name, convert_to)`
|
||
* `minetest.register_craft(recipe)`
|
||
* Check recipe table syntax for different types below.
|
||
* `minetest.clear_craft(recipe)`
|
||
* Will erase existing craft based either on output item or on input recipe.
|
||
* Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table
|
||
syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity.
|
||
* If no erase candidate could be found, Lua exception will be thrown.
|
||
* Warning! The type field ("shaped","cooking" or any other) will be ignored if the recipe
|
||
contains output. Erasing is then done independently from the crafting method.
|
||
* `minetest.register_ore(ore definition)`
|
||
* `minetest.register_biome(biome definition)`
|
||
* `minetest.register_decoration(decoration definition)`
|
||
* `minetest.override_item(name, redefinition)`
|
||
* Overrides fields of an item registered with register_node/tool/craftitem.
|
||
* Note: Item must already be defined, (opt)depend on the mod defining it.
|
||
* Example: `minetest.override_item("default:mese", {light_source=LIGHT_MAX})`
|
||
* `minetest.clear_registered_ores()`
|
||
* `minetest.clear_registered_biomes()`
|
||
* `minetest.clear_registered_decorations()`
|
||
|
||
### Global callback registration functions
|
||
Call these functions only at load time!
|
||
|
||
* `minetest.register_globalstep(func(dtime))`
|
||
* Called every server step, usually interval of 0.1s
|
||
* `minetest.register_on_shutdown(func())`
|
||
* Called before server shutdown
|
||
* **Warning**: If the server terminates abnormally (i.e. crashes), the registered
|
||
callbacks **will likely not be run**. Data should be saved at
|
||
semi-frequent intervals as well as on server shutdown.
|
||
* `minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack, pointed_thing))`
|
||
* Called when a node has been placed
|
||
* If return `true` no item is taken from `itemstack`
|
||
* **Not recommended**; use `on_construct` or `after_place_node` in node definition
|
||
whenever possible
|
||
* `minetest.register_on_dignode(func(pos, oldnode, digger))`
|
||
* Called when a node has been dug.
|
||
* **Not recommended**; Use `on_destruct` or `after_dig_node` in node definition
|
||
whenever possible
|
||
* `minetest.register_on_punchnode(func(pos, node, puncher, pointed_thing))`
|
||
* Called when a node is punched
|
||
* `minetest.register_on_generated(func(minp, maxp, blockseed))`
|
||
* Called after generating a piece of world. Modifying nodes inside the area
|
||
is a bit faster than usually.
|
||
* `minetest.register_on_newplayer(func(ObjectRef))`
|
||
* Called after a new player has been created
|
||
* `minetest.register_on_dieplayer(func(ObjectRef))`
|
||
* Called when a player dies
|
||
* `minetest.register_on_punchplayer(func(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))`
|
||
* Called when a player is punched
|
||
* `player` - ObjectRef - Player that was punched
|
||
* `hitter` - ObjectRef - Player that hit
|
||
* `time_from_last_punch`: Meant for disallowing spamming of clicks (can be nil)
|
||
* `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.
|
||
* `damage` - number that represents the damage calculated by the engine
|
||
* should return `true` to prevent the default damage mechanism
|
||
* `minetest.register_on_player_hpchange(func(player, hp_change), modifier)`
|
||
* Called when the player gets damaged or healed
|
||
* `player`: ObjectRef of the player
|
||
* `hp_change`: the amount of change. Negative when it is damage.
|
||
* `modifier`: when true, the function should return the actual hp_change.
|
||
Note: modifiers only get a temporary hp_change that can be modified by later modifiers.
|
||
modifiers can return true as a second argument to stop the execution of further functions.
|
||
Non-modifiers receive the final hp change calculated by the modifiers.
|
||
* `minetest.register_on_respawnplayer(func(ObjectRef))`
|
||
* Called when player is to be respawned
|
||
* Called _before_ repositioning of player occurs
|
||
* return true in func to disable regular player placement
|
||
* `minetest.register_on_prejoinplayer(func(name, ip))`
|
||
* Called before a player joins the game
|
||
* If it returns a string, the player is disconnected with that string as reason
|
||
* `minetest.register_on_joinplayer(func(ObjectRef))`
|
||
* Called when a player joins the game
|
||
* `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))`
|
||
* Called when a player leaves the game
|
||
* `timed_out`: True for timeout, false for other reasons.
|
||
* `minetest.register_on_cheat(func(ObjectRef, cheat))`
|
||
* Called when a player cheats
|
||
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
|
||
* `moved_too_fast`
|
||
* `interacted_too_far`
|
||
* `interacted_while_dead`
|
||
* `finished_unknown_dig`
|
||
* `dug_unbreakable`
|
||
* `dug_too_fast`
|
||
* `minetest.register_on_chat_message(func(name, message))`
|
||
* Called always when a player says something
|
||
* Return `true` to mark the message as handled, which means that it will not be sent to other players
|
||
* `minetest.register_on_player_receive_fields(func(player, formname, fields))`
|
||
* Called when a button is pressed in player's inventory form
|
||
* Newest functions are called first
|
||
* If function returns `true`, remaining functions are not called
|
||
* `minetest.register_on_craft(func(itemstack, player, old_craft_grid, craft_inv))`
|
||
* Called when `player` crafts something
|
||
* `itemstack` is the output
|
||
* `old_craft_grid` contains the recipe (Note: the one in the inventory is cleared)
|
||
* `craft_inv` is the inventory with the crafting grid
|
||
* Return either an `ItemStack`, to replace the output, or `nil`, to not modify it
|
||
* `minetest.register_craft_predict(func(itemstack, player, old_craft_grid, craft_inv))`
|
||
* The same as before, except that it is called before the player crafts, to make
|
||
craft prediction, and it should not change anything.
|
||
* `minetest.register_on_protection_violation(func(pos, name))`
|
||
* Called by `builtin` and mods when a player violates protection at a position
|
||
(eg, digs a node or punches a protected entity).
|
||
* The registered functions can be called using `minetest.record_protection_violation`
|
||
* The provided function should check that the position is protected by the mod
|
||
calling this function before it prints a message, if it does, to allow for
|
||
multiple protection mods.
|
||
* `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)
|
||
|
||
### Other registration functions
|
||
* `minetest.register_chatcommand(cmd, chatcommand definition)`
|
||
* Adds definition to minetest.registered_chatcommands
|
||
* `minetest.override_chatcommand(name, redefinition)`
|
||
* Overrides fields of a chatcommand registered with register_chatcommand.
|
||
* `minetest.unregister_chatcommand(name)`
|
||
* Unregisters a chatcommands registered with register_chatcommand.
|
||
* `minetest.register_privilege(name, definition)`
|
||
* `definition`: `"description text"`
|
||
* `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.
|
||
* `minetest.register_authentication_handler(handler)`
|
||
* See `minetest.builtin_auth_handler` in `builtin.lua` for reference
|
||
|
||
### Setting-related
|
||
* `minetest.setting_set(name, value)`
|
||
* Setting names can't contain whitespace or any of `="{}#`.
|
||
* Setting values can't contain the sequence `\n"""`.
|
||
* Setting names starting with "secure." can't be set.
|
||
* `minetest.setting_get(name)`: returns string or `nil`
|
||
* `minetest.setting_setbool(name, value)`
|
||
* See documentation on `setting_set` for restrictions.
|
||
* `minetest.setting_getbool(name)`: returns boolean or `nil`
|
||
* `minetest.setting_get_pos(name)`: returns position or nil
|
||
* `minetest.setting_save()`, returns `nil`, save all settings to config file
|
||
|
||
### Authentication
|
||
* `minetest.notify_authentication_modified(name)`
|
||
* Should be called by the authentication handler if privileges changes.
|
||
* To report everybody, set `name=nil`.
|
||
* `minetest.check_password_entry(name, entry, password)`
|
||
* Returns true if the "db entry" for a player with name matches given
|
||
* password, false otherwise.
|
||
* The "db entry" is the usually player-individual value that is derived
|
||
* from the player's chosen password and stored on the server in order to allow
|
||
* authentication whenever the player desires to log in.
|
||
* Only use this function for making it possible to log in via the password from
|
||
* via protocols like IRC, other uses for inside the game are frowned upon.
|
||
* `minetest.get_password_hash(name, raw_password)`
|
||
* Convert a name-password pair to a password hash that Minetest can use.
|
||
* The returned value alone is not a good basis for password checks based
|
||
* on comparing the password hash in the database with the password hash
|
||
* from the function, with an externally provided password, as the hash
|
||
* in the db might use the new SRP verifier format.
|
||
* For this purpose, use minetest.check_password_entry instead.
|
||
* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
|
||
* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
|
||
* Convert between two privilege representations
|
||
* `minetest.set_player_password(name, password_hash)`
|
||
* `minetest.set_player_privs(name, {priv1=true,...})`
|
||
* `minetest.get_player_privs(name) -> {priv1=true,...}`
|
||
* `minetest.auth_reload()`
|
||
* `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs`
|
||
* A quickhand for checking privileges.
|
||
* `player_or_name`: Either a Player object or the name of a player.
|
||
* `...` is either a list of strings, e.g. `"priva", "privb"` or
|
||
a table, e.g. `{ priva = true, privb = true }`.
|
||
* `minetest.get_player_ip(name)`: returns an IP address string
|
||
|
||
`minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs`
|
||
and `minetest.auth_reload` call the authetification handler.
|
||
|
||
### Chat
|
||
* `minetest.chat_send_all(text)`
|
||
* `minetest.chat_send_player(name, text)`
|
||
|
||
### 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.swap_node(pos, node)`
|
||
* Set node at position, but don't remove metadata
|
||
* `minetest.remove_node(pos)`
|
||
* Equivalent to `set_node(pos, "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}`
|
||
for unloaded areas.
|
||
* `minetest.get_node_or_nil(pos)`
|
||
* Same as `get_node` but returns `nil` for unloaded areas.
|
||
* `minetest.get_node_light(pos, timeofday)`
|
||
* Gets the light value at the given position. Note that the light value
|
||
"inside" the node at the given position is returned, so you usually want
|
||
to get the light value of a neighbor.
|
||
* `pos`: The position where to measure the light.
|
||
* `timeofday`: `nil` for current time, `0` for night, `0.5` for day
|
||
* Returns a number between `0` and `15` or `nil`
|
||
* `minetest.place_node(pos, node)`
|
||
* Place node with the same effects that a player would cause
|
||
* `minetest.dig_node(pos)`
|
||
* Dig node with the same effects that a player would cause
|
||
* Returns `true` if successful, `false` on failure (e.g. protected location)
|
||
* `minetest.punch_node(pos)`
|
||
* Punch node with the same effects that a player would cause
|
||
|
||
* `minetest.find_nodes_with_meta(pos1, pos2)`
|
||
* Get a table of positions of nodes that have metadata within a region {pos1, pos2}
|
||
* `minetest.get_meta(pos)`
|
||
* Get a `NodeMetaRef` at that position
|
||
* `minetest.get_node_timer(pos)`
|
||
* Get `NodeTimerRef`
|
||
|
||
* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at position
|
||
* Returns `ObjectRef`, or `nil` if failed
|
||
* `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)`
|
||
* `radius`: using an euclidean metric
|
||
* `minetest.set_timeofday(val)`
|
||
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
|
||
* `minetest.get_timeofday()`
|
||
* `minetest.get_gametime()`: returns the time, in seconds, since the world was created
|
||
* `minetest.get_day_count()`: returns number days elapsed since world was created,
|
||
* accounting for time changes.
|
||
* `minetest.find_node_near(pos, radius, nodenames)`: returns pos or `nil`
|
||
* `radius`: using a maximum metric
|
||
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
|
||
* `minetest.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
|
||
* `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
|
||
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
|
||
* `minetest.get_perlin(noiseparams)`
|
||
* `minetest.get_perlin(seeddiff, octaves, persistence, scale)`
|
||
* Return world-specific perlin noise (`int(worldseed)+seeddiff`)
|
||
* `minetest.get_voxel_manip([pos1, pos2])`
|
||
* Return voxel manipulator object.
|
||
* Loads the manipulator from the map if positions are passed.
|
||
* `minetest.set_gen_notify(flags, {deco_ids})`
|
||
* Set the types of on-generate notifications that should be collected
|
||
* `flags` is a flag field with the available flags: `dungeon`, `temple`, `cave_begin`,
|
||
`cave_end`, `large_cave_begin`, `large_cave_end`, `decoration`
|
||
* The second parameter is a list of IDS of decorations which notification is requested for
|
||
* `get_gen_notify()`: returns a flagstring and a table with the deco_ids
|
||
* `minetest.get_mapgen_object(objectname)`
|
||
* Return requested mapgen object if available (see "Mapgen objects")
|
||
* `minetest.get_biome_id(biome_name)`
|
||
* Returns the biome id, as used in the biomemap Mapgen object, for a
|
||
given biome_name string.
|
||
* `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing
|
||
`mgname`, `seed`, `chunksize`, `water_level`, and `flags`.
|
||
* Deprecated: use minetest.get_mapgen_setting(name) instead
|
||
* `minetest.set_mapgen_params(MapgenParams)`
|
||
* Deprecated: use minetest.set_mapgen_setting(name, value, override) instead
|
||
* Set map generation parameters
|
||
* Function cannot be called after the registration period; only initialization
|
||
and `on_mapgen_init`
|
||
* Takes a table as an argument with the fields `mgname`, `seed`, `water_level`,
|
||
and `flags`.
|
||
* Leave field unset to leave that parameter unchanged
|
||
* `flags` contains a comma-delimited string of flags to set,
|
||
or if the prefix `"no"` is attached, clears instead.
|
||
* `flags` is in the same format and has the same options as `mg_flags` in `minetest.conf`
|
||
* `minetest.get_mapgen_setting(name)`
|
||
* Gets the *active* mapgen setting (or nil if none exists) in string format with the following
|
||
order of precedence:
|
||
1) Settings loaded from map_meta.txt or overrides set during mod execution
|
||
2) Settings set by mods without a metafile override
|
||
3) Settings explicitly set in the user config file, minetest.conf
|
||
4) Settings set as the user config default
|
||
* `minetest.get_mapgen_setting_noiseparams(name)`
|
||
* Same as above, but returns the value as a NoiseParams table if the setting `name` exists
|
||
and is a valid NoiseParams
|
||
* `minetest.set_mapgen_setting(name, value, [override_meta])`
|
||
* Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting
|
||
is not already present in map_meta.txt.
|
||
* `override_meta` is an optional boolean (default: `false`). If this is set to true,
|
||
the setting will become the active setting regardless of the map metafile contents.
|
||
* Note: to set the seed, use "seed", not "fixed_map_seed"
|
||
* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])`
|
||
* Same as above, except value is a NoiseParams table.
|
||
* `minetest.set_noiseparams(name, noiseparams, set_default)`
|
||
* Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`.
|
||
* `set_default` is an optional boolean (default: `true`) that specifies whether the setting
|
||
should be applied to the default config or current active config
|
||
* `minetest.get_noiseparams(name)`: returns a table of the noiseparams for name
|
||
* `minetest.generate_ores(vm, pos1, pos2)`
|
||
* Generate all registered ores within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
|
||
* `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
|
||
* `minetest.generate_decorations(vm, pos1, pos2)`
|
||
* Generate all registered decorations within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
|
||
* `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
|
||
* `minetest.clear_objects([options])`
|
||
* Clear all objects in the environment
|
||
* Takes an optional table as an argument with the field `mode`.
|
||
* mode = `"full"`: Load and go through every mapblock, clearing objects (default).
|
||
* mode = `"quick"`: Clear objects immediately in loaded mapblocks;
|
||
clear objects in unloaded mapblocks only when the mapblocks are next activated.
|
||
* `minetest.emerge_area(pos1, pos2, [callback], [param])`
|
||
* Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be asynchronously
|
||
* fetched from memory, loaded from disk, or if inexistent, generates them.
|
||
* If `callback` is a valid Lua function, this will be called for each block emerged.
|
||
* The function signature of callback is:
|
||
* `function EmergeAreaCallback(blockpos, action, calls_remaining, param)`
|
||
* - `blockpos` is the *block* coordinates of the block that had been emerged
|
||
* - `action` could be one of the following constant values:
|
||
* `core.EMERGE_CANCELLED`, `core.EMERGE_ERRORED`, `core.EMERGE_FROM_MEMORY`,
|
||
* `core.EMERGE_FROM_DISK`, `core.EMERGE_GENERATED`
|
||
* - `calls_remaining` is the number of callbacks to be expected after this one
|
||
* - `param` is the user-defined parameter passed to emerge_area (or nil if the
|
||
* parameter was absent)
|
||
* `minetest.delete_area(pos1, pos2)`
|
||
* delete all mapblocks in the area from pos1 to pos2, inclusive
|
||
* `minetest.line_of_sight(pos1, pos2, stepsize)`: returns `boolean, pos`
|
||
* Check if there is a direct line of sight between `pos1` and `pos2`
|
||
* Returns the position of the blocking node when `false`
|
||
* `pos1`: First position
|
||
* `pos2`: Second position
|
||
* `stepsize`: smaller gives more accurate results but requires more computing
|
||
time. Default is `1`.
|
||
* `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`
|
||
* `pos1`: start position
|
||
* `pos2`: end position
|
||
* `searchdistance`: number of blocks to search in each direction using a maximum metric
|
||
* `max_jump`: maximum height difference to consider walkable
|
||
* `max_drop`: maximum height difference to consider droppable
|
||
* `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`
|
||
* `minetest.spawn_tree (pos, {treedef})`
|
||
* spawns L-system tree at given `pos` with definition in `treedef` table
|
||
* Warning: L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
|
||
Often these bugs appear as subtle shadows in water.
|
||
* `minetest.transforming_liquid_add(pos)`
|
||
* add node to liquid update queue
|
||
* `minetest.get_node_max_level(pos)`
|
||
* get max available level for leveled node
|
||
* `minetest.get_node_level(pos)`
|
||
* get level of leveled node (water, snow)
|
||
* `minetest.set_node_level(pos, level)`
|
||
* set level of leveled node, default `level` equals `1`
|
||
* if `totallevel > maxlevel`, returns rest (`total-max`).
|
||
* `minetest.add_node_level(pos, level)`
|
||
* increase level of leveled node by level, default `level` equals `1`
|
||
* if `totallevel > maxlevel`, returns rest (`total-max`)
|
||
* can be negative for decreasing
|
||
* `core.check_single_for_falling(pos)`
|
||
* causes an unsupported `group:falling_node` node to fall and causes an
|
||
unattached `group:attached_node` node to fall.
|
||
* does not spread these updates to neighbours.
|
||
* `core.check_for_falling(pos)`
|
||
* causes an unsupported `group:falling_node` node to fall and causes an
|
||
unattached `group:attached_node` node to fall.
|
||
* spread these updates to neighbours and can cause a cascade
|
||
of nodes to fall.
|
||
|
||
### Inventory
|
||
`minetest.get_inventory(location)`: returns an `InvRef`
|
||
|
||
* `location` = e.g.
|
||
* `{type="player", name="celeron55"}`
|
||
* `{type="node", pos={x=, y=, z=}}`
|
||
* `{type="detached", name="creative"}`
|
||
* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef`
|
||
* callbacks: See "Detached inventory callbacks"
|
||
* player_name: Make detached inventory available to one player exclusively,
|
||
by default they will be sent to every player (even if not used).
|
||
Note that this parameter is mostly just a workaround and will be removed in future releases.
|
||
* Creates a detached inventory. If it already exists, it is cleared.
|
||
* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
|
||
returns left over ItemStack
|
||
* See `minetest.item_eat` and `minetest.register_on_item_eat`
|
||
|
||
### Formspec
|
||
* `minetest.show_formspec(playername, formname, formspec)`
|
||
* `playername`: name of player to show formspec
|
||
* `formname`: name passed to `on_player_receive_fields` callbacks.
|
||
It should follow the `"modname:<whatever>"` naming convention
|
||
* `formspec`: formspec to display
|
||
* `minetest.close_formspec(playername, formname)`
|
||
* `playername`: name of player to close formspec
|
||
* `formname`: has to exactly match the one given in show_formspec, or the formspec will
|
||
not close.
|
||
* calling show_formspec(playername, formname, "") is equal to this expression
|
||
* to close a formspec regardless of the formname, call
|
||
minetest.close_formspec(playername, ""). USE THIS ONLY WHEN ABSOLUTELY NECESSARY!
|
||
* `minetest.formspec_escape(string)`: returns a string
|
||
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
|
||
* `minetest.explode_table_event(string)`: returns a table
|
||
* returns e.g. `{type="CHG", row=1, column=2}`
|
||
* `type` is one of:
|
||
* `"INV"`: no row selected)
|
||
* `"CHG"`: selected)
|
||
* `"DCL"`: double-click
|
||
* `minetest.explode_textlist_event(string)`: returns a table
|
||
* returns e.g. `{type="CHG", index=1}`
|
||
* `type` is one of:
|
||
* `"INV"`: no row selected)
|
||
* `"CHG"`: selected)
|
||
* `"DCL"`: double-click
|
||
* `minetest.explode_scrollbar_event(string)`: returns a table
|
||
* returns e.g. `{type="CHG", value=500}`
|
||
* `type` is one of:
|
||
* `"INV"`: something failed
|
||
* `"CHG"`: has been changed
|
||
* `"VAL"`: not changed
|
||
|
||
### Item handling
|
||
* `minetest.inventorycube(img1, img2, img3)`
|
||
* Returns a string for making an image of a cube (useful as an item image)
|
||
* `minetest.get_pointed_thing_position(pointed_thing, above)`
|
||
* Get position of a `pointed_thing` (that you can get from somewhere)
|
||
* `minetest.dir_to_facedir(dir, is6d)`
|
||
* Convert a vector to a facedir value, used in `param2` for `paramtype2="facedir"`;
|
||
* passing something non-`nil`/`false` for the optional second parameter causes it to
|
||
take the y component into account
|
||
* `minetest.facedir_to_dir(facedir)`
|
||
* Convert a facedir back into a vector aimed directly out the "back" of a node
|
||
* `minetest.dir_to_wallmounted(dir)`
|
||
* Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"`
|
||
* `minetest.wallmounted_to_dir(wallmounted)`
|
||
* Convert a wallmounted value back into a vector aimed directly out the "back" of a node
|
||
* `minetest.get_node_drops(nodename, toolname)`
|
||
* Returns list of item names.
|
||
* **Note**: This will be removed or modified in a future version.
|
||
* `minetest.get_craft_result(input)`: returns `output, decremented_input`
|
||
* `input.method` = `"normal"` or `"cooking"` or `"fuel"`
|
||
* `input.width` = for example `3`
|
||
* `input.items` = for example
|
||
`{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
|
||
* `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack`
|
||
* `output.time` = a number, if unsuccessful: `0`
|
||
* `output.replacements` = list of `ItemStack`s that couldn't be placed in
|
||
`decremented_input.items`
|
||
* `decremented_input` = like `input`
|
||
* `minetest.get_craft_recipe(output)`: returns input
|
||
* returns last registered recipe for output item (node)
|
||
* `output` is a node or item type such as `"default:torch"`
|
||
* `input.method` = `"normal"` or `"cooking"` or `"fuel"`
|
||
* `input.width` = for example `3`
|
||
* `input.items` = for example
|
||
`{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
|
||
* `input.items` = `nil` if no recipe found
|
||
* `minetest.get_all_craft_recipes(query item)`: returns a table or `nil`
|
||
* returns indexed table with all registered recipes for query item (node)
|
||
or `nil` if no recipe was found
|
||
* recipe entry table:
|
||
{
|
||
method = 'normal' or 'cooking' or 'fuel'
|
||
width = 0-3, 0 means shapeless recipe
|
||
items = indexed [1-9] table with recipe items
|
||
output = string with item name and quantity
|
||
}
|
||
* Example query for `"default:gold_ingot"` will return table:
|
||
{
|
||
[1]={type = "cooking", width = 3, output = "default:gold_ingot",
|
||
items = {1 = "default:gold_lump"}},
|
||
[2]={type = "normal", width = 1, output = "default:gold_ingot 9",
|
||
items = {1 = "default:goldblock"}}
|
||
}
|
||
* `minetest.handle_node_drops(pos, drops, digger)`
|
||
* `drops`: list of itemstrings
|
||
* Handles drops from nodes after digging: Default action is to put them into
|
||
digger's inventory
|
||
* Can be overridden to get different functionality (e.g. dropping items on
|
||
ground)
|
||
|
||
### Rollback
|
||
* `minetest.rollback_get_node_actions(pos, range, seconds, limit)`:
|
||
returns `{{actor, pos, time, oldnode, newnode}, ...}`
|
||
* Find who has done something to a node, or near a node
|
||
* `actor`: `"player:<name>"`, also `"liquid"`.
|
||
* `minetest.rollback_revert_actions_by(actor, seconds)`: returns `boolean, log_messages`
|
||
* Revert latest actions of someone
|
||
* `actor`: `"player:<name>"`, also `"liquid"`.
|
||
|
||
### Defaults for the `on_*` item definition functions
|
||
These functions return the leftover itemstack.
|
||
|
||
* `minetest.item_place_node(itemstack, placer, pointed_thing, param2)`
|
||
* Place item as a node
|
||
* `param2` overrides `facedir` and wallmounted `param2`
|
||
* returns `itemstack, success`
|
||
* `minetest.item_place_object(itemstack, placer, pointed_thing)`
|
||
* Place item as-is
|
||
* `minetest.item_place(itemstack, placer, pointed_thing, param2)`
|
||
* Use one of the above based on what the item is.
|
||
* Calls `on_rightclick` of `pointed_thing.under` if defined instead
|
||
* **Note**: is not called when wielded item overrides `on_place`
|
||
* `param2` overrides `facedir` and wallmounted `param2`
|
||
* returns `itemstack, success`
|
||
* `minetest.item_drop(itemstack, dropper, pos)`
|
||
* Drop the item
|
||
* `minetest.item_eat(hp_change, replace_with_item)`
|
||
* Eat the item.
|
||
* `replace_with_item` is the itemstring which is added to the inventory.
|
||
If the player is eating a stack, then replace_with_item goes to a
|
||
different spot. Can be `nil`
|
||
* See `minetest.do_item_eat`
|
||
|
||
### Defaults for the `on_punch` and `on_dig` node definition callbacks
|
||
* `minetest.node_punch(pos, node, puncher, pointed_thing)`
|
||
* Calls functions registered by `minetest.register_on_punchnode()`
|
||
* `minetest.node_dig(pos, node, digger)`
|
||
* Checks if node can be dug, puts item into inventory, removes node
|
||
* Calls functions registered by `minetest.registered_on_dignodes()`
|
||
|
||
### Sounds
|
||
* `minetest.sound_play(spec, parameters)`: returns a handle
|
||
* `spec` is a `SimpleSoundSpec`
|
||
* `parameters` is a sound parameter table
|
||
* `minetest.sound_stop(handle)`
|
||
|
||
### Timing
|
||
* `minetest.after(time, func, ...)`
|
||
* Call the function `func` after `time` seconds, may be fractional
|
||
* Optional: Variable number of arguments that are passed to `func`
|
||
|
||
### Server
|
||
* `minetest.request_shutdown([message],[reconnect])`: request for server shutdown. Will display `message` to clients,
|
||
and `reconnect` == true displays a reconnect button.
|
||
* `minetest.get_server_status()`: returns server status string
|
||
* `minetest.get_server_uptime()`: returns the server uptime in seconds
|
||
|
||
### Bans
|
||
* `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`)
|
||
* `minetest.get_ban_description(ip_or_name)`: returns ban description (string)
|
||
* `minetest.ban_player(name)`: ban a player
|
||
* `minetest.unban_player_or_ip(name)`: unban player or IP address
|
||
* `minetest.kick_player(name, [reason])`: disconnect a player with a optional reason
|
||
|
||
### Particles
|
||
* `minetest.add_particle(particle definition)`
|
||
* Deprecated: `minetest.add_particle(pos, velocity, acceleration, expirationtime,
|
||
size, collisiondetection, texture, playername)`
|
||
|
||
* `minetest.add_particlespawner(particlespawner definition)`
|
||
* Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
|
||
* Returns an `id`, and -1 if adding didn't succeed
|
||
* `Deprecated: minetest.add_particlespawner(amount, time,
|
||
minpos, maxpos,
|
||
minvel, maxvel,
|
||
minacc, maxacc,
|
||
minexptime, maxexptime,
|
||
minsize, maxsize,
|
||
collisiondetection, texture, playername)`
|
||
|
||
* `minetest.delete_particlespawner(id, player)``
|
||
* Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
|
||
* If playername is specified, only deletes on the player's client,
|
||
* otherwise on all clients
|
||
|
||
### 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`.
|
||
* `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).
|
||
* 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.
|
||
* If slice probability list equals `nil`, no slice probabilities are applied.
|
||
* Saves schematic in the Minetest Schematic format to filename.
|
||
|
||
* `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement)`
|
||
* Place the schematic specified by schematic (see: Schematic specifier) at `pos`.
|
||
* `rotation` can equal `"0"`, `"90"`, `"180"`, `"270"`, or `"random"`.
|
||
* If the `rotation` parameter is omitted, the schematic is not rotated.
|
||
* `replacements` = `{["old_name"] = "convert_to", ...}`
|
||
* `force_placement` is a boolean indicating whether nodes other than `air` and
|
||
`ignore` are replaced by the schematic
|
||
* Returns nil if the schematic could not be loaded.
|
||
|
||
* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)`:
|
||
* This function is analagous to minetest.place_schematic, but places a schematic onto the
|
||
specified VoxelManip object `vmanip` instead of the whole map.
|
||
* Returns false if any part of the schematic was cut-off due to the VoxelManip not
|
||
containing the full area required, and true if the whole schematic was able to fit.
|
||
* Returns nil if the schematic could not be loaded.
|
||
* After execution, any external copies of the VoxelManip contents are invalidated.
|
||
|
||
* `minetest.serialize_schematic(schematic, format, options)`
|
||
* Return the serialized schematic specified by schematic (see: Schematic specifier)
|
||
* in the `format` of either "mts" or "lua".
|
||
* "mts" - a string containing the binary MTS data used in the MTS file format
|
||
* "lua" - a string containing Lua code representing the schematic in table format
|
||
* `options` is a table containing the following optional parameters:
|
||
* If `lua_use_comments` is true and `format` is "lua", the Lua code generated will have (X, Z)
|
||
* position comments for every X row generated in the schematic data for easier reading.
|
||
* If `lua_num_indent_spaces` is a nonzero number and `format` is "lua", the Lua code generated
|
||
* will use that number of spaces as indentation instead of a tab character.
|
||
|
||
### HTTP Requests:
|
||
* `minetest.request_http_api()`:
|
||
* returns `HTTPApiTable` containing http functions if the calling mod has been granted
|
||
access by being listed in the `secure.http_mods` or `secure.trusted_mods` setting,
|
||
otherwise returns `nil`.
|
||
* The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get`
|
||
described below.
|
||
* Only works at init time and must be called from the mod's main scope (not from a function).
|
||
* Function only exists if minetest server was built with cURL support.
|
||
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
|
||
A LOCAL VARIABLE!**
|
||
* `HTTPApiTable.fetch(HTTPRequest req, callback)`
|
||
* Performs given request asynchronously and calls callback upon completion
|
||
* callback: `function(HTTPRequestResult res)`
|
||
* Use this HTTP function if you are unsure, the others are for advanced use.
|
||
* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
|
||
* Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get`
|
||
* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
|
||
* Return response data for given asynchronous HTTP request
|
||
|
||
### Misc.
|
||
* `minetest.get_connected_players()`: returns list of `ObjectRefs`
|
||
* `minetest.player_exists(name)`: boolean, whether player exists (regardless of online status)
|
||
* `minetest.hud_replace_builtin(name, hud_definition)`
|
||
* 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
|
||
* 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`
|
||
* `minetest.get_item_group(name, group)`: returns a rating
|
||
* Get rating of a group of an item. (`0` means: not in group)
|
||
* `minetest.get_node_group(name, group)`: returns a rating
|
||
* Deprecated: An alias for the former.
|
||
* `minetest.raillike_group(name)`: returns a rating
|
||
* Returns rating of the connect_to_raillike group corresponding to name
|
||
* If name is not yet the name of a connect_to_raillike group, a new group id
|
||
* is created, with that name
|
||
* `minetest.get_content_id(name)`: returns an integer
|
||
* Gets the internal content ID of `name`
|
||
* `minetest.get_name_from_content_id(content_id)`: returns a string
|
||
* Gets the name of the content with that content ID
|
||
* `minetest.parse_json(string[, nullvalue])`: returns something
|
||
* Convert a string containing JSON data into the Lua equivalent
|
||
* `nullvalue`: returned in place of the JSON null; defaults to `nil`
|
||
* On success returns a table, a string, a number, a boolean or `nullvalue`
|
||
* On failure outputs an error message and returns `nil`
|
||
* Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
|
||
* `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
|
||
* Convert a Lua table into a JSON string
|
||
* styled: Outputs in a human-readable format if this is set, defaults to false
|
||
* Unserializable things like functions and userdata are saved as null.
|
||
* **Warning**: JSON is more strict than the Lua table format.
|
||
1. You can only use strings and positive integers of at least one as keys.
|
||
2. You can not mix string and integer keys.
|
||
This is due to the fact that JSON has two distinct array and object values.
|
||
* Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
|
||
* `minetest.serialize(table)`: returns a string
|
||
* Convert a table containing tables, strings, numbers, booleans and `nil`s
|
||
into string form readable by `minetest.deserialize`
|
||
* Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
|
||
* `minetest.deserialize(string)`: returns a table
|
||
* Convert a string returned by `minetest.deserialize` into a table
|
||
* `string` is loaded in an empty sandbox environment.
|
||
* Will load functions, but they cannot access the global environment.
|
||
* Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
|
||
* Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
|
||
* `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
|
||
* `minetest.compress(data, method, ...)`: returns `compressed_data`
|
||
* Compress a string of data.
|
||
* `method` is a string identifying the compression method to be used.
|
||
* Supported compression methods:
|
||
* Deflate (zlib): `"deflate"`
|
||
* `...` indicates method-specific arguments. Currently defined arguments are:
|
||
* Deflate: `level` - Compression level, `0`-`9` or `nil`.
|
||
* `minetest.decompress(compressed_data, method, ...)`: returns data
|
||
* Decompress a string of data (using ZLib).
|
||
* See documentation on `minetest.compress()` for supported compression methods.
|
||
* currently supported.
|
||
* `...` indicates method-specific arguments. Currently, no methods use this.
|
||
* `minetest.encode_base64(string)`: returns string encoded in base64
|
||
* Encodes a string in base64.
|
||
* `minetest.decode_base64(string)`: returns string
|
||
* Decodes a string encoded in base64.
|
||
* `minetest.is_protected(pos, name)`: returns boolean
|
||
* Returns true, if player `name` shouldn't be abled to dig at `pos` or do other
|
||
actions, defineable by mods, due to some mod-defined ownership-like concept.
|
||
Returns false or nil, if the player is allowed to do such actions.
|
||
* This function should be overridden by protection mods and should be used to
|
||
check if a player can interact at a position.
|
||
* This function should call the old version of itself if the position is not
|
||
protected by the mod.
|
||
* Example:
|
||
|
||
local old_is_protected = minetest.is_protected
|
||
function minetest.is_protected(pos, name)
|
||
if mymod:position_protected_from(pos, name) then
|
||
return true
|
||
end
|
||
return old_is_protected(pos, name)
|
||
end
|
||
* `minetest.record_protection_violation(pos, name)`
|
||
* This function calls functions registered with
|
||
`minetest.register_on_protection_violation`.
|
||
* `minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)`
|
||
* Attempt to predict the desired orientation of the facedir-capable node
|
||
defined by `itemstack`, and place it accordingly (on-wall, on the floor, or
|
||
hanging from the ceiling). Stacks are handled normally if the `infinitestacks`
|
||
field is false or omitted (else, the itemstack is not changed). `orient_flags`
|
||
is an optional table containing extra tweaks to the placement code:
|
||
* `invert_wall`: if `true`, place wall-orientation on the ground and ground-
|
||
orientation on the wall.
|
||
* `force_wall` : if `true`, always place the node in wall orientation.
|
||
* `force_ceiling`: if `true`, always place on the ceiling.
|
||
* `force_floor`: if `true`, always place the node on the floor.
|
||
* `force_facedir`: if `true`, forcefully reset the facedir to north when placing on
|
||
the floor or ceiling
|
||
* The first four options are mutually-exclusive; the last in the list takes
|
||
precedence over the first.
|
||
* `minetest.rotate_node(itemstack, placer, pointed_thing)`
|
||
* calls `rotate_and_place()` with infinitestacks set according to the state of
|
||
the creative mode setting, and checks for "sneak" to set the `invert_wall`
|
||
parameter.
|
||
|
||
* `minetest.forceload_block(pos[, transient])`
|
||
* forceloads the position `pos`.
|
||
* returns `true` if area could be forceloaded
|
||
* If `transient` is `false` or absent, the forceload will be persistent
|
||
(saved between server runs). If `true`, the forceload will be transient
|
||
(not saved between server runs).
|
||
|
||
* `minetest.forceload_free_block(pos[, transient])`
|
||
* stops forceloading the position `pos`
|
||
* If `transient` is `false` or absent, frees a persistent forceload.
|
||
If `true`, frees a transient forceload.
|
||
|
||
* `minetest.request_insecure_environment()`: returns an environment containing
|
||
insecure functions if the calling mod has been listed as trusted in the
|
||
`secure.trusted_mods` setting or security is disabled, otherwise returns `nil`.
|
||
* Only works at init time and must be called from the mod's main scope (not from a function).
|
||
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN
|
||
A LOCAL VARIABLE!**
|
||
|
||
* `minetest.global_exists(name)`
|
||
* Checks if a global variable has been set, without triggering a warning.
|
||
|
||
### Global objects
|
||
* `minetest.env`: `EnvRef` of the server environment and world.
|
||
* Any function in the minetest namespace can be called using the syntax
|
||
`minetest.env:somefunction(somearguments)`
|
||
instead of `minetest.somefunction(somearguments)`
|
||
* Deprecated, but support is not to be dropped soon
|
||
|
||
### Global tables
|
||
* `minetest.registered_items`
|
||
* Map of registered items, indexed by name
|
||
* `minetest.registered_nodes`
|
||
* Map of registered node definitions, indexed by name
|
||
* `minetest.registered_craftitems`
|
||
* Map of registered craft item definitions, indexed by name
|
||
* `minetest.registered_tools`
|
||
* Map of registered tool definitions, indexed by name
|
||
* `minetest.registered_entities`
|
||
* Map of registered entity prototypes, indexed by name
|
||
* `minetest.object_refs`
|
||
* Map of object references, indexed by active object id
|
||
* `minetest.luaentities`
|
||
* Map of Lua entities, indexed by active object id
|
||
* `minetest.registered_chatcommands`
|
||
* Map of registered chat command definitions, indexed by name
|
||
* `minetest.registered_ores`
|
||
* List of registered ore definitions.
|
||
* `minetest.registered_biomes`
|
||
* List of registered biome definitions.
|
||
* `minetest.registered_decorations`
|
||
* List of registered decoration definitions.
|
||
|
||
Class reference
|
||
---------------
|
||
|
||
### `NodeMetaRef`
|
||
Node metadata: reference extra data and functionality stored in a node.
|
||
Can be gotten via `minetest.get_meta(pos)`.
|
||
|
||
#### Methods
|
||
* `set_string(name, value)`
|
||
* `get_string(name)`
|
||
* `set_int(name, value)`
|
||
* `get_int(name)`
|
||
* `set_float(name, value)`
|
||
* `get_float(name)`
|
||
* `get_inventory()`: returns `InvRef`
|
||
* `to_table()`: returns `nil` or `{fields = {...}, inventory = {list1 = {}, ...}}`
|
||
* `from_table(nil or {})`
|
||
* to clear metadata, use from_table(nil)
|
||
* See "Node Metadata"
|
||
|
||
### `NodeTimerRef`
|
||
Node Timers: a high resolution persistent per-node timer.
|
||
Can be gotten via `minetest.get_node_timer(pos)`.
|
||
|
||
#### Methods
|
||
* `set(timeout,elapsed)`
|
||
* set a timer's state
|
||
* `timeout` is in seconds, and supports fractional values (0.1 etc)
|
||
* `elapsed` is in seconds, and supports fractional values (0.1 etc)
|
||
* will trigger the node's `on_timer` function after `timeout`-elapsed seconds
|
||
* `start(timeout)`
|
||
* start a timer
|
||
* equivalent to `set(timeout,0)`
|
||
* `stop()`
|
||
* stops the timer
|
||
* `get_timeout()`: returns current timeout in seconds
|
||
* if `timeout` equals `0`, timer is inactive
|
||
* `get_elapsed()`: returns current elapsed time in seconds
|
||
* the node's `on_timer` function will be called after `timeout`-elapsed seconds
|
||
* `is_started()`: returns boolean state of timer
|
||
* returns `true` if timer is started, otherwise `false`
|
||
|
||
### `ObjectRef`
|
||
Moving things in the game are generally these.
|
||
|
||
This is basically a reference to a C++ `ServerActiveObject`
|
||
|
||
#### Methods
|
||
* `remove()`: remove object (after returning from Lua)
|
||
* Note: Doesn't work on players, use minetest.kick_player instead
|
||
* `get_pos()`: returns `{x=num, y=num, z=num}`
|
||
* `set_pos(pos)`; `pos`=`{x=num, y=num, z=num}`
|
||
* `move_to(pos, continuous=false)`: interpolated move
|
||
* `punch(puncher, time_from_last_punch, tool_capabilities, direction)`
|
||
* `puncher` = another `ObjectRef`,
|
||
* `time_from_last_punch` = time since last punch action of the puncher
|
||
* `direction`: can be `nil`
|
||
* `right_click(clicker)`; `clicker` is another `ObjectRef`
|
||
* `get_hp()`: returns number of hitpoints (2 * number of hearts)
|
||
* `set_hp(hp)`: set number of hitpoints (2 * number of hearts)
|
||
* `get_inventory()`: returns an `InvRef`
|
||
* `get_wield_list()`: returns the name of the inventory list the wielded item is in
|
||
* `get_wield_index()`: returns the index of the wielded item
|
||
* `get_wielded_item()`: returns an `ItemStack`
|
||
* `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)`
|
||
* `get_animation()`: returns range, frame_speed, frame_blend and frame_loop
|
||
* `set_attach(parent, bone, position, rotation)`
|
||
* `bone`: string
|
||
* `position`: `{x=num, y=num, z=num}` (relative)
|
||
* `rotation`: `{x=num, y=num, z=num}`
|
||
* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't attached
|
||
* `set_detach()`
|
||
* `set_bone_position(bone, position, rotation)`
|
||
* `bone`: string
|
||
* `position`: `{x=num, y=num, z=num}` (relative)
|
||
* `rotation`: `{x=num, y=num, z=num}`
|
||
* `get_bone_position(bone)`: returns position and rotation of the bone
|
||
* `set_properties(object property table)`
|
||
* `get_properties()`: returns object property table
|
||
* `is_player()`: returns true for players, false otherwise
|
||
* `get_nametag_attributes()`
|
||
* returns a table with the attributes of the nametag of an object
|
||
* {
|
||
color = {a=0..255, r=0..255, g=0..255, b=0..255},
|
||
text = "",
|
||
}
|
||
* `set_nametag_attributes(attributes)`
|
||
* sets the attributes of the nametag of an object
|
||
* `attributes`:
|
||
{
|
||
color = ColorSpec,
|
||
text = "My Nametag",
|
||
}
|
||
|
||
##### LuaEntitySAO-only (no-op for other objects)
|
||
* `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_yaw(radians)`
|
||
* `get_yaw()`: returns number in radians
|
||
* `set_texture_mod(mod)`
|
||
* `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
|
||
* `get_entity_name()` (**Deprecated**: Will be removed in a future version)
|
||
* `get_luaentity()`
|
||
|
||
##### Player-only (no-op for other objects)
|
||
* `get_player_name()`: returns `""` if is not a player
|
||
* `get_player_velocity()`: returns `nil` if is not a player, otherwise a
|
||
table {x, y, z} representing the player's instantaneous velocity in nodes/s
|
||
* `get_look_dir()`: get camera direction as a unit vector
|
||
* `get_look_vertical()`: pitch in radians
|
||
* Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.
|
||
* `get_look_horizontal()`: yaw in radians
|
||
* Angle is counter-clockwise from the +z direction.
|
||
* `set_look_vertical(radians)`: sets look pitch
|
||
* radians - Angle from looking forward, where positive is downwards.
|
||
* `set_look_horizontal(radians)`: sets look yaw
|
||
* radians - Angle from the +z direction, where positive is counter-clockwise.
|
||
* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use get_look_vertical.
|
||
* Angle ranges between -pi/2 and pi/2, which are straight down and up respectively.
|
||
* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use get_look_horizontal.
|
||
* Angle is counter-clockwise from the +x direction.
|
||
* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use set_look_vertical.
|
||
* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use set_look_horizontal.
|
||
* `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
|
||
* `set_inventory_formspec(formspec)`
|
||
* Redefine player's inventory form
|
||
* 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}`
|
||
* `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
|
||
* `set_physics_override(override_table)`
|
||
* `override_table` is a table with the following fields:
|
||
* `speed`: multiplier to default walking speed value (default: `1`)
|
||
* `jump`: multiplier to default jump value (default: `1`)
|
||
* `gravity`: multiplier to default gravity value (default: `1`)
|
||
* `sneak`: whether player can sneak (default: `true`)
|
||
* `sneak_glitch`: whether player can use the sneak glitch (default: `true`)
|
||
* `get_physics_override()`: returns the table given to set_physics_override
|
||
* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID
|
||
number on success
|
||
* `hud_remove(id)`: remove the HUD element of the specified id
|
||
* `hud_change(id, stat, value)`: change a value of a previously added HUD element
|
||
* 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`
|
||
* pass a table containing a `true`/`false` value of each flag to be set or unset
|
||
* if a flag equals `nil`, the flag is not modified
|
||
* note that setting `minimap` modifies the client's permission to view the minimap -
|
||
* the client may locally elect to not view the minimap
|
||
* `hud_get_flags()`: returns a table containing status of hud flags
|
||
* returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true, minimap=true }`
|
||
* `hud_set_hotbar_itemcount(count)`: sets number of items in builtin hotbar
|
||
* `count`: number of items, must be between `1` and `23`
|
||
* `hud_get_hotbar_itemcount`: returns number of visible items
|
||
* `hud_set_hotbar_image(texturename)`
|
||
* sets background image for hotbar
|
||
* `hud_get_hotbar_image`: returns texturename
|
||
* `hud_set_hotbar_selected_image(texturename)`
|
||
* sets image for selected item of hotbar
|
||
* `hud_get_hotbar_selected_image`: returns texturename
|
||
* `set_sky(bgcolor, type, {texture names})`
|
||
* `bgcolor`: ColorSpec, defaults to white
|
||
* Available types:
|
||
* `"regular"`: Uses 0 textures, `bgcolor` ignored
|
||
* `"skybox"`: Uses 6 textures, `bgcolor` used
|
||
* `"plain"`: Uses 0 textures, `bgcolor` used
|
||
* `get_sky()`: returns bgcolor, type and a table with the textures
|
||
* `override_day_night_ratio(ratio or nil)`
|
||
* `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific amount
|
||
* `nil`: Disables override, defaulting to sunlight based on day-night cycle
|
||
* `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden
|
||
* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`
|
||
|
||
set animation for player model in third person view
|
||
|
||
set_local_animation({x=0, y=79}, -- < stand/idle animation key frames
|
||
{x=168, y=187}, -- < walk animation key frames
|
||
{x=189, y=198}, -- < dig animation key frames
|
||
{x=200, y=219}, -- < walk+dig animation key frames
|
||
frame_speed=30): -- < animation frame speed
|
||
* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and frame_speed
|
||
* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for camera per player
|
||
* in first person view
|
||
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
|
||
* `get_eye_offset()`: returns offset_first and offset_third
|
||
|
||
### `InvRef`
|
||
An `InvRef` is a reference to an inventory.
|
||
|
||
#### Methods
|
||
* `is_empty(listname)`: return `true` if list is empty
|
||
* `get_size(listname)`: get size of a list
|
||
* `set_size(listname, size)`: set size of a list
|
||
* returns `false` on error (e.g. invalid `listname` or `size`)
|
||
* `get_width(listname)`: get width of a list
|
||
* `set_width(listname, width)`: set width of list; currently used for crafting
|
||
* `get_stack(listname, i)`: get a copy of stack index `i` in list
|
||
* `set_stack(listname, i, stack)`: copy `stack` to index `i` in list
|
||
* `get_list(listname)`: return full list
|
||
* `set_list(listname, list)`: set full list (size will not change)
|
||
* `get_lists()`: returns list of inventory lists
|
||
* `set_lists(lists)`: sets inventory lists (size will not change)
|
||
* `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
|
||
* `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
|
||
item this way will likely remove the wrong one -- to do that use `set_stack`
|
||
with an empty `ItemStack`
|
||
* `get_location()`: returns a location compatible to `minetest.get_inventory(location)`
|
||
* returns `{type="undefined"}` in case location is not known
|
||
|
||
### `AreaStore`
|
||
A fast access data structure to store areas, and find areas near a given position or area.
|
||
Every area has a `data` string attribute to store additional information.
|
||
You can create an empty `AreaStore` by calling `AreaStore()`, or `AreaStore(type_name)`.
|
||
If you chose the parameter-less constructor, a fast implementation will be automatically
|
||
chosen for you.
|
||
|
||
#### Methods
|
||
* `get_area(id, include_borders, include_data)`: returns the area with the id `id`.
|
||
(optional) Boolean values `include_borders` and `include_data` control what's copied.
|
||
Returns nil if specified area id does not exist.
|
||
* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain
|
||
the position `pos`. (optional) Boolean values `include_borders` and `include_data` control
|
||
what's copied.
|
||
* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`:
|
||
returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive).
|
||
If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area.
|
||
(optional) Boolean values `include_borders` and `include_data` control what's copied.
|
||
* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID,
|
||
or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area.
|
||
`data` is a string stored with the area. If passed, `id` will be used as the internal area ID,
|
||
it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it,
|
||
or insertions are likely to fail due to conflicts.
|
||
* `reserve(count)`: reserves resources for at most `count` many contained areas.
|
||
Only needed for efficiency, and only some implementations profit.
|
||
* `remove_area(id)`: removes the area with the given id from the store, returns success.
|
||
* `set_cache_params(params)`: sets params for the included prefiltering cache.
|
||
Calling invalidates the cache, so that its elements have to be newly generated.
|
||
* `params`:
|
||
{
|
||
enabled = boolean, -- whether to enable, default true
|
||
block_radius = number, -- the radius (in nodes) of the areas the cache generates
|
||
prefiltered lists for, minimum 16, default 64
|
||
limit = number, -- the cache's size, minimum 20, default 1000
|
||
}
|
||
* `to_string()`: Experimental. Returns area store serialized as a (binary) string.
|
||
* `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to a file.
|
||
* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore.
|
||
Returns success and, optionally, an error message.
|
||
* `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file.
|
||
|
||
### `ItemStack`
|
||
An `ItemStack` is a stack of items.
|
||
|
||
It can be created via `ItemStack(x)`, where x is an `ItemStack`,
|
||
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
|
||
* `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_metadata()`: Returns metadata (a string attached to an item stack).
|
||
* `set_metadata(metadata)`: 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`.
|
||
|
||
### `PseudoRandom`
|
||
A 16-bit pseudorandom number generator.
|
||
Uses a well-known LCG algorithm introduced by K&R.
|
||
|
||
It can be created via `PseudoRandom(seed)`.
|
||
|
||
#### Methods
|
||
* `next()`: return next integer random number [`0`...`32767`]
|
||
* `next(min, max)`: return next integer random number [`min`...`max`]
|
||
* `((max - min) == 32767) or ((max-min) <= 6553))` must be true
|
||
due to the simple implementation making bad distribution otherwise.
|
||
|
||
### `PcgRandom`
|
||
A 32-bit pseudorandom number generator.
|
||
Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness.
|
||
|
||
It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`.
|
||
|
||
#### Methods
|
||
* `next()`: return next integer random number [`-2147483648`...`2147483647`]
|
||
* `next(min, max)`: return next integer random number [`min`...`max`]
|
||
* `rand_normal_dist(min, max, num_trials=6)`: return normally distributed random number [`min`...`max`]
|
||
* This is only a rough approximation of a normal distribution with:
|
||
* mean = (max - min) / 2, and
|
||
* variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)
|
||
* Increasing num_trials improves accuracy of the approximation
|
||
|
||
### `SecureRandom`
|
||
Interface for the operating system's crypto-secure PRNG.
|
||
|
||
It can be created via `SecureRandom()`. The constructor returns nil if a secure random device cannot be
|
||
be found on the system.
|
||
|
||
#### Methods
|
||
* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many random bytes, as a string.
|
||
|
||
### `PerlinNoise`
|
||
A perlin noise generator.
|
||
It can be created via `PerlinNoise(seed, octaves, persistence, scale)`
|
||
or `PerlinNoise(noiseparams)`.
|
||
Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, scale)`
|
||
or `minetest.get_perlin(noiseparams)`.
|
||
|
||
#### Methods
|
||
* `get2d(pos)`: returns 2D noise value at `pos={x=,y=}`
|
||
* `get3d(pos)`: returns 3D noise value at `pos={x=,y=,z=}`
|
||
|
||
### `PerlinNoiseMap`
|
||
A fast, bulk perlin noise generator.
|
||
|
||
It can be created via `PerlinNoiseMap(noiseparams, size)` or
|
||
`minetest.get_perlin_map(noiseparams, size)`.
|
||
|
||
Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` conponent is ommitted
|
||
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
|
||
`nil` is returned).
|
||
|
||
For each of the functions with an optional `buffer` parameter: If `buffer` is not
|
||
nil, this table will be used to store the result instead of creating a new table.
|
||
|
||
|
||
#### Methods
|
||
* `get2dMap(pos)`: returns a `<size.x>` times `<size.y>` 2D array of 2D noise
|
||
with values starting at `pos={x=,y=}`
|
||
* `get3dMap(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>` 3D array
|
||
of 3D noise with values starting at `pos={x=,y=,z=}`
|
||
* `get2dMap_flat(pos, buffer)`: returns a flat `<size.x * size.y>` element array of 2D noise
|
||
with values starting at `pos={x=,y=}`
|
||
* `get3dMap_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise
|
||
* `calc2dMap(pos)`: Calculates the 2d noise map starting at `pos`. The result is stored internally.
|
||
* `calc3dMap(pos)`: Calculates the 3d noise map starting at `pos`. The result is stored internally.
|
||
* `getMapSlice(slice_offset, slice_size, buffer)`: In the form of an array, returns a slice of the
|
||
most recently computed noise results. The result slice begins at coordinates `slice_offset` and
|
||
takes a chunk of `slice_size`.
|
||
E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20:
|
||
`noisevals = noise:getMapSlice({y=20}, {y=2})`
|
||
It is important to note that `slice_offset` offset coordinates begin at 1, and are relative to
|
||
the starting position of the most recently calculated noise.
|
||
To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000:
|
||
`noise:calc3dMap({x=1000, y=1000, z=1000})`
|
||
`noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})`
|
||
|
||
### `VoxelManip`
|
||
|
||
#### About VoxelManip
|
||
VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' facility. The purpose of
|
||
this object is for fast, low-level, bulk access to reading and writing Map content. As such, setting
|
||
map nodes through VoxelManip will lack many of the higher level features and concepts you may be used
|
||
to with other methods of setting nodes. For example, nodes will not have their construction and
|
||
destruction callbacks run, and no rollback information is logged.
|
||
|
||
It is important to note that VoxelManip is designed for speed, and *not* ease of use or flexibility.
|
||
If your mod requires a map manipulation facility that will handle 100% of all edge cases, or the use
|
||
of high level node placement features, perhaps minetest.set_node() is better suited for the job.
|
||
|
||
In addition, VoxelManip might not be faster, or could even be slower, for your specific use case.
|
||
VoxelManip is most effective when setting very large areas of map at once - for example, if only
|
||
setting a 5x5x5 node area, a minetest.set_node() loop may be more optimal. Always profile code
|
||
using both methods of map manipulation to determine which is most appropriate for your usage.
|
||
|
||
#### Using VoxelManip
|
||
A VoxelManip object can be created any time using either:
|
||
`VoxelManip([p1, p2])`, or `minetest.get_voxel_manip([p1, p2])`.
|
||
|
||
If the optional position parameters are present for either of these routines, the specified region
|
||
will be pre-loaded into the VoxelManip object on creation. Otherwise, the area of map you wish to
|
||
manipulate must first be loaded into the VoxelManip object using `VoxelManip:read_from_map()`.
|
||
|
||
Note that `VoxelManip:read_from_map()` returns two position vectors. The region formed by these
|
||
positions indicate the minimum and maximum (respectively) positions of the area actually loaded in
|
||
the VoxelManip, which may be larger than the area requested. For convenience, the loaded area
|
||
coordinates can also be queried any time after loading map data with `VoxelManip:get_emerged_area()`.
|
||
|
||
Now that the VoxelManip object is populated with map data, your mod can fetch a copy of this data
|
||
using either of two methods. `VoxelManip:get_node_at()`, which retrieves an individual node in a
|
||
MapNode formatted table at the position requested is the simplest method to use, but also the slowest.
|
||
|
||
Nodes in a VoxelManip object may also be read in bulk to a flat array table using:
|
||
`VoxelManip:get_data()` for node content (in Content ID form, see section 'Content IDs'),
|
||
`VoxelManip:get_light_data()` for node light levels, and
|
||
`VoxelManip:get_param2_data()` for the node type-dependent "param2" values.
|
||
|
||
See section 'Flat array format' for more details.
|
||
|
||
It is very important to understand that the tables returned by any of the above three functions
|
||
represent a snapshot of the VoxelManip's internal state at the time of the call. This copy of the
|
||
data will *not* magically update itself if another function modifies the internal VoxelManip state.
|
||
Any functions that modify a VoxelManip's contents work on the VoxelManip's internal state unless
|
||
otherwise explicitly stated.
|
||
|
||
Once the bulk data has been edited to your liking, the internal VoxelManip state can be set using:
|
||
`VoxelManip:set_data()` for node content (in Content ID form, see section 'Content IDs'),
|
||
`VoxelManip:set_light_data()` for node light levels, and
|
||
`VoxelManip:set_param2_data()` for the node type-dependent "param2" values.
|
||
|
||
The parameter to each of the above three functions can use any table at all in the same flat array
|
||
format as produced by get_data() et al. and is *not required* to be a table retrieved from get_data().
|
||
|
||
Once the internal VoxelManip state has been modified to your liking, the changes can be committed back
|
||
to the map by calling `VoxelManip:write_to_map()`.
|
||
|
||
Finally, a call to `VoxelManip:update_map()` is required to re-calculate lighting and set the blocks
|
||
as being modified so that connected clients are sent the updated parts of map.
|
||
|
||
|
||
##### Flat array format
|
||
Let
|
||
`Nx = p2.X - p1.X + 1`,
|
||
`Ny = p2.Y - p1.Y + 1`, and
|
||
`Nz = p2.Z - p1.Z + 1`.
|
||
|
||
Then, for a loaded region of p1..p2, this array ranges from `1` up to and including the value of
|
||
the expression `Nx * Ny * Nz`.
|
||
|
||
Positions offset from p1 are present in the array with the format of:
|
||
```
|
||
[
|
||
(0, 0, 0), (1, 0, 0), (2, 0, 0), ... (Nx, 0, 0),
|
||
(0, 1, 0), (1, 1, 0), (2, 1, 0), ... (Nx, 1, 0),
|
||
...
|
||
(0, Ny, 0), (1, Ny, 0), (2, Ny, 0), ... (Nx, Ny, 0),
|
||
(0, 0, 1), (1, 0, 1), (2, 0, 1), ... (Nx, 0, 1),
|
||
...
|
||
(0, Ny, 2), (1, Ny, 2), (2, Ny, 2), ... (Nx, Ny, 2),
|
||
...
|
||
(0, Ny, Nz), (1, Ny, Nz), (2, Ny, Nz), ... (Nx, Ny, Nz)
|
||
]
|
||
```
|
||
|
||
and the array index for a position p contained completely in p1..p2 is:
|
||
|
||
`(p.Z - p1.Z) * Ny * Nx + (p.Y - p1.Y) * Nx + (p.X - p1.X) + 1`
|
||
|
||
Note that this is the same "flat 3D array" format as `PerlinNoiseMap:get3dMap_flat()`.
|
||
VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation of the index
|
||
for a single point in a flat VoxelManip array.
|
||
|
||
##### Content IDs
|
||
A Content ID is a unique integer identifier for a specific node type. These IDs are used by VoxelManip
|
||
in place of the node name string for `VoxelManip:get_data()` and `VoxelManip:set_data()`. You can use
|
||
`minetest.get_content_id()` to look up the Content ID for the specified node name, and
|
||
`minetest.get_name_from_content_id()` to look up the node name string for a given Content ID.
|
||
After registration of a node, its Content ID will remain the same throughout execution of the mod.
|
||
Note that the node being queried needs to have already been been registered.
|
||
|
||
The following builtin node types have their Content IDs defined as constants:
|
||
```
|
||
core.CONTENT_UNKNOWN (ID for "unknown" nodes)
|
||
core.CONTENT_AIR (ID for "air" nodes)
|
||
core.CONTENT_IGNORE (ID for "ignore" nodes)
|
||
```
|
||
|
||
##### Mapgen VoxelManip objects
|
||
Inside of `on_generated()` callbacks, it is possible to retrieve the same VoxelManip object used by the
|
||
core's Map Generator (commonly abbreviated Mapgen). Most of the rules previously described still apply
|
||
but with a few differences:
|
||
|
||
* The Mapgen VoxelManip object is retrieved using: `minetest.get_mapgen_object("voxelmanip")`
|
||
* This VoxelManip object already has the region of map just generated loaded into it; it's not necessary
|
||
to call `VoxelManip:read_from_map()` before using a Mapgen VoxelManip.
|
||
* The `on_generated()` callbacks of some mods may place individual nodes in the generated area using
|
||
non-VoxelManip map modification methods. Because the same Mapgen VoxelManip object is passed through
|
||
each `on_generated()` callback, it becomes necessary for the Mapgen VoxelManip object to maintain
|
||
consistency with the current map state. For this reason, calling any of the following functions:
|
||
`minetest.add_node()`, `minetest.set_node()`, or `minetest.swap_node()`
|
||
will also update the Mapgen VoxelManip object's internal state active on the current thread.
|
||
* After modifying the Mapgen VoxelManip object's internal buffer, it may be necessary to update lighting
|
||
information using either: `VoxelManip:calc_lighting()` or `VoxelManip:set_lighting()`.
|
||
* `VoxelManip:update_map()` does not need to be called after `write_to_map()`. The map update is performed
|
||
automatically after all on_generated callbacks have been run for that generated block.
|
||
|
||
##### Other API functions operating on a VoxelManip
|
||
If any VoxelManip contents were set to a liquid node, `VoxelManip:update_liquids()` must be called
|
||
for these liquid nodes to begin flowing. It is recommended to call this function only after having
|
||
written all buffered data back to the VoxelManip object, save for special situations where the modder
|
||
desires to only have certain liquid nodes begin flowing.
|
||
|
||
The functions `minetest.generate_ores()` and `minetest.generate_decorations()` will generate all
|
||
registered decorations and ores throughout the full area inside of the specified VoxelManip object.
|
||
|
||
`minetest.place_schematic_on_vmanip()` is otherwise identical to `minetest.place_schematic()`,
|
||
except instead of placing the specified schematic directly on the map at the specified position, it
|
||
will place the schematic inside of the VoxelManip.
|
||
|
||
##### Notes
|
||
* Attempting to read data from a VoxelManip object before map is read will result in a zero-length
|
||
array table for `VoxelManip:get_data()`, and an "ignore" node at any position for
|
||
`VoxelManip:get_node_at()`.
|
||
* If either a region of map has not yet been generated or is out-of-bounds of the map, that region is
|
||
filled with "ignore" nodes.
|
||
* Other mods, or the core itself, could possibly modify the area of map currently loaded into a VoxelManip
|
||
object. With the exception of Mapgen VoxelManips (see above section), the internal buffers are not
|
||
updated. For this reason, it is strongly encouraged to complete the usage of a particular VoxelManip
|
||
object in the same callback it had been created.
|
||
* If a VoxelManip object will be used often, such as in an `on_generated()` callback, consider passing
|
||
a file-scoped table as the optional parameter to `VoxelManip:get_data()`, which serves as a static
|
||
buffer the function can use to write map data to instead of returning a new table each call. This
|
||
greatly enhances performance by avoiding unnecessary memory allocations.
|
||
|
||
#### Methods
|
||
* `read_from_map(p1, p2)`: Loads a chunk of map into the VoxelManip object containing
|
||
the region formed by `p1` and `p2`.
|
||
* returns actual emerged `pmin`, actual emerged `pmax`
|
||
* `write_to_map()`: Writes the data loaded from the `VoxelManip` back to the map.
|
||
* **important**: data must be set using `VoxelManip:set_data()` before calling this
|
||
* `get_node_at(pos)`: Returns a `MapNode` table of the node currently loaded in
|
||
the `VoxelManip` at that position
|
||
* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at that position
|
||
* `get_data([buffer])`: Retrieves the node content data loaded into the `VoxelManip` object
|
||
* returns raw node data in the form of an array of node content IDs
|
||
* if the param `buffer` is present, this table will be used to store the result instead
|
||
* `set_data(data)`: Sets the data contents of the `VoxelManip` object
|
||
* `update_map()`: Update map after writing chunk back to map.
|
||
* To be used only by `VoxelManip` objects created by the mod itself;
|
||
not a `VoxelManip` that was retrieved from `minetest.get_mapgen_object`
|
||
* `set_lighting(light, [p1, p2])`: Set the lighting within the `VoxelManip` to a uniform value
|
||
* `light` is a table, `{day=<0...15>, night=<0...15>}`
|
||
* To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
|
||
* (`p1`, `p2`) is the area in which lighting is set;
|
||
defaults to the whole area if left out
|
||
* `get_light_data()`: Gets the light data read into the `VoxelManip` object
|
||
* Returns an array (indices 1 to volume) of integers ranging from `0` to `255`
|
||
* Each value is the bitwise combination of day and night light values (`0` to `15` each)
|
||
* `light = day + (night * 16)`
|
||
* `set_light_data(light_data)`: Sets the `param1` (light) contents of each node
|
||
in the `VoxelManip`
|
||
* expects lighting data in the same format that `get_light_data()` returns
|
||
* `get_param2_data([buffer])`: Gets the raw `param2` data read into the `VoxelManip` object
|
||
* Returns an array (indices 1 to volume) of integers ranging from `0` to `255`
|
||
* If the param `buffer` is present, this table will be used to store the result instead
|
||
* `set_param2_data(param2_data)`: Sets the `param2` contents of each node in the `VoxelManip`
|
||
* `calc_lighting([p1, p2], [propagate_shadow])`: Calculate lighting within the `VoxelManip`
|
||
* To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
|
||
* (`p1`, `p2`) is the area in which lighting is set; defaults to the whole area
|
||
if left out or nil
|
||
* `propagate_shadow` is an optional boolean deciding whether shadows in a generated
|
||
mapchunk above are propagated down into the mapchunk; defaults to `true` if left out
|
||
* `update_liquids()`: Update liquid flow
|
||
* `was_modified()`: Returns `true` or `false` if the data in the voxel manipulator
|
||
had been modified since the last read from map, due to a call to
|
||
`minetest.set_data()` on the loaded area elsewhere
|
||
* `get_emerged_area()`: Returns actual emerged minimum and maximum positions.
|
||
|
||
### `VoxelArea`
|
||
A helper class for voxel areas.
|
||
It can be created via `VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}`.
|
||
The coordinates are *inclusive*, like most other things in Minetest.
|
||
|
||
#### Methods
|
||
* `getExtent()`: returns a 3D vector containing the size of the area formed by
|
||
`MinEdge` and `MaxEdge`
|
||
* `getVolume()`: returns the volume of the area formed by `MinEdge` and `MaxEdge`
|
||
* `index(x, y, z)`: returns the index of an absolute position in a flat array starting at `1`
|
||
* useful for things like `VoxelManip`, raw Schematic specifiers,
|
||
`PerlinNoiseMap:get2d`/`3dMap`, and so on
|
||
* `indexp(p)`: same as above, except takes a vector
|
||
* `position(i)`: returns the absolute position vector corresponding to index `i`
|
||
* `contains(x, y, z)`: check if (`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`
|
||
* `containsp(p)`: same as above, except takes a vector
|
||
* `containsi(i)`: same as above, except takes an index `i`
|
||
* `iter(minx, miny, minz, maxx, maxy, maxz)`: returns an iterator that returns indices
|
||
* from (`minx`,`miny`,`minz`) to (`maxx`,`maxy`,`maxz`) in the order of `[z [y [x]]]`
|
||
* `iterp(minp, maxp)`: same as above, except takes a vector
|
||
|
||
### `Settings`
|
||
An interface to read config files in the format of `minetest.conf`.
|
||
|
||
It can be created via `Settings(filename)`.
|
||
|
||
#### Methods
|
||
* `get(key)`: returns a value
|
||
* `get_bool(key)`: returns a boolean
|
||
* `set(key, value)`
|
||
* `remove(key)`: returns a boolean (`true` for success)
|
||
* `get_names()`: returns `{key1,...}`
|
||
* `write()`: returns a boolean (`true` for success)
|
||
* write changes to file
|
||
* `to_table()`: returns `{[key1]=value1,...}`
|
||
|
||
Mapgen objects
|
||
--------------
|
||
A mapgen object is a construct used in map generation. Mapgen objects can be used
|
||
by an `on_generate` callback to speed up operations by avoiding unnecessary
|
||
recalculations; these can be retrieved using the `minetest.get_mapgen_object()`
|
||
function. If the requested Mapgen object is unavailable, or `get_mapgen_object()`
|
||
was called outside of an `on_generate()` callback, `nil` is returned.
|
||
|
||
The following Mapgen objects are currently available:
|
||
|
||
### `voxelmanip`
|
||
This returns three values; the `VoxelManip` object to be used, minimum and maximum
|
||
emerged position, in that order. All mapgens support this object.
|
||
|
||
### `heightmap`
|
||
Returns an array containing the y coordinates of the ground levels of nodes in
|
||
the most recently generated chunk by the current mapgen.
|
||
|
||
### `biomemap`
|
||
Returns an array containing the biome IDs of nodes in the most recently
|
||
generated chunk by the current mapgen.
|
||
|
||
### `heatmap`
|
||
Returns an array containing the temperature values of nodes in the most
|
||
recently generated chunk by the current mapgen.
|
||
|
||
### `humiditymap`
|
||
Returns an array containing the humidity values of nodes in the most recently
|
||
generated chunk by the current mapgen.
|
||
|
||
### `gennotify`
|
||
Returns a table mapping requested generation notification types to arrays of
|
||
positions at which the corresponding generated structures are located at within
|
||
the current chunk. To set the capture of positions of interest to be recorded
|
||
on generate, use `minetest.set_gen_notify()`.
|
||
|
||
Possible fields of the table returned are:
|
||
|
||
* `dungeon`
|
||
* `temple`
|
||
* `cave_begin`
|
||
* `cave_end`
|
||
* `large_cave_begin`
|
||
* `large_cave_end`
|
||
* `decoration`
|
||
|
||
Decorations have a key in the format of `"decoration#id"`, where `id` is the
|
||
numeric unique decoration ID.
|
||
|
||
Registered entities
|
||
-------------------
|
||
* Functions receive a "luaentity" as `self`:
|
||
* 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
|
||
* The original prototype stuff is visible directly via a metatable
|
||
* Callbacks:
|
||
* `on_activate(self, staticdata, dtime_s)`
|
||
* Called when the object is instantiated.
|
||
* `dtime_s` is the time passed since the object was unloaded, which can
|
||
be used for updating the entity state.
|
||
* `on_step(self, dtime)`
|
||
* Called on every server tick, after movement and collision processing.
|
||
`dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting
|
||
`in minetest.conf`.
|
||
* `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)`
|
||
* Called when somebody punches the object.
|
||
* Note that you probably want to handle most punches using the
|
||
automatic armor group system.
|
||
* `puncher`: an `ObjectRef` (can be `nil`)
|
||
* `time_from_last_punch`: Meant for disallowing spamming of clicks (can be `nil`)
|
||
* `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_rightclick(self, clicker)`
|
||
* `get_staticdata(self)`
|
||
* Should return a string that will be passed to `on_activate` when
|
||
the object is instantiated the next time.
|
||
|
||
L-system trees
|
||
--------------
|
||
**Warning**
|
||
L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
|
||
Often these bugs appear as subtle shadows in water.
|
||
|
||
### Tree definition
|
||
|
||
treedef={
|
||
axiom, --string initial tree axiom
|
||
rules_a, --string rules set A
|
||
rules_b, --string rules set B
|
||
rules_c, --string rules set C
|
||
rules_d, --string rules set D
|
||
trunk, --string trunk node name
|
||
leaves, --string leaves node name
|
||
leaves2, --string secondary leaves node name
|
||
leaves2_chance,--num chance (0-100) to replace leaves with leaves2
|
||
angle, --num angle in deg
|
||
iterations, --num max # of iterations, usually 2 -5
|
||
random_level, --num factor to lower nr of iterations, usually 0 - 3
|
||
trunk_type, --string single/double/crossed) type of trunk: 1 node,
|
||
-- 2x2 nodes or 3x3 in cross shape
|
||
thin_branches, --boolean true -> use thin (1 node) branches
|
||
fruit, --string fruit node name
|
||
fruit_chance, --num chance (0-100) to replace leaves with fruit node
|
||
seed, --num random seed; if no seed is provided, the engine will create one
|
||
}
|
||
|
||
### Key for Special L-System Symbols used in Axioms
|
||
|
||
* `G`: move forward one unit with the pen up
|
||
* `F`: move forward one unit with the pen down drawing trunks and branches
|
||
* `f`: move forward one unit with the pen down drawing leaves (100% chance)
|
||
* `T`: move forward one unit with the pen down drawing trunks only
|
||
* `R`: move forward one unit with the pen down placing fruit
|
||
* `A`: replace with rules set A
|
||
* `B`: replace with rules set B
|
||
* `C`: replace with rules set C
|
||
* `D`: replace with rules set D
|
||
* `a`: replace with rules set A, chance 90%
|
||
* `b`: replace with rules set B, chance 80%
|
||
* `c`: replace with rules set C, chance 70%
|
||
* `d`: replace with rules set D, chance 60%
|
||
* `+`: yaw the turtle right by `angle` parameter
|
||
* `-`: yaw the turtle left by `angle` parameter
|
||
* `&`: pitch the turtle down by `angle` parameter
|
||
* `^`: pitch the turtle up by `angle` parameter
|
||
* `/`: roll the turtle to the right by `angle` parameter
|
||
* `*`: roll the turtle to the left by `angle` parameter
|
||
* `[`: save in stack current state info
|
||
* `]`: recover from stack state info
|
||
|
||
### Example
|
||
Spawn a small apple tree:
|
||
|
||
pos = {x=230,y=20,z=4}
|
||
apple_tree={
|
||
axiom="FFFFFAFFBF",
|
||
rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
|
||
rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
|
||
trunk="default:tree",
|
||
leaves="default:leaves",
|
||
angle=30,
|
||
iterations=2,
|
||
random_level=0,
|
||
trunk_type="single",
|
||
thin_branches=true,
|
||
fruit_chance=10,
|
||
fruit="default:apple"
|
||
}
|
||
minetest.spawn_tree(pos,apple_tree)
|
||
|
||
Definition tables
|
||
-----------------
|
||
|
||
### Object Properties
|
||
|
||
{
|
||
hp_max = 1,
|
||
physical = true,
|
||
collide_with_objects = true, -- collide with other objects if physical=true
|
||
weight = 5,
|
||
collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
|
||
visual = "cube"/"sprite"/"upright_sprite"/"mesh"/"wielditem",
|
||
visual_size = {x=1, y=1},
|
||
mesh = "model",
|
||
textures = {}, -- number of required textures depends on visual
|
||
colors = {}, -- number of required colors depends on visual
|
||
spritediv = {x=1, y=1},
|
||
initial_sprite_basepos = {x=0, y=0},
|
||
is_visible = true,
|
||
makes_footstep_sound = false,
|
||
automatic_rotate = false,
|
||
stepheight = 0,
|
||
automatic_face_movement_dir = 0.0,
|
||
-- ^ automatically set yaw to movement direction; offset in degrees; false to disable
|
||
automatic_face_movement_max_rotation_per_sec = -1,
|
||
-- ^ limit automatic rotation to this value in degrees per second. values < 0 no limit
|
||
backface_culling = true, -- false to disable backface_culling for model
|
||
nametag = "", -- by default empty, for players their name is shown if empty
|
||
nametag_color = <color>, -- sets color of nametag as ColorSpec
|
||
infotext = "", -- by default empty, text to be shown when pointed at object
|
||
}
|
||
|
||
### Entity definition (`register_entity`)
|
||
|
||
{
|
||
-- Deprecated: Everything in object properties is read directly from here
|
||
|
||
initial_properties = --[[<initial object properties>]],
|
||
|
||
on_activate = function(self, staticdata, dtime_s),
|
||
on_step = function(self, dtime),
|
||
on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
|
||
on_rightclick = function(self, clicker),
|
||
get_staticdata = function(self),
|
||
-- ^ Called sometimes; the string returned is passed to on_activate when
|
||
-- the entity is re-activated from static state
|
||
|
||
-- Also you can define arbitrary member variables here (see item definition for
|
||
-- more info)
|
||
_custom_field = whatever,
|
||
}
|
||
|
||
### ABM (ActiveBlockModifier) definition (`register_abm`)
|
||
|
||
{
|
||
label = "Lava cooling",
|
||
-- ^ Descriptive label for profiling purposes (optional).
|
||
-- Definitions with identical labels will be listed as one.
|
||
-- In the following two fields, also group:groupname will work.
|
||
nodenames = {"default:lava_source"},
|
||
neighbors = {"default:water_source", "default:water_flowing"}, -- Any of these --[[
|
||
^ If left out or empty, any neighbor will do ]]
|
||
interval = 1.0, -- Operation interval in seconds
|
||
chance = 1, -- Chance of trigger per-node per-interval is 1.0 / this
|
||
catch_up = true, -- If true, catch-up behaviour is enabled --[[
|
||
^ The chance value is temporarily reduced when returning to
|
||
an area to simulate time lost by the area being unattended.
|
||
^ Note chance value can often be reduced to 1 ]]
|
||
action = func(pos, node, active_object_count, active_object_count_wider),
|
||
}
|
||
|
||
### LBM (LoadingBlockModifier) definition (`register_lbm`)
|
||
|
||
{
|
||
label = "Upgrade legacy doors",
|
||
-- ^ Descriptive label for profiling purposes (optional).
|
||
-- Definitions with identical labels will be listed as one.
|
||
name = "modname:replace_legacy_door",
|
||
nodenames = {"default:lava_source"},
|
||
-- ^ List of node names to trigger the LBM on.
|
||
-- Also non-registered nodes will work.
|
||
-- Groups (as of group:groupname) will work as well.
|
||
run_at_every_load = false,
|
||
-- ^ Whether to run the LBM's action every time a block gets loaded,
|
||
-- and not just for blocks that were saved last time before LBMs were
|
||
-- introduced to the world.
|
||
action = func(pos, node),
|
||
}
|
||
|
||
### Item definition (`register_node`, `register_craftitem`, `register_tool`)
|
||
|
||
{
|
||
description = "Steel Axe",
|
||
groups = {}, -- key = name, value = rating; rating = 1..3.
|
||
if rating not applicable, use 1.
|
||
e.g. {wool = 1, fluffy = 3}
|
||
{soil = 2, outerspace = 1, crumbly = 1}
|
||
{bendy = 2, snappy = 1},
|
||
{hard = 1, metal = 1, spikes = 1}
|
||
inventory_image = "default_tool_steelaxe.png",
|
||
wield_image = "",
|
||
wield_scale = {x = 1, y = 1, z = 1},
|
||
stack_max = 99,
|
||
range = 4.0,
|
||
liquids_pointable = false,
|
||
tool_capabilities = {
|
||
full_punch_interval = 1.0,
|
||
max_drop_level = 0,
|
||
groupcaps = {
|
||
-- For example:
|
||
choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, uses = 20, maxlevel = 2},
|
||
},
|
||
damage_groups = {groupname = damage},
|
||
},
|
||
node_placement_prediction = nil,
|
||
--[[
|
||
^ If nil and item is node, prediction is made automatically
|
||
^ If nil and item is not a node, no prediction is made
|
||
^ If "" and item is anything, no prediction is made
|
||
^ Otherwise should be name of node which the client immediately places
|
||
on ground when the player places the item. Server will always update
|
||
actual result to client in a short moment.
|
||
]]
|
||
sound = {
|
||
breaks = "default_tool_break", -- tools only
|
||
place = --[[<SimpleSoundSpec>]],
|
||
},
|
||
|
||
on_place = func(itemstack, placer, pointed_thing),
|
||
--[[
|
||
^ Shall place item and return the leftover itemstack
|
||
^ The placer may be any ObjectRef or nil.
|
||
^ default: minetest.item_place ]]
|
||
on_secondary_use = func(itemstack, user, pointed_thing),
|
||
--[[
|
||
^ Same as on_place but called when pointing at nothing.
|
||
^ The user may be any ObjectRef or nil.
|
||
^ pointed_thing : always { type = "nothing" }
|
||
]]
|
||
on_drop = func(itemstack, dropper, pos),
|
||
--[[
|
||
^ Shall drop item and return the leftover itemstack
|
||
^ The dropper may be any ObjectRef or nil.
|
||
^ default: minetest.item_drop ]]
|
||
on_use = func(itemstack, user, pointed_thing),
|
||
--[[
|
||
^ default: nil
|
||
^ Function must return either nil if no item shall be removed from
|
||
inventory, or an itemstack to replace the original itemstack.
|
||
e.g. itemstack:take_item(); return itemstack
|
||
^ Otherwise, the function is free to do what it wants.
|
||
^ The user may be any ObjectRef or nil.
|
||
^ The default functions handle regular use cases.
|
||
]]
|
||
after_use = func(itemstack, user, node, digparams),
|
||
--[[
|
||
^ default: nil
|
||
^ If defined, should return an itemstack and will be called instead of
|
||
wearing out the tool. If returns nil, does nothing.
|
||
If after_use doesn't exist, it is the same as:
|
||
function(itemstack, user, node, digparams)
|
||
itemstack:add_wear(digparams.wear)
|
||
return itemstack
|
||
end
|
||
^ The user may be any ObjectRef or nil.
|
||
]]
|
||
_custom_field = whatever,
|
||
--[[
|
||
^ Add your own custom fields. By convention, all custom field names
|
||
should start with `_` to avoid naming collisions with future engine
|
||
usage.
|
||
]]
|
||
}
|
||
|
||
### Tile definition
|
||
* `"image.png"`
|
||
* `{name="image.png", animation={Tile Animation definition}}`
|
||
* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
|
||
tileable_horizontal=bool}`
|
||
* backface culling enabled by default for most nodes
|
||
* tileable flags are info for shaders, how they should treat texture
|
||
when displacement mapping is used
|
||
Directions are from the point of view of the tile texture,
|
||
not the node it's on
|
||
* deprecated, yet still supported field names:
|
||
* `image` (name)
|
||
|
||
### Tile animation definition
|
||
|
||
{
|
||
type = "vertical_frames",
|
||
aspect_w = 16,
|
||
-- ^ specify width of a frame in pixels
|
||
aspect_h = 16,
|
||
-- ^ specify height of a frame in pixels
|
||
length = 3.0,
|
||
-- ^ specify full loop length
|
||
}
|
||
|
||
{
|
||
type = "sheet_2d",
|
||
frames_w = 5,
|
||
-- ^ specify width in number of frames
|
||
frames_h = 3,
|
||
-- ^ specify height in number of frames
|
||
frame_length = 0.5,
|
||
-- ^ specify length of a single frame
|
||
}
|
||
|
||
### Node definition (`register_node`)
|
||
|
||
{
|
||
-- <all fields allowed in item definitions>,
|
||
|
||
drawtype = "normal", -- See "Node drawtypes"
|
||
visual_scale = 1.0, --[[
|
||
^ Supported for drawtypes "plantlike", "signlike", "torchlike", "mesh".
|
||
^ For plantlike, the image will start at the bottom of the node; for the
|
||
^ other drawtypes, the image will be centered on the node.
|
||
^ Note that positioning for "torchlike" may still change. ]]
|
||
tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
|
||
^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
|
||
^ List can be shortened to needed length ]]
|
||
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 ]]
|
||
alpha = 255,
|
||
use_texture_alpha = false, -- Use texture's alpha channel
|
||
post_effect_color = "green#0F", -- If player is inside node, see "ColorSpec"
|
||
paramtype = "none", -- See "Nodes" --[[
|
||
^ paramtype = "light" allows light to propagate from or through the node with light value
|
||
^ falling by 1 per node. This line is essential for a light source node to spread its light. ]]
|
||
paramtype2 = "none", -- See "Nodes"
|
||
place_param2 = nil, -- Force value for param2 when player places node
|
||
is_ground_content = true, -- If false, the cave generator will not carve through this
|
||
sunlight_propagates = false, -- If true, sunlight will go infinitely through this
|
||
walkable = true, -- If true, objects collide with node
|
||
pointable = true, -- If true, can be pointed at
|
||
diggable = true, -- If false, can never be dug
|
||
climbable = false, -- If true, can be climbed on (ladder)
|
||
buildable_to = false, -- If true, placed nodes can replace this node
|
||
floodable = false, -- If true, liquids flow into and replace this node
|
||
liquidtype = "none", -- "none"/"source"/"flowing"
|
||
liquid_alternative_flowing = "", -- Flowing version of source liquid
|
||
liquid_alternative_source = "", -- Source version of flowing liquid
|
||
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. ]]
|
||
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, --[[
|
||
^ Amount of light emitted by node.
|
||
^ To set the maximum (currently 14), use the value 'minetest.LIGHT_MAX'.
|
||
^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.]]
|
||
damage_per_second = 0, -- If player is inside node, this damage is caused
|
||
node_box = {type="regular"}, -- See "Node boxes"
|
||
connects_to = nodenames, --[[
|
||
* Used for nodebox nodes with the type == "connected"
|
||
* Specifies to what neighboring nodes connections will be drawn
|
||
* e.g. `{"group:fence", "default:wood"}` or `"default:stone"` ]]
|
||
connect_sides = { "top", "bottom", "front", "left", "back", "right" }, --[[
|
||
^ Tells connected nodebox nodes to connect only to these sides of this node. ]]
|
||
mesh = "model",
|
||
selection_box = {type="regular"}, -- See "Node boxes" --[[
|
||
^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
|
||
legacy_facedir_simple = false, -- Support maps made in and before January 2012
|
||
legacy_wallmounted = false, -- Support maps made in and before January 2012
|
||
sounds = {
|
||
footstep = <SimpleSoundSpec>,
|
||
dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
|
||
dug = <SimpleSoundSpec>,
|
||
place = <SimpleSoundSpec>,
|
||
place_failed = <SimpleSoundSpec>,
|
||
},
|
||
drop = "", -- Name of dropped node when dug. Default is the node itself.
|
||
-- Alternatively:
|
||
drop = {
|
||
max_items = 1, -- Maximum number of items to drop.
|
||
items = { -- Choose max_items randomly from this list.
|
||
{
|
||
items = {"foo:bar", "baz:frob"}, -- Items to drop.
|
||
rarity = 1, -- Probability of dropping is 1 / rarity.
|
||
},
|
||
},
|
||
},
|
||
|
||
on_construct = func(pos), --[[
|
||
^ Node constructor; called after adding node
|
||
^ Can set up metadata and stuff like that
|
||
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
|
||
^ default: nil ]]
|
||
on_destruct = func(pos), --[[
|
||
^ Node destructor; called before removing node
|
||
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
|
||
^ default: nil ]]
|
||
after_destruct = func(pos, oldnode), --[[
|
||
^ Node destructor; called after removing node
|
||
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
|
||
^ default: nil ]]
|
||
|
||
after_place_node = func(pos, placer, itemstack, pointed_thing) --[[
|
||
^ Called after constructing node when node was placed using
|
||
minetest.item_place_node / minetest.place_node
|
||
^ If return true no item is taken from itemstack
|
||
^ default: nil ]]
|
||
after_dig_node = func(pos, oldnode, oldmetadata, digger), --[[
|
||
^ oldmetadata is in table format
|
||
^ Called after destructing node when node was dug using
|
||
minetest.node_dig / minetest.dig_node
|
||
^ default: nil ]]
|
||
can_dig = function(pos, [player]) --[[
|
||
^ returns true if node can be dug, or false if not
|
||
^ default: nil ]]
|
||
|
||
on_punch = func(pos, node, puncher, pointed_thing), --[[
|
||
^ default: minetest.node_punch
|
||
^ 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
|
||
^ Shall return the leftover itemstack
|
||
^ Note: pointed_thing can be nil, if a mod calls this function ]]
|
||
|
||
on_dig = func(pos, node, digger), --[[
|
||
^ default: minetest.node_dig
|
||
^ By default: checks privileges, wears out tool and removes node ]]
|
||
|
||
on_timer = function(pos,elapsed), --[[
|
||
^ default: nil
|
||
^ called by NodeTimers, see minetest.get_node_timer and NodeTimerRef
|
||
^ elapsed is the total time passed since the timer was started
|
||
^ return true to run the timer for another cycle with the same timeout value ]]
|
||
|
||
on_receive_fields = func(pos, formname, fields, sender), --[[
|
||
^ fields = {name1 = value1, name2 = value2, ...}
|
||
^ Called when an UI form (e.g. sign text input) returns data
|
||
^ default: nil ]]
|
||
|
||
allow_metadata_inventory_move = func(pos, from_list, from_index,
|
||
to_list, to_index, count, player), --[[
|
||
^ Called when a player wants to move items inside the inventory
|
||
^ Return value: number of items allowed to move ]]
|
||
|
||
allow_metadata_inventory_put = func(pos, listname, index, stack, player), --[[
|
||
^ Called when a player wants to put something into the inventory
|
||
^ Return value: number of items allowed to put
|
||
^ Return value: -1: Allow and don't modify item count in inventory ]]
|
||
|
||
allow_metadata_inventory_take = func(pos, listname, index, stack, player), --[[
|
||
^ Called when a player wants to take something out of the inventory
|
||
^ Return value: number of items allowed to take
|
||
^ Return value: -1: Allow and don't modify item count in inventory ]]
|
||
|
||
on_metadata_inventory_move = func(pos, from_list, from_index,
|
||
to_list, to_index, count, player),
|
||
on_metadata_inventory_put = func(pos, listname, index, stack, player),
|
||
on_metadata_inventory_take = func(pos, listname, index, stack, player), --[[
|
||
^ Called after the actual action has happened, according to what was allowed.
|
||
^ No return value ]]
|
||
|
||
on_blast = func(pos, intensity), --[[
|
||
^ intensity: 1.0 = mid range of regular TNT
|
||
^ If defined, called when an explosion touches the node, instead of
|
||
removing the node ]]
|
||
}
|
||
|
||
### Recipe for `register_craft` (shaped)
|
||
|
||
{
|
||
output = 'default:pick_stone',
|
||
recipe = {
|
||
{'default:cobble', 'default:cobble', 'default:cobble'},
|
||
{'', 'default:stick', ''},
|
||
{'', 'default:stick', ''}, -- Also groups; e.g. 'group:crumbly'
|
||
},
|
||
replacements = --[[<optional list of item pairs,
|
||
replace one input item with another item on crafting>]]
|
||
}
|
||
|
||
### Recipe for `register_craft` (shapeless)
|
||
|
||
{
|
||
type = "shapeless",
|
||
output = 'mushrooms:mushroom_stew',
|
||
recipe = {
|
||
"mushrooms:bowl",
|
||
"mushrooms:mushroom_brown",
|
||
"mushrooms:mushroom_red",
|
||
},
|
||
replacements = --[[<optional list of item pairs,
|
||
replace one input item with another item on crafting>]]
|
||
}
|
||
|
||
### Recipe for `register_craft` (tool repair)
|
||
|
||
{
|
||
type = "toolrepair",
|
||
additional_wear = -0.02,
|
||
}
|
||
|
||
### Recipe for `register_craft` (cooking)
|
||
|
||
{
|
||
type = "cooking",
|
||
output = "default:glass",
|
||
recipe = "default:sand",
|
||
cooktime = 3,
|
||
}
|
||
|
||
### Recipe for `register_craft` (furnace fuel)
|
||
|
||
{
|
||
type = "fuel",
|
||
recipe = "default:leaves",
|
||
burntime = 1,
|
||
}
|
||
|
||
### Ore definition (`register_ore`)
|
||
|
||
{
|
||
ore_type = "scatter", -- See "Ore types"
|
||
ore = "default:stone_with_coal",
|
||
wherein = "default:stone",
|
||
-- ^ a list of nodenames is supported too
|
||
clust_scarcity = 8*8*8,
|
||
-- ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
|
||
-- ^ This value should be *MUCH* higher than your intuition might tell you!
|
||
clust_num_ores = 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
|
||
y_min = -31000,
|
||
y_max = 64,
|
||
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
|
||
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.
|
||
-- ^ 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",
|
||
-- ^ Node dropped onto upper surface after all else is generated.
|
||
node_top = "default:dirt_with_snow",
|
||
depth_top = 1,
|
||
-- ^ Node forming surface layer of biome and thickness of this layer.
|
||
node_filler = "default:permafrost",
|
||
depth_filler = 3,
|
||
-- ^ Node forming lower layer of biome and thickness of this layer.
|
||
node_stone = "default:bluestone",
|
||
-- ^ Node that replaces all stone nodes between roughly y_min and y_max.
|
||
node_water_top = "default:ice",
|
||
depth_water_top = 10,
|
||
-- ^ Node forming a surface layer in seawater with the defined thickness.
|
||
node_water = "",
|
||
-- ^ Node that replaces all seawater nodes not in the defined surface layer.
|
||
node_river_water = "default:ice",
|
||
-- ^ Node that replaces river water in mapgens that use default:river_water.
|
||
node_riverbed = "default:gravel",
|
||
depth_riverbed = 2,
|
||
-- ^ Node placed under river water and thickness of this layer.
|
||
y_min = 1,
|
||
y_max = 31000,
|
||
-- ^ Lower and upper limits for biome.
|
||
-- ^ 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.
|
||
-- ^ These values create 'biome points' on a voronoi diagram that has heat
|
||
-- ^ and humidity as axes. The resulting voronoi cells determine which
|
||
-- ^ heat/humidity points belong to which biome, and therefore determine
|
||
-- ^ the area and location of each biome in the world.
|
||
-- ^ The biome points need to be carefully and evenly spaced on the voronoi
|
||
-- ^ diagram to result in roughly equal size biomes.
|
||
-- ^ Heat and humidity have average values of 50, vary mostly between
|
||
-- ^ 0 and 100 but also often exceed these values.
|
||
-- ^ Heat is not in degrees celcius, both values are abstract.
|
||
}
|
||
|
||
### Decoration definition (`register_decoration`)
|
||
|
||
{
|
||
deco_type = "simple", -- See "Decoration types"
|
||
place_on = "default:dirt_with_grass",
|
||
-- ^ Node (or list of nodes) that the decoration can be placed on
|
||
sidelen = 8,
|
||
-- ^ Size of divisions made in the chunk being generated.
|
||
-- ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size.
|
||
fill_ratio = 0.02,
|
||
-- ^ Ratio of the area to be uniformly filled by the decoration.
|
||
-- ^ Used only if noise_params is not specified.
|
||
noise_params = {offset=0, scale=.45, spread={x=100, y=100, z=100}, seed=354, octaves=3, persist=0.7},
|
||
-- ^ NoiseParams structure describing the perlin noise used for decoration distribution.
|
||
-- ^ The result of this is multiplied by the 2d area of the division being decorated.
|
||
biomes = {"Oceanside", "Hills", "Plains"},
|
||
-- ^ 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.
|
||
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`.
|
||
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),
|
||
-- ^ one plane at Y = surface and one plane at Y = surface = + 1.
|
||
num_spawn_by = 1,
|
||
-- ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
|
||
-- ^ If absent or -1, decorations occur next to any nodes.
|
||
flags = "liquid_surface, force_placement",
|
||
-- ^ Flags for all decoration types.
|
||
-- ^ "liquid_surface": Instead of placement on the highest solid surface
|
||
-- ^ in a mapchunk column, placement is on the highest liquid surface.
|
||
-- ^ Placement is disabled if solid nodes are found above the liquid surface.
|
||
-- ^ "force_placement": Nodes other than "air" and "ignore" are replaced by the decoration.
|
||
|
||
----- Simple-type parameters
|
||
decoration = "default:grass",
|
||
-- ^ The node name used as the decoration.
|
||
-- ^ If instead a list of strings, a randomly selected node from the list is placed as the decoration.
|
||
height = 1,
|
||
-- ^ Number of nodes high the decoration is made.
|
||
-- ^ If height_max is not 0, this is the lower bound of the randomly selected height.
|
||
height_max = 0,
|
||
-- ^ Number of nodes the decoration can be at maximum.
|
||
-- ^ If absent, the parameter 'height' is used as a constant.
|
||
param2 = 0,
|
||
-- ^ Param2 value of placed decoration node.
|
||
|
||
----- Schematic-type parameters
|
||
schematic = "foobar.mts",
|
||
-- ^ If schematic is a string, it is the filepath relative to the current working directory of the
|
||
-- ^ specified Minetest schematic file.
|
||
-- ^ - OR -, could be the ID of a previously registered schematic
|
||
-- ^ - OR -, could instead be a table containing two mandatory fields, size and data,
|
||
-- ^ and an optional table yslice_prob:
|
||
schematic = {
|
||
size = {x=4, y=6, z=4},
|
||
data = {
|
||
{name="default:cobble", param1=255, param2=0},
|
||
{name="default:dirt_with_grass", param1=255, param2=0},
|
||
{name="ignore", param1=255, param2=0},
|
||
{name="air", param1=255, param2=0},
|
||
...
|
||
},
|
||
yslice_prob = {
|
||
{ypos=2, prob=128},
|
||
{ypos=5, prob=64},
|
||
...
|
||
},
|
||
},
|
||
-- ^ See 'Schematic specifier' for details.
|
||
replacements = {["oldname"] = "convert_to", ...},
|
||
flags = "place_center_x, place_center_y, place_center_z",
|
||
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
|
||
rotation = "90" -- rotate schematic 90 degrees on placement
|
||
-- ^ Rotation can be "0", "90", "180", "270", or "random".
|
||
}
|
||
|
||
### Chat command definition (`register_chatcommand`)
|
||
|
||
{
|
||
params = "<name> <privilege>", -- Short parameter description
|
||
description = "Remove privilege from player", -- Full description
|
||
privs = {privs=true}, -- Require the "privs" privilege to run
|
||
func = function(name, param), -- Called when command is run.
|
||
-- Returns boolean success and text output.
|
||
}
|
||
|
||
### Detached inventory callbacks
|
||
|
||
{
|
||
allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
|
||
-- ^ Called when a player wants to move items inside the inventory
|
||
-- ^ Return value: number of items allowed to move
|
||
|
||
allow_put = func(inv, listname, index, stack, player),
|
||
-- ^ Called when a player wants to put something into the inventory
|
||
-- ^ Return value: number of items allowed to put
|
||
-- ^ Return value: -1: Allow and don't modify item count in inventory
|
||
|
||
allow_take = func(inv, listname, index, stack, player),
|
||
-- ^ Called when a player wants to take something out of the inventory
|
||
-- ^ Return value: number of items allowed to take
|
||
-- ^ Return value: -1: Allow and don't modify item count in inventory
|
||
|
||
on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
|
||
on_put = func(inv, listname, index, stack, player),
|
||
on_take = func(inv, listname, index, stack, player),
|
||
-- ^ Called after the actual action has happened, according to what was allowed.
|
||
-- ^ No return value
|
||
}
|
||
|
||
### HUD Definition (`hud_add`, `hud_get`)
|
||
|
||
{
|
||
hud_elem_type = "image", -- see HUD element types
|
||
-- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
|
||
position = {x=0.5, y=0.5},
|
||
-- ^ Left corner position of element
|
||
name = "<name>",
|
||
scale = {x=2, y=2},
|
||
text = "<text>",
|
||
number = 2,
|
||
item = 3,
|
||
-- ^ Selected item in inventory. 0 for no item selected.
|
||
direction = 0,
|
||
-- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
|
||
alignment = {x=0, y=0},
|
||
-- ^ See "HUD Element Types"
|
||
offset = {x=0, y=0},
|
||
-- ^ See "HUD Element Types"
|
||
size = { x=100, y=100 },
|
||
-- ^ Size of element in pixels
|
||
}
|
||
|
||
### Particle definition (`add_particle`)
|
||
|
||
{
|
||
pos = {x=0, y=0, z=0},
|
||
velocity = {x=0, y=0, z=0},
|
||
acceleration = {x=0, y=0, z=0},
|
||
-- ^ Spawn particle at pos with velocity and acceleration
|
||
expirationtime = 1,
|
||
-- ^ Disappears after expirationtime seconds
|
||
size = 1,
|
||
collisiondetection = false,
|
||
-- ^ collisiondetection: if true collides with physical objects
|
||
collision_removal = false,
|
||
-- ^ collision_removal: if true then particle is removed when it collides,
|
||
-- ^ requires collisiondetection = true to have any effect
|
||
vertical = false,
|
||
-- ^ vertical: if true faces player using y axis only
|
||
texture = "image.png",
|
||
-- ^ Uses texture (string)
|
||
playername = "singleplayer",
|
||
-- ^ optional, if specified spawns particle only on the player's client
|
||
animation = {Tile Animation definition},
|
||
-- ^ optional, specifies how to animate the particle texture
|
||
glow = 0
|
||
-- ^ optional, specify particle self-luminescence in darkness
|
||
}
|
||
|
||
|
||
### `ParticleSpawner` definition (`add_particlespawner`)
|
||
|
||
{
|
||
amount = 1,
|
||
time = 1,
|
||
-- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
|
||
minpos = {x=0, y=0, z=0},
|
||
maxpos = {x=0, y=0, z=0},
|
||
minvel = {x=0, y=0, z=0},
|
||
maxvel = {x=0, y=0, z=0},
|
||
minacc = {x=0, y=0, z=0},
|
||
maxacc = {x=0, y=0, z=0},
|
||
minexptime = 1,
|
||
maxexptime = 1,
|
||
minsize = 1,
|
||
maxsize = 1,
|
||
-- ^ The particle's properties are random values in between the bounds:
|
||
-- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
|
||
-- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
|
||
collisiondetection = false,
|
||
-- ^ collisiondetection: if true uses collision detection
|
||
collision_removal = false,
|
||
-- ^ collision_removal: if true then particle is removed when it collides,
|
||
-- ^ requires collisiondetection = true to have any effect
|
||
attached = ObjectRef,
|
||
-- ^ attached: if defined, particle positions, velocities and accelerations
|
||
-- ^ are relative to this object's position and yaw.
|
||
vertical = false,
|
||
-- ^ vertical: if true faces player using y axis only
|
||
texture = "image.png",
|
||
-- ^ Uses texture (string)
|
||
playername = "singleplayer"
|
||
-- ^ Playername is optional, if specified spawns particle only on the player's client
|
||
}
|
||
|
||
### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`)
|
||
|
||
{
|
||
url = "http://example.org",
|
||
timeout = 10,
|
||
-- ^ Timeout for connection in seconds. Default is 3 seconds.
|
||
post_data = "Raw POST request data string" OR { field1 = "data1", field2 = "data2" },
|
||
-- ^ Optional, if specified a POST request with post_data is performed.
|
||
-- ^ Accepts both a string and a table. If a table is specified, encodes table
|
||
-- ^ as x-www-form-urlencoded key-value pairs.
|
||
-- ^ If post_data ist not specified, a GET request is performed instead.
|
||
user_agent = "ExampleUserAgent",
|
||
-- ^ Optional, if specified replaces the default minetest user agent with given string
|
||
extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
|
||
-- ^ Optional, if specified adds additional headers to the HTTP request. You must make sure
|
||
-- ^ that the header strings follow HTTP specification ("Key: Value").
|
||
multipart = boolean
|
||
-- ^ Optional, if true performs a multipart HTTP request. Default is false.
|
||
}
|
||
|
||
### `HTTPRequestResult` definition (`HTTPApiTable.fetch` callback, `HTTPApiTable.fetch_async_get`)
|
||
|
||
{
|
||
completed = true,
|
||
-- ^ If true, the request has finished (either succeeded, failed or timed out)
|
||
succeeded = true,
|
||
-- ^ If true, the request was succesful
|
||
timeout = false,
|
||
-- ^ If true, the request timed out
|
||
code = 200,
|
||
-- ^ HTTP status code
|
||
data = "response"
|
||
}
|