:`
* `[cracko::`
* `[crack:::`
* `[cracko:::`
Parameters:
* ``: tile count (in each direction)
* ``: animation frame count
* ``: 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:x:,=:,=:...`
* ``: width
* ``: height
* ``: x position
* ``: y position
* ``: texture to combine
Creates a texture of size `` times `` and blits the listed files to their
specified coordinates.
Example:
[combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
#### `[resize:x`
Resizes the texture to the given dimensions.
Example:
default_sandstone.png^[resize:16x16
#### `[opacity:`
Makes the base image transparent according to the given ratio.
`r` must be between 0 (transparent) and 255 (opaque).
Example:
default_sandstone.png^[opacity:127
#### `[invert:`
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:,,`
Convert one color to transparency.
Example:
default_cobble.png^[makealpha:128,128,128
#### `[transform`
* ``: transformation(s) to apply
Rotates and/or flips the image.
`` 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{{{`
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::`
Blit the lower ``% part of `` on the texture.
Example:
base.png^[lowpart:25:overlay.png
#### `[verticalframe::`
* ``: animation frame count
* ``: current animation frame
Crops the texture to a frame of a vertical animation.
Example:
default_torch_animated.png^[verticalframe:16:8
#### `[mask:`
Apply a mask to the base image.
The mask is applied using binary AND.
#### `[sheet:x:,`
Retrieves a tile at position x,y from the base image
which it assumes to be a tilesheet with dimensions w,h.
#### `[colorize::`
Colorize the textures with the given color.
`` is specified as a `ColorString`.
`` 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 ``. If
omitted, the alpha of `` will be used as the ratio. If it is
the word "`alpha`", then each texture pixel will contain the RGB of
`` and the alpha of `` multiplied by the alpha of the
texture pixel.
#### `[multiply:`
Multiplies texture colors with the given 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.
#### `[png:`
Embed a base64 encoded PNG image in the texture string.
You can produce a valid string for this by calling
`minetest.encode_base64(minetest.encode_png(tex))`,
refer to the documentation of these functions for details.
You can use this to send disposable images such as captchas
to individual clients, or render things that would be too
expensive to compose with `[combine:`.
IMPORTANT: Avoid sending large images this way.
This is not a replacement for asset files, do not use it to do anything
that you could instead achieve by just using a file.
In particular consider `minetest.dynamic_add_media` and test whether
using other texture modifiers could result in a shorter string than
embedding a whole image, this may vary by use case.
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 method. 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) x 4 (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 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"}},
-- 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 at 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 = ,
gain = 1.0, -- default
max_hear_distance = 32, -- default, uses an euclidean metric
loop = true,
}
-- Play at a location, heard by anyone *but* the given player
{
pos = {x = 32, y = 0, z = 100},
max_hear_distance = 40,
exclude_player = name,
}
Looped sounds must either be connected to an object or played locationless to
one player using `to_player = name`.
A positional sound will only be heard by players that are within
`max_hear_distance` of the sound position, at the start of the sound.
`exclude_player = name` can be applied to locationless, positional and object-
bound sounds to exclude a single player from hearing them.
`SimpleSoundSpec`
-----------------
Specifies a sound name, gain (=volume) and pitch.
This is either a string or a table.
In string form, you just specify the sound name or
the empty string for no sound.
Table form has the following fields:
* `name`: Sound name
* `gain`: Volume (`1.0` = 100%)
* `pitch`: Pitch (`1.0` = 100%)
`gain` and `pitch` are optional and default to `1.0`.
Examples:
* `""`: No sound
* `{}`: No sound
* `"default_place_node"`: Play e.g. `default_place_node.ogg`
* `{name = "default_place_node"}`: Same as above
* `{name = "default_place_node", gain = 0.5}`: 50% volume
* `{name = "default_place_node", gain = 0.9, pitch = 1.1}`: 90% volume, 110% pitch
Special sound files
-------------------
These sound files are played back by the engine if provided.
* `player_damage`: Played when the local player takes damage (gain = 0.5)
* `player_falling_damage`: Played when the local player takes
damage by falling (gain = 0.5)
* `player_jump`: Played when the local player jumps
* `default_dig_`: Default node digging sound
(see node sound definition for details)
Registered definitions
======================
Anything added using certain [Registration functions]
getintfield(L, current_abm, "chance", trigger_chance);
bool simple_catch_up = true;
getboolfield(L, current_abm, "catch_up", simple_catch_up);
s16 min_y = INT16_MIN;
getintfield(L, current_abm, "min_y", min_y);
s16 max_y = INT16_MAX;
getintfield(L, current_abm, "max_y", max_y);
lua_getfield(L, current_abm, "action");
luaL_checktype(L, current_abm + 1, LUA_TFUNCTION);
lua_pop(L, 1);
LuaABM *abm = new LuaABM(L, id, trigger_contents, required_neighbors,
trigger_interval, trigger_chance, simple_catch_up, min_y, max_y);
env->addActiveBlockModifier(abm);
// removes value, keeps key for next iteration
lua_pop(L, 1);
}
lua_pop(L, 1);
// Get core.registered_lbms
lua_getglobal(L, "core");
lua_getfield(L, -1, "registered_lbms");
int registered_lbms = lua_gettop(L);
if (!lua_istable(L, registered_lbms)) {
lua_pop(L, 1);
throw LuaError("core.registered_lbms was not a lua table, as expected.");
}
lua_pushnil(L);
while (lua_next(L, registered_lbms)) {
// key at index -2 and value at index -1
int id = lua_tonumber(L, -2);
int current_lbm = lua_gettop(L);
std::set<std::string> trigger_contents;
lua_getfield(L, current_lbm, "nodenames");
if (lua_istable(L, -1)) {
int table = lua_gettop(L);
lua_pushnil(L);
while (lua_next(L, table)) {
// key at index -2 and value at index -1
luaL_checktype(L, -1, LUA_TSTRING);
trigger_contents.insert(readParam<std::string>(L, -1));
// removes value, keeps key for next iteration
lua_pop(L, 1);
}
} else if (lua_isstring(L, -1)) {
trigger_contents.insert(readParam<std::string>(L, -1));
}
lua_pop(L, 1);
std::string name;
getstringfield(L, current_lbm, "name", name);
bool run_at_every_load = getboolfield_default(L, current_lbm,
"run_at_every_load", false);
lua_getfield(L, current_lbm, "action");
luaL_checktype(L, current_lbm + 1, LUA_TFUNCTION);
lua_pop(L, 1);
LuaLBM *lbm = new LuaLBM(L, id, trigger_contents, name,
run_at_every_load);
env->addLoadingBlockModifierDef(lbm);
// removes value, keeps key for next iteration
lua_pop(L, 1);
}
lua_pop(L, 1);
}
void ScriptApiEnv::on_emerge_area_completion(
v3s16 blockpos, int action, ScriptCallbackState *state)
{
Server *server = getServer();
// This function should be executed with envlock held.
// The caller (LuaEmergeAreaCallback in src/script/lua_api/l_env.cpp)
// should have obtained the lock.
// Note that the order of these locks is important! Envlock must *ALWAYS*
// be acquired before attempting to acquire scriptlock, or else ServerThread
// will try to acquire scriptlock after it already owns envlock, thus
// deadlocking EmergeThread and ServerThread
SCRIPTAPI_PRECHECKHEADER
int error_handler = PUSH_ERROR_HANDLER(L);
lua_rawgeti(L, LUA_REGISTRYINDEX, state->callback_ref);
luaL_checktype(L, -1, LUA_TFUNCTION);
push_v3s16(L, blockpos);
lua_pushinteger(L, action);
lua_pushinteger(L, state->refcount);
lua_rawgeti(L, LUA_REGISTRYINDEX, state->args_ref);
setOriginDirect(state->origin.c_str());
try {
PCALL_RES(lua_pcall(L, 4, 0, error_handler));
} catch (LuaError &e) {
server->setAsyncFatalError(
std::string("on_emerge_area_completion: ") + e.what() + "\n"
+ script_get_backtrace(L));
}
lua_pop(L, 1); // Pop error handler
if (state->refcount == 0) {
luaL_unref(L, LUA_REGISTRYINDEX, state->callback_ref);
luaL_unref(L, LUA_REGISTRYINDEX, state->args_ref);
}
}
void ScriptApiEnv::on_liquid_transformed(
const std::vector<std::pair<v3s16, MapNode>> &list)
{
SCRIPTAPI_PRECHECKHEADER
// Get core.registered_on_liquid_transformed
lua_getglobal(L, "core");
lua_getfield(L, -1, "registered_on_liquid_transformed");
luaL_checktype(L, -1, LUA_TTABLE);
lua_remove(L, -2);
// Skip converting list and calling hook if there are
// no registered callbacks.
if(lua_objlen(L, -1) < 1) return;
// Convert the list to a pos array and a node array for lua
int index = 1;
const NodeDefManager *ndef = getEnv()->getGameDef()->ndef();
lua_createtable(L, list.size(), 0);
lua_createtable(L, list.size(), 0);
for(std::pair<v3s16, MapNode> p : list) {
lua_pushnumber(L, index);
push_v3s16(L, p.first);
lua_rawset(L, -4);
lua_pushnumber(L, index++);
pushnode(L, p.second, ndef);
lua_rawset(L, -3);
}
runCallbacks(2, RUN_CALLBACKS_MODE_FIRST);
}