You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
6001 lines
251 KiB
6001 lines
251 KiB
Minetest Lua Modding API Reference |
|
================================== |
|
* More information at <http://www.minetest.net/> |
|
* Developer Wiki: <http://dev.minetest.net/> |
|
|
|
Introduction |
|
------------ |
|
Content and functionality can be added to Minetest using Lua scripting |
|
in run-time loaded mods. |
|
|
|
A mod is a self-contained bunch of scripts, textures and other related |
|
things, which 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, and to document it here. |
|
|
|
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 can contain the following files: |
|
|
|
* `game.conf`, which contains: |
|
* `name = <Human-readable full name of the game>` e.g. `name = Minetest` |
|
* Optionally, game.conf can also contain |
|
`disallowed_mapgens = <comma-separated mapgens>` |
|
e.g. `disallowed_mapgens = v5,v6,flat` |
|
These mapgens are removed from the list of mapgens for the game. |
|
* `minetest.conf`: |
|
Used to set default settings when running this game. |
|
* `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 advanced settings tab. |
|
* If the game contains a folder called `textures` the server will load it as a |
|
texturepack, overriding mod textures. |
|
Any server texturepack will override mod textures and the game texturepack. |
|
|
|
### 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 |
|
| |-- mod.conf |
|
| |-- screenshot.png |
|
| |-- settingtypes.txt |
|
| |-- init.lua |
|
| |-- models |
|
| |-- textures |
|
| | |-- modname_stuff.png |
|
| | `-- modname_something_else.png |
|
| |-- sounds |
|
| |-- media |
|
| |-- locale |
|
| `-- <custom data> |
|
`-- another |
|
|
|
### modname |
|
The location of this directory can be fetched by using |
|
`minetest.get_modpath(modname)`. |
|
|
|
### mod.conf |
|
A key-value store of mod details. |
|
|
|
* `name` - the mod name. Allows Minetest to determine the mod name even if the |
|
folder is wrongly named. |
|
* `description` - Description of mod to be shown in the Mods tab of the mainmenu. |
|
* `depends` - A comma separated list of dependencies. These are mods that must |
|
be loaded before this mod. |
|
* `optional_depends` - A comma separated list of optional dependencies. |
|
Like a dependency, but no error if the mod doesn't exist. |
|
|
|
Note: to support 0.4.x, please also provide depends.txt. |
|
|
|
### `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. |
|
|
|
### `depends.txt` |
|
**Deprecated:** you should use mod.conf instead. |
|
|
|
This file is used if there are no dependencies in mod.conf. |
|
|
|
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. This means that if the specified mod |
|
is missing, it does not prevent this mod from being loaded. |
|
|
|
### `description.txt` |
|
**Deprecated:** you should use mod.conf instead. |
|
|
|
This file is used if there is no description in mod.conf. |
|
|
|
A file containing a description to be shown in the Mods tab of the 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.settings` can be used to read custom or existing settings at load |
|
time, if necessary. (See `Settings`) |
|
|
|
### `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. |
|
|
|
### `locale` |
|
Translation files for the clients. (See `Translations`) |
|
|
|
Naming convention for registered textual names |
|
---------------------------------------------- |
|
Registered names should generally be in this format: |
|
|
|
`modname:<whatever>` |
|
|
|
`<whatever>` can have these 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 converts anything called `name` to `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 also set 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`. |
|
|
|
Mapgen aliases |
|
-------------- |
|
In a game, a certain number of these must be set to tell core mapgens which |
|
of the game's nodes are to be used by the core mapgens. For example: |
|
|
|
minetest.register_alias("mapgen_stone", "default:stone") |
|
|
|
### Aliases needed for all mapgens except Mapgen v6 |
|
|
|
Base terrain: |
|
|
|
"mapgen_stone" |
|
"mapgen_water_source" |
|
"mapgen_river_water_source" |
|
|
|
Caves: |
|
|
|
"mapgen_lava_source" |
|
|
|
Dungeons: |
|
|
|
Only needed for registered biomes where 'node_stone' is stone: |
|
"mapgen_cobble" |
|
"mapgen_stair_cobble" |
|
"mapgen_mossycobble" |
|
Only needed for registered biomes where 'node_stone' is desert stone: |
|
"mapgen_desert_stone" |
|
"mapgen_stair_desert_stone" |
|
Only needed for registered biomes where 'node_stone' is sandstone: |
|
"mapgen_sandstone" |
|
"mapgen_sandstonebrick" |
|
"mapgen_stair_sandstone_block" |
|
|
|
### Aliases needed for Mapgen v6 |
|
|
|
Terrain and biomes: |
|
|
|
"mapgen_stone" |
|
"mapgen_water_source" |
|
"mapgen_lava_source" |
|
"mapgen_dirt" |
|
"mapgen_dirt_with_grass" |
|
"mapgen_sand" |
|
"mapgen_gravel" |
|
"mapgen_desert_stone" |
|
"mapgen_desert_sand" |
|
"mapgen_dirt_with_snow" |
|
"mapgen_snowblock" |
|
"mapgen_snow" |
|
"mapgen_ice" |
|
|
|
Flora: |
|
|
|
"mapgen_tree" |
|
"mapgen_leaves" |
|
"mapgen_apple" |
|
"mapgen_jungletree" |
|
"mapgen_jungleleaves" |
|
"mapgen_junglegrass" |
|
"mapgen_pine_tree" |
|
"mapgen_pine_needles" |
|
|
|
Dungeons: |
|
|
|
"mapgen_cobble" |
|
"mapgen_stair_cobble" |
|
"mapgen_mossycobble" |
|
"mapgen_stair_desert_stone" |
|
|
|
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 overlaid 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 |
|
* `[crack:<n>:<p>` |
|
* `[cracko:<n>:<p>` |
|
* `[crack:<t>:<n>:<p>` |
|
* `[cracko:<t>:<n>:<p>` |
|
|
|
Parameters: |
|
* `<t>` = tile count (in each direction) |
|
* `<n>` = animation frame count |
|
* `<p>` = current animation frame |
|
|
|
Draw a step of the crack animation on the texture. |
|
`crack` draws it normally, while `cracko` lays it over, keeping transparent |
|
pixels intact. |
|
|
|
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. |
|
|
|
#### `[multiply:<color>` |
|
Multiplies texture colors with the given color. |
|
`<color>` is specified as a `ColorString`. |
|
Result is more like what you'd expect if you put a color on top of another |
|
color. Meaning white surfaces get a lot of your new color while black parts |
|
don't change very much. |
|
|
|
Hardware coloring |
|
----------------- |
|
The goal of hardware coloring is to simplify the creation of |
|
colorful nodes. If your textures use the same pattern, and they only |
|
differ in their color (like colored wool blocks), you can use hardware |
|
coloring instead of creating and managing many texture files. |
|
All of these methods use color multiplication (so a white-black texture |
|
with red coloring will result in red-black color). |
|
|
|
### Static coloring |
|
This method is useful if you wish to create nodes/items with |
|
the same texture, in different colors, each in a new node/item definition. |
|
|
|
#### Global color |
|
When you register an item or node, set its `color` field (which accepts a |
|
`ColorSpec`) to the desired color. |
|
|
|
An `ItemStack`s static color can be overwritten by the `color` metadata |
|
field. If you set that field to a `ColorString`, that color will be used. |
|
|
|
#### Tile color |
|
Each tile may have an individual static color, which overwrites every |
|
other coloring methods. To disable the coloring of a face, |
|
set its color to white (because multiplying with white does nothing). |
|
You can set the `color` property of the tiles in the node's definition |
|
if the tile is in table format. |
|
|
|
### Palettes |
|
For nodes and items which can have many colors, a palette is more |
|
suitable. A palette is a texture, which can contain up to 256 pixels. |
|
Each pixel is one possible color for the node/item. |
|
You can register one node/item, which can have up to 256 colors. |
|
|
|
#### Palette indexing |
|
When using palettes, you always provide a pixel index for the given |
|
node or `ItemStack`. The palette is read from left to right and from |
|
top to bottom. If the palette has less than 256 pixels, then it is |
|
stretched to contain exactly 256 pixels (after arranging the pixels |
|
to one line). The indexing starts from 0. |
|
|
|
Examples: |
|
|
|
* 16x16 palette, index = 0: the top left corner |
|
* 16x16 palette, index = 4: the fifth pixel in the first row |
|
* 16x16 palette, index = 16: the pixel below the top left corner |
|
* 16x16 palette, index = 255: the bottom right corner |
|
* 2 (width)x4 (height) palette, index=31: the top left corner. |
|
The palette has 8 pixels, so each pixel is stretched to 32 pixels, |
|
to ensure the total 256 pixels. |
|
* 2x4 palette, index=32: the top right corner |
|
* 2x4 palette, index=63: the top right corner |
|
* 2x4 palette, index=64: the pixel below the top left corner |
|
|
|
#### Using palettes with items |
|
When registering an item, set the item definition's `palette` field to |
|
a texture. You can also use texture modifiers. |
|
|
|
The `ItemStack`'s color depends on the `palette_index` field of the |
|
stack's metadata. `palette_index` is an integer, which specifies the |
|
index of the pixel to use. |
|
|
|
#### Linking palettes with nodes |
|
When registering a node, set the item definition's `palette` field to |
|
a texture. You can also use texture modifiers. |
|
The node's color depends on its `param2`, so you also must set an |
|
appropriate `paramtype2`: |
|
|
|
* `paramtype2 = "color"` for nodes which use their full `param2` for |
|
palette indexing. These nodes can have 256 different colors. |
|
The palette should contain 256 pixels. |
|
* `paramtype2 = "colorwallmounted"` for nodes which use the first |
|
five bits (most significant) of `param2` for palette indexing. |
|
The remaining three bits are describing rotation, as in `wallmounted` |
|
paramtype2. Division by 8 yields the palette index (without stretching the |
|
palette). These nodes can have 32 different colors, and the palette |
|
should contain 32 pixels. |
|
Examples: |
|
* `param2 = 17` is 2 * 8 + 1, so the rotation is 1 and the third (= 2 + 1) |
|
pixel will be picked from the palette. |
|
* `param2 = 35` is 4 * 8 + 3, so the rotation is 3 and the fifth (= 4 + 1) |
|
pixel will be picked from the palette. |
|
* `paramtype2 = "colorfacedir"` for nodes which use the first |
|
three bits of `param2` for palette indexing. The remaining |
|
five bits are describing rotation, as in `facedir` paramtype2. |
|
Division by 32 yields the palette index (without stretching the |
|
palette). These nodes can have 8 different colors, and the |
|
palette should contain 8 pixels. |
|
Examples: |
|
* `param2 = 17` is 0 * 32 + 17, so the rotation is 17 and the |
|
first (= 0 + 1) pixel will be picked from the palette. |
|
* `param2 = 35` is 1 * 32 + 3, so the rotation is 3 and the |
|
second (= 1 + 1) pixel will be picked from the palette. |
|
|
|
To colorize a node on the map, set its `param2` value (according |
|
to the node's paramtype2). |
|
|
|
### Conversion between nodes in the inventory and the on the map |
|
Static coloring is the same for both cases, there is no need |
|
for conversion. |
|
|
|
If the `ItemStack`'s metadata contains the `color` field, it will be |
|
lost on placement, because nodes on the map can only use palettes. |
|
|
|
If the `ItemStack`'s metadata contains the `palette_index` field, it is |
|
automatically transferred between node and item forms by the engine, |
|
when a player digs or places a colored node. |
|
You can disable this feature by setting the `drop` field of the node |
|
to itself (without metadata). |
|
To transfer the color to a special drop, you need a drop table. |
|
|
|
Example: |
|
|
|
minetest.register_node("mod:stone", { |
|
description = "Stone", |
|
tiles = {"default_stone.png"}, |
|
paramtype2 = "color", |
|
palette = "palette.png", |
|
drop = { |
|
items = { |
|
-- assume that mod:cobblestone also has the same palette |
|
{items = {"mod:cobblestone"}, inherit_color = true }, |
|
} |
|
} |
|
}) |
|
|
|
### Colored items in craft recipes |
|
Craft recipes only support item strings, but fortunately item strings |
|
can also contain metadata. Example craft recipe registration: |
|
|
|
minetest.register_craft({ |
|
output = minetest.itemstring_with_palette("wool:block", 3), |
|
type = "shapeless", |
|
recipe = { |
|
"wool:block", |
|
"dye:red", |
|
}, |
|
}) |
|
|
|
To set the `color` field, you can use `minetest.itemstring_with_color`. |
|
|
|
Metadata field filtering in the `recipe` field are not supported yet, |
|
so the craft output is independent of the color of the ingredients. |
|
|
|
Soft texture overlay |
|
-------------------- |
|
Sometimes hardware coloring is not enough, because it affects the |
|
whole tile. Soft texture overlays were added to Minetest to allow |
|
the dynamic coloring of only specific parts of the node's texture. |
|
For example a grass block may have colored grass, while keeping the |
|
dirt brown. |
|
|
|
These overlays are 'soft', because unlike texture modifiers, the layers |
|
are not merged in the memory, but they are simply drawn on top of each |
|
other. This allows different hardware coloring, but also means that |
|
tiles with overlays are drawn slower. Using too much overlays might |
|
cause FPS loss. |
|
|
|
For inventory and wield images you can specify overlays which |
|
hardware coloring does not modify. You have to set `inventory_overlay` |
|
and `wield_overlay` fields to an image name. |
|
|
|
To define a node overlay, simply set the `overlay_tiles` field of the node |
|
definition. These tiles are defined in the same way as plain tiles: |
|
they can have a texture name, color etc. |
|
To skip one face, set that overlay tile to an empty string. |
|
|
|
Example (colored grass block): |
|
|
|
minetest.register_node("default:dirt_with_grass", { |
|
description = "Dirt with Grass", |
|
-- Regular tiles, as usual |
|
-- The dirt tile disables palette coloring |
|
tiles = {{name = "default_grass.png"}, |
|
{name = "default_dirt.png", color = "white"}}, |
|
-- Overlay tiles: define them in the same style |
|
-- The top and bottom tile does not have overlay |
|
overlay_tiles = {"", "", |
|
{name = "default_grass_side.png", tileable_vertical = false}}, |
|
-- Global color, used in inventory |
|
color = "green", |
|
-- Palette in the world |
|
paramtype2 = "color", |
|
palette = "default_foilage.png", |
|
}) |
|
|
|
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 |
|
fade = 0.0, -- default, change to a value > 0 to fade the sound in |
|
pitch = 1.0, -- default |
|
} |
|
-- Play locationless to one player |
|
{ |
|
to_player = name, |
|
gain = 1.0, -- default |
|
fade = 0.0, -- default, change to a value > 0 to fade the sound in |
|
pitch = 1.0, -- default |
|
} |
|
-- Play locationless to one player, looped |
|
{ |
|
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}` |
|
* e.g. `{name = "default_place_node", gain = 1.0, pitch = 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.unregister_biome(name)` |
|
* Unregisters the biome name from engine, and deletes the entry with key |
|
* `name` from `minetest.registered_biome` |
|
|
|
* `minetest.register_ore(ore definition)` |
|
* returns an integer uniquely identifying the registered ore |
|
* added to `minetest.registered_ores` with the key of `ore.name` |
|
* 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 ranging from 0 to 255. 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" |
|
^ Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted". |
|
Leveled nodebox: |
|
The level of the top face of the nodebox is stored in param2. |
|
The other faces are defined by 'fixed = {}' like 'type = "fixed"' |
|
nodeboxes. |
|
The nodebox height is (param2 / 64) nodes. |
|
The maximum accepted value of param2 is 127. |
|
Rooted plantlike: |
|
The height of the 'plantlike' section is stored in param2. |
|
The height is (param2 / 16) nodes. |
|
paramtype2 == "degrotate" |
|
^ Only valid for "plantlike". The rotation of the node is stored in param2. |
|
Values range 0 - 179. The value stored in param2 is multiplied by two to |
|
get the actual rotation in degrees 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. |
|
paramtype2 == "color" |
|
^ `param2` tells which color is picked from the palette. |
|
The palette should have 256 pixels. |
|
paramtype2 == "colorfacedir" |
|
^ Same as `facedir`, but with colors. |
|
The first three bits of `param2` tells which color |
|
is picked from the palette. |
|
The palette should have 8 pixels. |
|
paramtype2 == "colorwallmounted" |
|
^ Same as `wallmounted`, but with colors. |
|
The first five bits of `param2` tells which color |
|
is picked from the palette. |
|
The palette should have 32 pixels. |
|
paramtype2 == "glasslikeliquidlevel" |
|
^ Only valid for "glasslike_framed" or "glasslike_framed_optional" |
|
drawtypes. |
|
param2 values 0-63 define 64 levels of internal liquid, 0 being empty and |
|
63 being full. |
|
Liquid texture is defined using `special_tiles = {"modname_tilename.png"},` |
|
|
|
Nodes can also contain extra data. See "Node Metadata". |
|
|
|
Node drawtypes |
|
-------------- |
|
There are a bunch of different looking node types. |
|
|
|
Look for examples in `games/minimal` or `games/minetest_game`. |
|
|
|
* `normal` |
|
* A node-sized cube. |
|
* `airlike` |
|
* Invisible, uses no texture. |
|
* `liquid` |
|
* The cubic source node for a liquid. |
|
* `flowingliquid` |
|
* The flowing version of a liquid, appears with various heights and slopes. |
|
* `glasslike` |
|
* Often used for partially-transparent nodes. |
|
* Only external sides of textures are visible. |
|
* `glasslike_framed` |
|
* All face-connected nodes are drawn as one volume within a surrounding |
|
frame. |
|
* The frame appearence is generated from the edges of the first texture |
|
specified in `tiles`. The width of the edges used are 1/16th of texture |
|
size: 1 pixel for 16x16, 2 pixels for 32x32 etc. |
|
* The glass 'shine' (or other desired detail) on each node face is supplied |
|
by the second texture specified in `tiles`. |
|
* `glasslike_framed_optional` |
|
* This switches between the above 2 drawtypes according to the menu setting |
|
'Connected Glass'. |
|
* `allfaces` |
|
* Often used for partially-transparent nodes. |
|
* External and internal sides of textures are visible. |
|
* `allfaces_optional` |
|
* Often used for leaves nodes. |
|
* This switches between `normal`, `glasslike` and `allfaces` according to |
|
the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves. |
|
* With 'Simple Leaves' selected, the texture specified in `special_tiles` |
|
is used instead, if present. This allows a visually thicker texture to be |
|
used to compensate for how `glasslike` reduces visual thickness. |
|
* `torchlike` |
|
* A single vertical texture. |
|
* If placed on top of a node, uses the first texture specified in `tiles`. |
|
* If placed against the underside of a node, uses the second texture |
|
specified in `tiles`. |
|
* If placed on the side of a node, uses the third texture specified in |
|
`tiles` and is perpendicular to that node. |
|
* `signlike` |
|
* A single texture parallel to, and mounted against, the top, underside or |
|
side of a node. |
|
* `plantlike` |
|
* Two vertical and diagonal textures at right-angles to each other. |
|
* See `paramtype2 == "meshoptions"` above for other options. |
|
* `firelike` |
|
* When above a flat surface, appears as 6 textures, the central 2 as |
|
`plantlike` plus 4 more surrounding those. |
|
* If not above a surface the central 2 do not appear, but the texture |
|
appears against the faces of surrounding nodes if they are present. |
|
* `fencelike` |
|
* A 3D model suitable for a wooden fence. |
|
* One placed node appears as a single vertical post. |
|
* Adjacently-placed nodes cause horizontal bars to appear between them. |
|
* `raillike` |
|
* Often used for tracks for mining carts. |
|
* Requires 4 textures to be specified in `tiles`, in order: Straight, |
|
curved, t-junction, crossing. |
|
* Each placed node automatically switches to a suitable rotated texture |
|
determined by the adjacent `raillike` nodes, in order to create a |
|
continuous track network. |
|
* Becomes a sloping node if placed against stepped nodes. |
|
* `nodebox` |
|
* Often used for stairs and slabs. |
|
* Allows defining nodes consisting of an arbitrary number of boxes. |
|
* See 'Node boxes' below for more information. |
|
* `mesh` |
|
* Uses models for nodes. |
|
* Tiles should hold model materials textures. |
|
* Only static meshes are implemented. |
|
* For supported model formats see Irrlicht engine documentation. |
|
* `plantlike_rooted` |
|
* Enables underwater `plantlike` without air bubbles around the nodes. |
|
* Consists of a base cube at the co-ordinates of the node plus a |
|
`plantlike` extension above with a height of `param2 / 16` nodes. |
|
* The `plantlike` extension visually passes through any nodes above the |
|
base cube without affecting them. |
|
* The base cube texture tiles are defined as normal, the `plantlike` |
|
extension uses the defined special tile, for example: |
|
`special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},` |
|
|
|
`*_optional` drawtypes need less rendering time if deactivated |
|
(always client-side). |
|
|
|
Node boxes |
|
---------- |
|
Node selection boxes are defined using "node boxes". |
|
|
|
A nodebox is defined as any of: |
|
|
|
{ |
|
-- A normal cube; the default in most things |
|
type = "regular" |
|
} |
|
{ |
|
-- A fixed box (or boxes) (facedir param2 is used, if applicable) |
|
type = "fixed", |
|
fixed = box OR {box1, box2, ...} |
|
} |
|
{ |
|
-- A variable height box (or boxes) with the top face position defined |
|
-- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"' |
|
-- by param2. |
|
-- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'. |
|
type = "leveled", |
|
fixed = box OR {box1, box2, ...} |
|
} |
|
{ |
|
-- A box like the selection box for torches |
|
-- (wallmounted param2 is used, if applicable) |
|
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, ...} |
|
-- The following `disconnected_*` boxes are the opposites of the |
|
-- `connect_*` ones above, i.e. when a node has no suitable neighbour |
|
-- on the respective side, the corresponding disconnected box is drawn. |
|
disconnected_top = box OR {box1, box2, ...} |
|
disconnected_bottom = box OR {box1, box2, ...} |
|
disconnected_front = box OR {box1, box2, ...} |
|
disconnected_left = box OR {box1, box2, ...} |
|
disconnected_back = box OR {box1, box2, ...} |
|
disconnected_right = box OR {box1, box2, ...} |
|
disconnected = box OR {box1, box2, ...} -- when there is *no* neighbour |
|
disconnected_sides = box OR {box1, box2, ...} -- when there are *no* |
|
neighbours to the sides |
|
} |
|
|
|
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}, |
|
|
|
Perlin noise |
|
------------ |
|
Perlin noise creates a continuously-varying value depending on the input values. |
|
Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes. |
|
The result is used during map generation to create the terrain shape, vary heat |
|
and humidity to distribute biomes, vary the density of decorations or vary the |
|
structure of ores. |
|
|
|
### Structure of perlin noise |
|
An 'octave' is a simple noise generator that outputs a value between -1 and 1. |
|
The smooth wavy noise it generates has a single characteristic scale, almost |
|
like a 'wavelength', so on its own does not create fine detail. |
|
Due to this perlin noise combines several octaves to create variation on |
|
multiple scales. Each additional octave has a smaller 'wavelength' than the |
|
previous. |
|
|
|
This combination results in noise varying very roughly between -2.0 and 2.0 and |
|
with an average value of 0.0, so `scale` and `offset` are then used to multiply |
|
and offset the noise variation. |
|
|
|
The final perlin noise variation is created as follows: |
|
|
|
noise = offset + scale * (octave1 + |
|
octave2 * persistence + |
|
octave3 * persistence ^ 2 + |
|
octave4 * persistence ^ 3 + |
|
...) |
|
|
|
Noise Parameters |
|
---------------- |
|
Noise Parameters are commonly called `NoiseParams`. |
|
|
|
### `offset` |
|
After the multiplication by `scale` this is added to the result and is the final |
|
step in creating the noise value. |
|
Can be positive or negative. |
|
|
|
### `scale` |
|
Once all octaves have been combined, the result is multiplied by this. |
|
Can be positive or negative. |
|
|
|
### `spread` |
|
For octave1, this is roughly the change of input value needed for a very large |
|
variation in the noise value generated by octave1. It is almost like a |
|
'wavelength' for the wavy noise variation. |
|
Each additional octave has a 'wavelength' that is smaller than the previous |
|
octave, to create finer detail. `spread` will therefore roughly be the typical |
|
size of the largest structures in the final noise variation. |
|
|
|
`spread` is a vector with values for x, y, z to allow the noise variation to be |
|
stretched or compressed in the desired axes. |
|
Values are positive numbers. |
|
|
|
### `seed` |
|
This is a whole number that determines the entire pattern of the noise |
|
variation. Altering it enables different noise patterns to be created. |
|
With other parameters equal, different seeds produce different noise patterns |
|
and identical seeds produce identical noise patterns. |
|
|
|
For this parameter you can randomly choose any whole number. Usually it is |
|
preferable for this to be different from other seeds, but sometimes it is useful |
|
to be able to create identical noise patterns. |
|
|
|
When used in mapgen this is actually a 'seed offset', it is added to the |
|
'world seed' to create the seed used by the noise, to ensure the noise has a |
|
different pattern in different worlds. |
|
|
|
### `octaves` |
|
The number of simple noise generators that are combined. |
|
A whole number, 1 or more. |
|
Each additional octave adds finer detail to the noise but also increases the |
|
noise calculation load. |
|
3 is a typical minimum for a high quality, complex and natural-looking noise |
|
variation. 1 octave has a slight 'gridlike' appearence. |
|
|
|
Choose the number of octaves according to the `spread` and `lacunarity`, and the |
|
size of the finest detail you require. For example: |
|
if `spread` is 512 nodes, `lacunarity` is 2.0 and finest detail required is 16 |
|
nodes, octaves will be 6 because the 'wavelengths' of the octaves will be |
|
512, 256, 128, 64, 32, 16 nodes. |
|
|
|
### `persistence` |
|
Each additional octave has an amplitude that is the amplitude of the previous |
|
octave multiplied by `persistence`, to reduce the amplitude of finer details, |
|
as is often helpful and natural to do so. |
|
Since this controls the balance of fine detail to large-scale detail |
|
`persistence` can be thought of as the 'roughness' of the noise. |
|
|
|
A positive or negative non-zero number, often between 0.3 and 1.0. |
|
A common medium value is 0.5, such that each octave has half the amplitude of |
|
the previous octave. |
|
This may need to be tuned when altering `lacunarity`; when doing so consider |
|
that a common medium value is 1 / lacunarity. |
|
|
|
### `lacunarity` |
|
Each additional octave has a 'wavelength' that is the 'wavelength' of the |
|
previous octave multiplied by 1 / lacunarity, to create finer detail. |
|
'lacunarity' is often 2.0 so 'wavelength' often halves per octave. |
|
|
|
A positive number no smaller than 1.0. |
|
Values below 2.0 create higher quality noise at the expense of requiring more |
|
octaves to cover a paticular range of 'wavelengths'. |
|
|
|
### `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 with a slightly gridded |
|
appearence. |
|
If no flags are specified (or defaults is), 2D noise is eased and 3D noise is |
|
not eased. |
|
Easing a 3D noise significantly increases the noise calculation load, so use |
|
with restraint. |
|
|
|
#### `absvalue` |
|
The absolute value of each octave's noise variation is used when combining the |
|
octaves. The final perlin noise variation is created as follows: |
|
|
|
noise = offset + scale * (abs(octave1) + |
|
abs(octave2) * persistence + |
|
abs(octave3) * persistence ^ 2 + |
|
abs(octave4) * persistence ^ 3 + |
|
...) |
|
|
|
###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", |
|
} |
|
|
|
For 2D noise the Z component of `spread` is still defined but is ignored. |
|
A single noise parameter table can be used for 2D or 3D noise. |
|
|
|
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 emanates 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 different 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, |
|
lacunarity = 2.0, |
|
flags = "eased", |
|
}, |
|
noise_threshold = 1.6 |
|
|
|
**WARNING**: Use this ore type *very* sparingly since it is ~200x more |
|
computationally expensive than any other ore. |
|
|
|
### `stratum` |
|
Creates a single undulating ore stratum that is continuous across mapchunk |
|
borders and horizontally spans the world. |
|
|
|
The 2D perlin noise described by `noise_params` defines the Y co-ordinate of |
|
the stratum midpoint. The 2D perlin noise described by `np_stratum_thickness` |
|
defines the stratum's vertical thickness (in units of nodes). Due to being |
|
continuous across mapchunk borders the stratum's vertical thickness is |
|
unlimited. |
|
|
|
If the noise parameter `noise_params` is omitted the ore will occur from y_min |
|
to y_max in a simple horizontal stratum. |
|
|
|
A parameter `stratum_thickness` can be provided instead of the noise parameter |
|
`np_stratum_thickness`, to create a constant thickness. |
|
|
|
Leaving out one or both noise parameters makes the ore generation less |
|
intensive, useful when adding multiple strata. |
|
|
|
`y_min` and `y_max` define the limits of the ore generation and for performance |
|
reasons should be set as close together as possible but without clipping the |
|
stratum's Y variation. |
|
|
|
Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a |
|
solid-ore stratum would require a `clust_scarcity` of 1. |
|
|
|
The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and |
|
`random_factor` are ignored by this ore type. |
|
|
|
Ore attributes |
|
-------------- |
|
See section "Flag Specifier Format". |
|
|
|
Currently supported flags: |
|
`puff_cliffs`, `puff_additive_composition`. |
|
|
|
### `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 |
|
occurring. (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. |
|
|
|
### Amount and wear |
|
All item stacks have an amount between 0 to 65535. It is 1 by |
|
default. Tool item stacks can not have an amount greater than 1. |
|
|
|
Tools use a wear (=damage) value ranging from 0 to 65535. The |
|
value 0 is the default and used is for unworn tools. The values |
|
1 to 65535 are used for worn tools, where a higher value stands for |
|
a higher wear. Non-tools always have a wear value of 0. |
|
|
|
### Item formats |
|
Items and item stacks can exist in three formats: Serializes, table format |
|
and `ItemStack`. |
|
|
|
#### Serialized |
|
This is called "stackstring" or "itemstring". It is a simple string with |
|
1-3 components: the full item identifier, an optional amount and an optional |
|
wear value. Syntax: |
|
|
|
<identifier> [<amount>[ <wear>]] |
|
|
|
Examples: |
|
|
|
* `'default:apple'`: 1 apple |
|
* `'default:dirt 5'`: 5 dirt |
|
* `'default:pick_stone'`: a new stone pickaxe |
|
* `'default:pick_wood 1 21323'`: a wooden pickaxe, ca. 1/3 worn out |
|
|
|
#### 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 |
|
* `punch_operable`: For entities; 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. |
|
* `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 reducing tool wear) |
|
* `2`: the node always gets the digging time 0.5 seconds (rail, sign) |
|
* `3`: the node always gets the digging time 0 seconds (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 |
|
* `slippery`: Players and items will slide on the node. |
|
Slipperiness rises steadily with `slippery` value, starting at 1. |
|
|
|
|
|
### Known damage and digging time defining groups |
|
* `crumbly`: dirt, sand |
|
* `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. |
|
|
|
If the result digging time is 0, a delay of 0.15 seconds is added between |
|
digging nodes; If the player releases LMB after digging, this delay is set to 0, |
|
i.e. players can more quickly click the nodes away instead of holding LMB. |
|
|
|
#### 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, damage) |
|
|
|
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. |
|
* `damage` damage that will be done to entity |
|
Return value of this function will determine if damage is done by this function |
|
(retval true) or shall be done by engine (retval false) |
|
|
|
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`. |
|
|
|
Node 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" |
|
} |
|
}) |
|
|
|
Item Metadata |
|
------------- |
|
Item stacks can store metadata too. See `ItemStackMetaRef`. |
|
|
|
Item metadata only contains a key-value store. |
|
|
|
Some of the values in the key-value store are handled specially: |
|
|
|
* `description`: Set the item stack's description. Defaults to |
|
`idef.description`. |
|
* `color`: A `ColorString`, which sets the stack's color. |
|
* `palette_index`: If the item has a palette, this is used to get the |
|
current color from the palette. |
|
|
|
Example stuff: |
|
|
|
local meta = stack:get_meta() |
|
meta:set_string("key", "value") |
|
print(dump(meta:to_table())) |
|
|
|
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. |
|
|
|
WARNING: Minetest allows you to add elements to every single formspec instance |
|
using player:set_formspec_prepend(), which may be the reason backgrounds are |
|
appearing when you don't expect them to. See `no_prepend[]` |
|
|
|
### 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>;]` |
|
|
|
#### `position[<X>,<Y>]` |
|
* Must be used after `size` element. |
|
* Defines the position on the game window of the formspec's `anchor` point. |
|
* For X and Y, 0.0 and 1.0 represent opposite edges of the game window, |
|
for example: |
|
* [0.0, 0.0] sets the position to the top left corner of the game window. |
|
* [1.0, 1.0] sets the position to the bottom right of the game window. |
|
* Defaults to the center of the game window [0.5, 0.5]. |
|
|
|
#### `anchor[<X>,<Y>]` |
|
* Must be used after both `size` and `position` (if present) elements. |
|
* Defines the location of the anchor point within the formspec. |
|
* For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, |
|
for example: |
|
* [0.0, 1.0] sets the anchor to the bottom left corner of the formspec. |
|
* [1.0, 0.0] sets the anchor to the top right of the formspec. |
|
* Defaults to the center of the formspec [0.5, 0.5]. |
|
|
|
* `position` and `anchor` elements need suitable values to avoid a formspec |
|
extending off the game window due to particular game window sizes. |
|
|
|
#### `no_prepend[]` |
|
* Must be used after the `size`, `position`, and `anchor` elements (if present). |
|
* Disables player:set_formspec_prepend() from applying to this formspec. |
|
|
|
#### `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 |
|
* if the text overflows a vertical scrollbar is added |
|
* if the name is empty the textarea is readonly, the label is not displayed. |
|
|
|
#### `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 |
|
* Fixed button height. It will be vertically centred on `h` |
|
* `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: |
|
|
|
* `minetest.get_color_escape_sequence(color)`: |
|
* `color` is a ColorString |
|
* The escape sequence sets the text color to `color` |
|
* `minetest.colorize(color, message)`: |
|
* Equivalent to: |
|
`minetest.get_color_escape_sequence(color) .. |
|
message .. |
|
minetest.get_color_escape_sequence("#ffffff")` |
|
* `minetest.get_background_escape_sequence(color)` |
|
* `color` is a ColorString |
|
* The escape sequence sets the background of the whole text element to |
|
`color`. Only defined for item descriptions and tooltips. |
|
* `minetest.strip_foreground_colors(str)` |
|
* Removes foreground colors added by `get_color_escape_sequence`. |
|
* `minetest.strip_background_colors(str)` |
|
* Removes background colors added by `get_background_escape_sequence`. |
|
* `minetest.strip_colors(str)` |
|
* Removes all color escape sequences. |
|
|
|
Spatial Vectors |
|
--------------- |
|
For the following functions, `v`, `v1`, `v2` are vectors, |
|
`p1`, `p2` are positions: |
|
|
|
* `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 of `a`, `b`, `c` are defined numbers. |
|
* `vector.direction(p1, p2)`: |
|
* Returns a vector of length 1 with direction `p1` to `p2`. |
|
* If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`. |
|
* `vector.distance(p1, p2)`: |
|
* Returns zero or a positive number, the distance between `p1` and `p2`. |
|
* `vector.length(v)`: |
|
* Returns zero or a positive number, the length of vector `v`. |
|
* `vector.normalize(v)`: |
|
* Returns a vector of length 1 with direction of vector `v`. |
|
* If `v` has zero length, returns `{x = 0, y = 0, z = 0}`. |
|
* `vector.floor(v)`: |
|
* Returns a vector, each dimension rounded down. |
|
* `vector.round(v)`: |
|
* Returns a vector, each dimension rounded to nearest integer. |
|
* `vector.apply(v, func)`: |
|
* Returns a vector where the function `func` has been applied to each |
|
component. |
|
* `vector.equals(v1, v2)`: |
|
* Returns a boolean, `true` if the vectors are identical. |
|
* `vector.sort(v1, v2)`: |
|
* Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`. |
|
|
|
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)`: returns a string which makes `obj` |
|
human-readable, handles reference loops. |
|
* `obj`: arbitrary variable |
|
* `name`: string, default: `"_"` |
|
* `dumped`: table, default: `{}` |
|
* `dump(obj, dumped)`: returns a string which makes `obj` human-readable |
|
* `obj`: arbitrary variable |
|
* `dumped`: table, default: `{}` |
|
* `math.hypot(x, y)` |
|
* Get the hypotenuse of a triangle with legs x and y. |
|
Useful for distance calculation. |
|
* `math.sign(x, tolerance)`: returns `-1`, `0` or `1` |
|
* Get the sign of a number. |
|
* tolerance: number, default: `0.0` |
|
* If the absolute value of `x` is within the `tolerance` or `x` is NaN, |
|
`0` is returned. |
|
* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)` |
|
* `separator`: string, default: `","` |
|
* `include_empty`: boolean, default: `false` |
|
* `max_splits`: number, if it's positive, splits aren't limited, |
|
default: `-1` |
|
* `sep_is_pattern`: boolean, it specifies whether separator is a plain |
|
string or a pattern (regex), default: `false` |
|
* e.g. `"a,b":split","` returns `{"a","b"}` |
|
* `string:trim()`: returns the string without whitespace pre- and suffixes |
|
* e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"` |
|
* `minetest.wrap_text(str, limit, as_table)`: returns a string or table |
|
* Adds newlines to the string to keep it within the specified character |
|
limit |
|
* Note that the returned lines may be longer than the limit since it only |
|
splits at word borders. |
|
* `limit`: number, maximal amount of characters in one line |
|
* `as_table`: boolean, if set to true, a table of lines instead of a string |
|
is returned, default: `false` |
|
* `minetest.pos_to_string(pos, decimal_places)`: returns string `"(X,Y,Z)"` |
|
* `pos`: table {x=X, y=Y, z=Z} |
|
* Converts the position `pos` to a human-readable, printable string |
|
* `decimal_places`: number, if specified, the x, y and z values of |
|
the position are rounded to the given decimal place. |
|
* `minetest.string_to_pos(string)`: returns a position or `nil` |
|
* Same but in reverse. |
|
* If the string can't be parsed to a position, nothing is returned. |
|
* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions |
|
* Converts a string representing an area box into two positions |
|
* `minetest.formspec_escape(string)`: returns a string |
|
* escapes the characters "[", "]", "\", "," and ";", which can not be used |
|
in formspecs. |
|
* `minetest.is_yes(arg)` |
|
* returns true if passed 'y', 'yes', 'true' or a number that isn't zero. |
|
* `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.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a |
|
position. |
|
* returns the exact position on the surface of a pointed node |
|
|
|
Translations |
|
------------ |
|
|
|
Texts can be translated client-side with the help of `minetest.translate` and |
|
translation files. |
|
|
|
### Translating a string |
|
Two functions are provided to translate strings: `minetest.translate` and |
|
`minetest.get_translator`. |
|
|
|
* `minetest.get_translator(textdomain)` is a simple wrapper around |
|
`minetest.translate`, and `minetest.get_translator(textdomain)(str, ...)` is |
|
equivalent to `minetest.translate(textdomain, str, ...)`. |
|
It is intended to be used in the following way, so that it avoids verbose |
|
repetitions of `minetest.translate`: |
|
|
|
local S = minetest.get_translator(textdomain) |
|
S(str, ...) |
|
|
|
As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead. |
|
|
|
* `minetest.translate(textdomain, str, ...)` translates the string `str` with |
|
the given `textdomain` for disambiguation. The textdomain must match the |
|
textdomain specified in the translation file in order to get the string |
|
translated. This can be used so that a string is translated differently in |
|
different contexts. |
|
It is advised to use the name of the mod as textdomain whenever possible, to |
|
avoid clashes with other mods. |
|
This function must be given a number of arguments equal to the number of |
|
arguments the translated string expects. |
|
Arguments are literal strings -- they will not be translated, so if you want |
|
them to be, they need to come as outputs of `minetest.translate` as well. |
|
|
|
For instance, suppose we want to translate "@1 Wool" with "@1" being replaced |
|
by the translation of "Red". We can do the following: |
|
|
|
local S = minetest.get_translator() |
|
S("@1 Wool", S("Red")) |
|
|
|
This will be displayed as "Red Wool" on old clients and on clients that do |
|
not have localization enabled. However, if we have for instance a translation |
|
file named `wool.fr.tr` containing the following: |
|
|
|
@1 Wool=Laine @1 |
|
Red=Rouge |
|
|
|
this will be displayed as "Laine Rouge" on clients with a French locale. |
|
|
|
### Operations on translated strings |
|
|
|
The output of `minetest.translate` is a string, with escape sequences adding |
|
additional information to that string so that it can be translated on the |
|
different clients. In particular, you can't expect operations like string.length |
|
to work on them like you would expect them to, or string.gsub to work in the |
|
expected manner. However, string concatenation will still work as expected |
|
(note that you should only use this for things like formspecs; do not translate |
|
sentences by breaking them into parts; arguments should be used instead), and |
|
operations such as `minetest.colorize` which are also concatenation. |
|
|
|
### Translation file format |
|
A translation file has the suffix `.[lang].tr`, where `[lang]` is the language |
|
it corresponds to. |
|
The file should be a text file, with the following format: |
|
|
|
* Lines beginning with `# textdomain:` (the space is significant) can be used |
|
to specify the text domain of all following translations in the file. |
|
* All other empty lines or lines beginning with `#` are ignored. |
|
* Other lines should be in the format `original=translated`. Both `original` |
|
and `translated` can contain escape sequences beginning with `@` to insert |
|
arguments, literal `@`, `=` or newline (See ### Escapes below). |
|
There must be no extraneous whitespace around the `=` or at the beginning or |
|
the end of the line. |
|
|
|
### Escapes |
|
Strings that need to be translated can contain several escapes, preceded by `@`. |
|
|
|
* `@@` acts as a literal `@`. |
|
* `@n`, where `n` is a digit between 1 and 9, is an argument for the translated |
|
string that will be inlined when translation. Due to how translations are |
|
implemented, the original translation string **must** have its arguments in |
|
increasing order, without gaps or repetitions, starting from 1. |
|
* `@=` acts as a literal `=`. It is not required in strings given to |
|
`minetest.translate`, but is in translation files to avoid being confused |
|
with the `=` separating the original from the translation. |
|
* `@\n` (where the `\n` is a literal newline) acts as a literal newline. |
|
As with `@=`, this escape is not required in strings given to |
|
`minetest.translate`, but is in translation files. |
|
* `@n` acts as a literal newline as well. |
|
|
|
`minetest` namespace reference |
|
------------------------------ |
|
|
|
### Utilities |
|
|
|
* `minetest.get_current_modname()`: returns the currently loading mod's name, |
|
when 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 |
|
|
|
{ |
|
glasslike_framed = true, |
|
nodebox_as_selectionbox = true, |
|
chat_send_player_param3 = true, |
|
get_all_craft_recipes_works = true, |
|
use_texture_alpha = true, |
|
-- ^ The transparency channel of textures can optionally be used on nodes |
|
no_legacy_abms = true, |
|
-- ^ Tree and grass ABMs are no longer done from C++ |
|
texture_names_parens = true, |
|
-- ^ Texture grouping is possible using parentheses |
|
area_store_custom_ids = true, |
|
-- ^ Unique Area ID for AreaStore:insert_area |
|
add_entity_with_staticdata = true, |
|
-- ^ add_entity supports passing initial staticdata to on_activate |
|
no_chat_message_prediction = true, |
|
-- ^ Chat messages are no longer predicted |
|
object_use_texture_alpha = true |
|
-- ^ The transparency channel of textures can optionally be used on |
|
-- objects (ie: players and lua entities) |
|
} |
|
* `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 a 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 |
|
protocol_version = 32, -- protocol version used by client |
|
-- following information is available on debug build only!!! |
|
-- DO NOT USE IN MODS |
|
--ser_vers = 26, -- serialization 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.safe_file_write(path, content)`: returns boolean indicating success |
|
* Replaces contents of file at path with new contents in a safe (atomic) |
|
way. Use this instead of below code when writing e.g. database files: |
|
`local f = io.open(path, "wb"); f:write(content); f:close()` |
|
* `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 verifiable. Compatible forks will have a different name and |
|
version entirely. To check for the presence of engine features, test |
|
whether the functions exported by the wanted features exist. For example: |
|
`if minetest.check_for_falling then ... end`. |
|
* `minetest.sha1(data, [raw])`: returns the sha1 hash of data |
|
* `data`: string of data to hash |
|
* `raw`: return raw bytes instead of hex digits, default: false |
|
|
|
### 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)` |
|
* Also use this to set the 'mapgen aliases' needed in a game for the core |
|
* mapgens. See 'Mapgen aliases' section above. |
|
* `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` |
|
* `placer` may be any valid ObjectRef or nil. |
|
* **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_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, reason), 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. |
|
* `reason`: a PlayerHPChangeReason table. |
|
* The `type` field will have one of the following values: |
|
* `set_hp` - A mod or the engine called `set_hp` without |
|
giving a type - use this for custom damage types. |
|
* `punch` - Was punched. `reason.object` will hold the puncher, or nil if none. |
|
* `fall` |
|
* `node_damage` - damage_per_second from a neighbouring node. |
|
* `drown` |
|
* `respawn` |
|
* Any of the above types may have additional fields from mods. |
|
* `reason.from` will be `mod` or `engine`. |
|
* `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_dieplayer(func(ObjectRef, reason))` |
|
* Called when a player dies |
|
* `reason`: a PlayerHPChangeReason table, see register_on_player_hpchange |
|
* `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_auth_fail(func(name, ip))` |
|
* Called when a client attempts to log into an account but supplies the |
|
wrong password. |
|
* `ip`: The IP address of the client. |
|
* `name`: The account the client attempted to log into. |
|
* `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). |
|
* `minetest.register_on_priv_grant(function(name, granter, priv))` |
|
* Called when `granter` grants the priv `priv` to `name`. |
|
* Note that the callback will be called twice if it's done by a player, |
|
once with granter being the player name, and again with granter being nil. |
|
* `minetest.register_on_priv_revoke(function(name, revoker, priv))` |
|
* Called when `revoker` revokes the priv `priv` from `name`. |
|
* Note that the callback will be called twice if it's done by a player, |
|
once with revoker being the player name, and again with revoker being nil. |
|
* `minetest.register_can_bypass_userlimit(function(name, ip))` |
|
* Called when `name` user connects with `ip`. |
|
* Return `true` to by pass the player limit |
|
* `minetest.register_on_modchannel_message(func(channel_name, sender, message))` |
|
* Called when an incoming mod channel message is received |
|
* You should have joined some channels to receive events. |
|
* If message comes from a server mod, `sender` field is an empty string. |
|
|
|
### Other registration functions |
|
* `minetest.register_chatcommand(cmd, chatcommand definition)` |
|
* 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. |
|
* `on_grant(name, granter_name)`: Called when given to player `name` by |
|
`granter_name`. |
|
`granter_name` will be nil if the priv was granted by a mod. |
|
* `on_revoke(name, revoker_name)`: Called when taken from player `name` by |
|
`revoker_name`. |
|
`revoker_name` will be nil if the priv was revoked by a mod |
|
* Note that the above two callbacks will be called twice if a player is |
|
responsible, once with the player name, and then with a nil player name. |
|
* Return true in the above callbacks to stop register_on_priv_grant or |
|
revoke being called. |
|
* `minetest.register_authentication_handler(authentication handler definition)` |
|
* Registers an auth handler that overrides the builtin one |
|
* This function can be called by a single mod once only. |
|
|
|
### Setting-related |
|
* `minetest.settings`: Settings object containing all of the settings from the |
|
main config file (`minetest.conf`). |
|
* `minetest.setting_get_pos(name)`: Loads a setting from the main settings and |
|
parses it as a position (in the format `(1,2,3)`). Returns a position or nil. |
|
|
|
### Authentication |
|
* `minetest.string_to_privs(str)`: returns `{priv1=true,...}` |
|
* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."` |
|
* Convert between two privilege representations |
|
* `minetest.get_player_privs(name) -> {priv1=true,...}` |
|
* `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.check_password_entry(name, entry, password)` |
|
* Returns true if the "password entry" for a player with name matches given |
|
password, false otherwise. |
|
* The "password entry" is the password representation generated by the |
|
engine as returned as part of a `get_auth()` call on the auth handler. |
|
* Only use this function for making it possible to log in via password from |
|
external protocols such as IRC, other uses 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.get_player_ip(name)`: returns an IP address string for the player |
|
`name`. |
|
* The player needs to be online for this to be successful. |
|
|
|
* `minetest.get_auth_handler()`: Return the currently active auth handler |
|
* See the `Authentication handler definition` |
|
* Use this to e.g. get the authentication data for a player: |
|
`local auth_data = minetest.get_auth_handler().get_auth(playername)` |
|
* `minetest.notify_authentication_modified(name)` |
|
* Must be called by the authentication handler for privilege changes. |
|
* `name`: string; if omitted, all auth data should be considered modified |
|
* `minetest.set_player_password(name, password_hash)`: Set password hash of |
|
player `name`. |
|
* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player |
|
`name`. |
|
* `minetest.auth_reload()` |
|
* See `reload()` in authentication handler definition |
|
|
|
`minetest.set_player_password`, `minetest_set_player_privs`, |
|
`minetest_get_player_privs` and `minetest.auth_reload` call the authentication |
|
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 to `minetest.set_node` |
|
* Set node at position `pos` |
|
* `node`: table `{name=string, param1=number, param2=number}` |
|
* If param1 or param2 is omitted, it's set to `0`. |
|
* e.g. `minetest.set_node({x=0, y=10, z=0}, {name="default:wood"})` |
|
* `minetest.bulk_set_node({pos1, pos2, pos3, ...}, node)` |
|
* Set node on all positions set in the first argument. |
|
* e.g. `minetest.bulk_set_node({{x=0, y=1, z=1}, {x=1, y=2, z=2}}, {name="default:stone"})` |
|
* For node specification or position syntax see `minetest.set_node` call |
|
* Faster than set_node due to single call, but still considerably slower |
|
than Lua Voxel Manipulators (LVM) for large numbers of nodes. |
|
Unlike LVMs, this will call node callbacks. It also allows setting nodes |
|
in spread out positions which would cause LVMs to waste memory. |
|
For setting a cube, this is 1.3x faster than set_node whereas LVM is 20 |
|
times faster. |
|
* `minetest.swap_node(pos, node)` |
|
* Set node at position, but don't remove metadata |
|
* `minetest.remove_node(pos)` |
|
* By default it does the same as `minetest.set_node(pos, {name="air"})` |
|
* `minetest.get_node(pos)` |
|
* Returns the node at the given position as table in the format |
|
`{name="node_name", param1=0, param2=0}`, |
|
returns `{name="ignore", param1=0, param2=0}` 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.spawn_falling_node(pos)` |
|
* Change node into falling node |
|
* Returns `true` if successful, `false` on failure |
|
|
|
* `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)`: returns a list of |
|
ObjectRefs. |
|
* `radius`: using an euclidean metric |
|
* `minetest.set_timeofday(val)` |
|
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday |
|
* `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. |
|
* accounts for time changes. |
|
* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns |
|
pos or `nil`. |
|
* `radius`: using a maximum metric |
|
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` |
|
* `search_center` is an optional boolean (default: `false`) |
|
If true `pos` is also checked for the nodes |
|
* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of |
|
positions. |
|
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` |
|
* First return value: Table with all node positions |
|
* Second return value: Table with the count of each node with the node name |
|
as index. |
|
* Area volume is limited to 4,096,000 nodes |
|
* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a |
|
list of positions. |
|
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` |
|
* Return value: Table with all node positions with a node air above |
|
* Area volume is limited to 4,096,000 nodes |
|
* `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. |
|
* `minetest.get_gen_notify()` |
|
* Returns a flagstring and a table with the `deco_id`s. |
|
* `minetest.get_decoration_id(decoration_name) |
|
* Returns the decoration ID number for the provided decoration name string, |
|
or `nil` on failure. |
|
* `minetest.get_mapgen_object(objectname)` |
|
* Return requested mapgen object if available (see "Mapgen objects") |
|
* `minetest.get_heat(pos)` |
|
* Returns the heat at the position, or `nil` on failure. |
|
* `minetest.get_humidity(pos)` |
|
* Returns the humidity at the position, or `nil` on failure. |
|
* `minetest.get_biome_data(pos)` |
|
* Returns a table containing: |
|
* `biome` the biome id of the biome at that position |
|
* `heat` the heat at the position |
|
* `humidity` the humidity at the position |
|
* Or returns `nil` on failure. |
|
* `minetest.get_biome_id(biome_name)` |
|
* Returns the biome id, as used in the biomemap Mapgen object and returned |
|
by `minetest.get_biome_data(pos)`, for a given biome_name string. |
|
* `minetest.get_biome_name(biome_id)` |
|
* Returns the biome name string for the provided biome id, or `nil` on |
|
failure. |
|
* If no biomes have been registered, such as in mgv6, returns `default`. |
|
* `minetest.get_mapgen_params()` |
|
* Deprecated: use `minetest.get_mapgen_setting(name)` instead. |
|
* Returns a table containing: |
|
* `mgname` |
|
* `seed` |
|
* `chunksize` |
|
* `water_level` |
|
* `flags` |
|
* `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` |
|
* `chunksize` |
|
* `water_level` |
|
* `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: |
|
* `minetest.EMERGE_CANCELLED` |
|
* `minetest.EMERGE_ERRORED` |
|
* `minetest.EMERGE_FROM_MEMORY` |
|
* `minetest.EMERGE_FROM_DISK` |
|
* `minetest.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)`: returns `boolean, pos` |
|
* Checks if there is anything other than air between pos1 and pos2. |
|
* Returns false if something is blocking the sight. |
|
* Returns the position of the blocking node when `false` |
|
* `pos1`: First position |
|
* `pos2`: Second position |
|
* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast` |
|
* Creates a `Raycast` object. |
|
* `pos1`: start of the ray |
|
* `pos2`: end of the ray |
|
* `objects` : if false, only nodes will be returned. Default is `true`. |
|
* `liquids' : if false, liquid nodes won't be returned. Default is `false`. |
|
* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)` |
|
* returns table containing path |
|
* returns a table of 3D points representing a path from `pos1` to `pos2` or |
|
`nil`. |
|
* `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 |
|
* `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 |
|
* `minetest.fix_light(pos1, pos2)`: returns `true`/`false` |
|
* resets the light in a cuboid-shaped part of |
|
the map and removes lighting bugs. |
|
* Loads the area if it is not loaded. |
|
* `pos1` is the corner of the cuboid with the least coordinates |
|
(in node coordinates), inclusive. |
|
* `pos2` is the opposite corner of the cuboid, inclusive. |
|
* The actual updated cuboid might be larger than the specified one, |
|
because only whole map blocks can be updated. |
|
The actual updated area consists of those map blocks that intersect |
|
with the given cuboid. |
|
* However, the neighborhood of the updated area might change |
|
as well, as light can spread out of the cuboid, also light |
|
might be removed. |
|
* returns `false` if the area is not fully generated, |
|
`true` otherwise |
|
* `minetest.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. |
|
* `minetest.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. |
|
* `minetest.get_spawn_level(x, z)` |
|
* Returns a player spawn y co-ordinate for the provided (x, z) |
|
co-ordinates, or `nil` for an unsuitable spawn point. |
|
* For most mapgens a 'suitable spawn point' is one with y between |
|
`water_level` and `water_level + 16`, and in mgv7 well away from rivers, |
|
so `nil` will be returned for many (x, z) co-ordinates. |
|
* The spawn level returned is for a player spawn in unmodified terrain. |
|
* The spawn level is intentionally above terrain level to cope with |
|
full-node biome 'dust' nodes. |
|
|
|
### Mod channels |
|
You can find mod channels communication scheme in `docs/mod_channels.png`. |
|
|
|
* `minetest.mod_channel_join(channel_name)` |
|
* Server joins channel `channel_name`, and creates it if necessary. You |
|
should listen from incoming messages with |
|
`minetest.register_on_modchannel_message` call to receive incoming |
|
messages. |
|
|
|
### Inventory |
|
`minetest.get_inventory(location)`: returns an `InvRef` |
|
|
|
* `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 |
|
|