Games
-----
Games are looked up from:
- * `$path_share/games/gameid/`
- * `$path_user/games/gameid/`
+
+* `$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 subgame 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.
+
+* `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 subgame 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
* `<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.
+`crack` draws it normally, while `cracko` lays it over, keeping transparent
+pixels intact.
Example:
default_stone.png^[transformFXR90
#### `[inventorycube{<top>{<left>{<right>`
-Escaping does not apply here and `^` is replaced by `&` in texture names instead.
+Escaping does not apply here and `^` is replaced by `&` in texture names
+instead.
Create an inventory cube texture using the side textures.
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.
+color. Meaning white surfaces get a lot of your new color while black parts
+don't change very much.
Hardware coloring
-----------------
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
a texture. You can also use texture modifiers.
The node's color depends on its `param2`, so you also must set an
appropriate `drawtype`:
+
* `drawtype = "color"` for nodes which use their full `param2` for
palette indexing. These nodes can have 256 different colors.
The palette should contain 256 pixels.
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", {
* `minetest.register_decoration(decoration definition)`
* returns an integer uniquely identifying the registered decoration
- * added to `minetest.registered_decorations` with the key of `decoration.name`
+ * 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
+ * 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
^ 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 other faces are defined by 'fixed = {}' like 'type = "fixed"'
+ nodeboxes.
The nodebox height is (param2 / 64) nodes.
The maximum accepted value of param2 is 127.
Rooted plantlike:
The height of the 'plantlike' section is stored in param2.
The height is (param2 / 16) nodes.
paramtype2 == "degrotate"
- ^ The rotation of this node is stored in param2. Plants are rotated this way.
+ ^ 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 of the node.
+ 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:
+ ^ 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
is picked from the palette.
The palette should have 32 pixels.
paramtype2 == "glasslikeliquidlevel"
- ^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes.
+ ^ 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"},`
* `mesh` -- Use models for nodes, see below
* `plantlike_rooted` -- See below
-`*_optional` drawtypes need less rendering time if deactivated (always client side).
+`*_optional` drawtypes need less rendering time if deactivated
+(always client side).
Node boxes
----------
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.
+ -- 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, ...}
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
+ disconnected_sides = box OR {box1, box2, ...} -- when there are *no*
+ neighbours to the sides
}
A `box` is defined as:
Factor that the noise is scaled by (i.e. multiplied) after calculation.
### `spread`
-Vector containing values by which each coordinate is divided by before calculation.
+Vector containing values by which each coordinate is divided by before
+calculation.
Higher spread values result in larger noise features.
A value of `{x=250, y=250, z=250}` is common.
### `seed`
-Random seed for the noise. Add the world seed to a seed offset for world-unique noise.
-In the case of `minetest.get_perlin()`, this value has the world seed automatically added.
+Random seed for the noise. Add the world seed to a seed offset for world-unique
+noise. In the case of `minetest.get_perlin()`, this value has the world seed
+automatically added.
### `octaves`
Number of times the noise gradient is accumulated into the noise.
A value of `6` is common.
### `persistence`
-Factor by which the effect of the noise gradient function changes with each successive octave.
+Factor by which the effect of the noise gradient function changes with each
+successive octave.
-Values less than `1` make the details of successive octaves' noise diminish, while values
-greater than `1` make successive octaves stronger.
+Values less than `1` make the details of successive octaves' noise diminish,
+while values greater than `1` make successive octaves stronger.
A value of `0.6` is common.
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.
+Specify this if you would like to keep auto-selection of eased/not-eased while
+specifying some other flags.
#### `eased`
-Maps noise gradient values onto a quintic S-curve before performing interpolation.
-This results in smooth, rolling noise. Disable this (`noeased`) for sharp-looking noise.
-If no flags are specified (or defaults is), 2D noise is eased and 3D noise is not eased.
+Maps noise gradient values onto a quintic S-curve before performing
+interpolation. This results in smooth, rolling noise.
+Disable this (`noeased`) for sharp-looking noise.
+If no flags are specified (or defaults is), 2D noise is eased and 3D noise is
+not eased.
#### `absvalue`
Accumulates the absolute value of each noise gradient result.
### `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.
+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
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`.
+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 `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.
+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.
+`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.
+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
+`noise_params`. The maximum size of the blob is `clust_size`, and
`clust_scarcity` has the same meaning as with the `scatter` type.
### `vein`
`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`.
+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.
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`
+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.
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.
+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
`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`.
+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`.
+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
----------------
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 `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)
+ * `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).
+* 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.
* `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.
+* `force_placement`: Schematic nodes other than "ignore" will replace existing
+ nodes.
HUD element types
* `sep_is_pattern`: boolean, it specifies whether separator is a plain
string or a pattern (regex), default: `false`
* e.g. `"a,b":split","` returns `{"a","b"}`
-* `string:trim()`: returns the string whithout whitespace pre- and suffixes
+* `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
### 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
* `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:
* `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`)
* decoration
* The second parameter is a list of IDS of decorations which notification
is requested for.
-* `get_gen_notify()`
+* `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)`
* If slice probability list equals `nil`, no slice probabilities are applied.
* Saves schematic in the Minetest Schematic format to filename.
-* `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement)`
+* `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement, flags)`
* Place the schematic specified by schematic (see: Schematic specifier) at `pos`.
* `rotation` can equal `"0"`, `"90"`, `"180"`, `"270"`, or `"random"`.
* If the `rotation` parameter is omitted, the schematic is not rotated.
will always use the cached version and the replacement list defined for it,
regardless of whether the file or the replacement list parameter have changed.
The only way to load the file anew is to restart the server.
+ * `flags` is a flag field with the available flags:
+ * place_center_x
+ * place_center_y
+ * place_center_z
-* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)`:
+* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement, flags)`:
* This function is analogous to minetest.place_schematic, but places a schematic onto the
specified VoxelManip object `vmanip` instead of the whole map.
* Returns false if any part of the schematic was cut-off due to the VoxelManip not
containing the full area required, and true if the whole schematic was able to fit.
* Returns nil if the schematic could not be loaded.
* After execution, any external copies of the VoxelManip contents are invalidated.
+ * `flags` is a flag field with the available flags:
+ * place_center_x
+ * place_center_y
+ * place_center_z
* `minetest.serialize_schematic(schematic, format, options)`
* Return the serialized schematic specified by schematic (see: Schematic specifier)
* `minetest.decode_base64(string)`: returns string
* Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
- * Returns true, if player `name` shouldn't be abled to dig at `pos` or do other
+ * Returns true, if player `name` shouldn't be able to dig at `pos` or do other
actions, definable by mods, due to some mod-defined ownership-like concept.
Returns false or nil, if the player is allowed to do such actions.
* `name` will be "" for non-players or unknown players.
* `minetest.record_protection_violation(pos, name)`
* This function calls functions registered with
`minetest.register_on_protection_violation`.
-* `minetest.intersects_protection(minp, maxp, player_name, interval)
- * Returns a boolean, returns true if the volume defined by `minp` and `maxp`
- intersects a protected area not owned by `player_name`.
+* `minetest.is_area_protected(pos1, pos2, player_name, interval)
+ * Returns the position of the first node that `player_name` may not modify in
+ the specified cuboid between `pos1` and `pos2`.
+ * Returns `false` if no protections were found.
* Applies `is_protected()` to a 3D lattice of points in the defined volume.
The points are spaced evenly throughout the volume and have a spacing
similar to, but no larger than, `interval`.
* `interval` defaults to 4.
* `interval` should be carefully chosen and maximised to avoid an excessive
number of points being checked.
+ * Like `minetest.is_protected`, this function may be extended or overwritten by
+ mods to provide a faster implementation to check the cuboid for intersections.
* `minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)`
* Attempt to predict the desired orientation of the facedir-capable node
defined by `itemstack`, and place it accordingly (on-wall, on the floor, or
### `gennotify`
Returns a table mapping requested generation notification types to arrays of
-positions at which the corresponding generated structures are located at within
+positions at which the corresponding generated structures are located within
the current chunk. To set the capture of positions of interest to be recorded
on generate, use `minetest.set_gen_notify()`.
+For decorations, the returned positions are the ground surface 'place_on' nodes,
+not the decorations themselves. A 'simple' type decoration is often 1 node above
+the returned position and possibly displaced by 'place_offset_y'.
Possible fields of the table returned are:
node_riverbed = "default:gravel",
depth_riverbed = 2,
-- ^ Node placed under river water and thickness of this layer.
- y_min = 1,
y_max = 31000,
- -- ^ Lower and upper limits for biome.
+ y_min = 1,
+ -- ^ Upper and lower limits for biome.
+ -- ^ Alternatively you can use xyz limits as shown below.
+ max_pos = {x = 31000, y = 128, z = 31000},
+ min_pos = {x = -31000, y = 9, z = -31000},
+ -- ^ xyz limits for biome, an alternative to using 'y_min' and 'y_max'.
+ -- ^ Biome is limited to a cuboid defined by these positions.
+ -- ^ Any x, y or z field left undefined defaults to -31000 in 'min_pos' or
+ -- ^ 31000 in 'max_pos'.
vertical_blend = 8,
-- ^ Vertical distance in nodes above 'y_max' over which the biome will
-- ^ blend with the biome above.
projects / minetest.git / blobdiff