diff --git a/lua_api.html b/lua_api.html index a804026..ef8ca8d 100644 --- a/lua_api.html +++ b/lua_api.html @@ -323,7 +323,8 @@ source code patches to http://www.minetest.net/
If you have any difficulty in understanding this, please read Programming in Lua.
+If you have any difficulty in understanding this, please read +Programming in Lua.
Mods are loaded during server startup from the mod load paths by running
the init.lua
scripts in a shared environment.
param2
.
Only static meshes are implemented.
For supported model formats see Irrlicht engine documentation.
Noise Parameters, or commonly called "NoiseParams
", define the properties of perlin noise.
Noise Parameters, or commonly called "NoiseParams
", define the properties of
+perlin noise.
offset
Offset that the noise is translated by (i.e. added) after calculation.
scale
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.
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
.
-The relative height of the sheet can be controlled by the same perlin noise as well, by specifying
-a non-zero scale
parameter in noise_params
.
IMPORTANT: The noise is not transformed by offset
or scale
when comparing against the noise
-threshold, but scale is used to determine relative height.
+
Creates a sheet of ore in a blob shape according to the 2D perlin noise
+described by noise_params
. The relative height of the sheet can be
+controlled by the same perlin noise as well, by specifying a non-zero
+scale
parameter in noise_params
.
IMPORTANT: The noise is not transformed by offset
or scale
when comparing
+against the noise threshold, but scale is used to determine relative height.
The height of the blob is randomly scattered, with a maximum height of clust_size
.
clust_scarcity
and clust_num_ores
are ignored.
This is essentially an improved version of the so-called "stratus" ore seen in some unofficial mods.
+This is essentially an improved version of the so-called "stratus" ore seen in +some unofficial mods.
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
@@ -931,49 +935,60 @@ computationally expensive than any other ore.
The varying types of decorations that can be placed.
The default value is simple
, and is currently the only type supported.
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,
-and so on.
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, 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.
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.
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 must specify two fields:
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 must specify two fields:
size
field is a 3D vector containing the dimensions of the provided schematic.data
field is a flat table of MapNodes making up the schematic, in the order of [z [y [x]]]
.data
field is a flat table of MapNodes making up the schematic,
+ in the order of [z [y [x]]]
.Important: The default value for param1
in MapNodes here is 255
, which represents "always place".
In the bulk MapNode
data, param1
, instead of the typical light values, instead represents the
-probability of that node appearing in the structure.
When passed to minetest.create_schematic
, probability is an integer value ranging from 0
to 255
:
Important: The default value for param1
in MapNodes here is 255
,
+which represents "always place".
In the bulk MapNode
data, param1
, instead of the typical light values,
+instead represents the probability of that node appearing in the structure.
When passed to minetest.create_schematic
, probability is an integer value
+ranging from 0
to 255
:
0
means that node will never appear (0% chance).255
means the node will always appear (100% chance).p
is greater than 0
, then there is a (p / 256 * 100)
% chance that node
- will appear when the schematic is placed on the map.p
is greater than 0
, then there is a
+ (p / 256 * 100)
% chance that node will appear when the schematic is
+ placed on the map.Important note: Node aliases cannot be used for a raw schematic provided when registering as a decoration.
+Important note: Node aliases cannot be used for a raw schematic provided + when registering as a decoration.
See section "Flag Specifier Format".
-Currently supported flags: place_center_x
, place_center_y
, place_center_z
.
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.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.
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.
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.
+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.
{type="object", ref=ObjectRef}
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
+
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.
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}
@@ -1177,8 +1196,8 @@ effective towards.
dropped as an item. If the node is wallmounted the wallmounted direction is
checked.
soil
: saplings will grow on nodes in this groupconnect_to_raillike
: makes nodes of raillike drawtype connect to
- other group members with same drawtypeconnect_to_raillike
: makes nodes of raillike drawtype with same group value
+ connect to each otherDamage 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)
+ 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
@@ -1323,8 +1343,8 @@ a non-tool item, so that it can do something else than take damage.
On the Lua side, every punch calls:
entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction)
-This should never be called directly, because damage is usually not handled by the entity
-itself.
+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.
@@ -1364,12 +1384,14 @@ 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] = ""}
+ 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;]",
@@ -2166,6 +2188,11 @@ and minetest.auth_reload
call the authetification handler.
nodenames
: e.g. {"ignore", "group:tree"}
or "default:dirt"
+minetest.find_nodes_in_area_under_air(minp, maxp, nodenames)
: returns a list of positions
+- returned positions are nodes with a node air above
+nodenames
: e.g. {"ignore", "group:tree"}
or "default:dirt"
+
+
minetest.get_perlin(noiseparams)
minetest.get_perlin(seeddiff, octaves, persistence, scale)
- Return world-specific perlin noise (
int(worldseed)+seeddiff
)
@@ -2191,8 +2218,10 @@ and minetest.auth_reload
call the authetification handler.
mgname
, seed
, chunksize
, water_level
, and flags
.
minetest.set_mapgen_params(MapgenParams)
- Set map generation parameters
-- Function cannot be called after the registration period; only initialization and
on_mapgen_init
-- Takes a table as an argument with the fields
mgname
, seed
, water_level
, and flags
.
+- Function cannot be called after the registration period; only initialization
+ and
on_mapgen_init
+- Takes a table as an argument with the fields
mgname
, seed
, water_level
,
+ and flags
.
- Leave field unset to leave that parameter unchanged
flags
contains a comma-delimited string of flags to set,
or if the prefix "no"
is attached, clears instead.
@@ -2207,10 +2236,10 @@ and minetest.auth_reload
call the authetification handler.
should be applied to the default config or current active config
-minetest.generate_ores(vm)
-- Generate all registered ores within the VoxelManip specified by
vm
.
-minetest.generate_decorations(vm)
-- Generate all registered decorations within the VoxelManip specified by
vm
.
+minetest.generate_ores(vm, p1, p2)
+- Generate all registered ores within the VoxelManip
vm
and in the area from p1 to p2.
+minetest.generate_decorations(vm, p1, p2)
+- Generate all registered decorations within the VoxelManip
vm
and in the area from p1 to p2.
minetest.clear_objects()
- clear all objects in the environments
@@ -2281,7 +2310,8 @@ and minetest.auth_reload
call the authetification handler.
- Creates a detached inventory. If it already exists, it is cleared.
-minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)
: returns left over ItemStack
+minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)
:
+ returns left over ItemStack
- See
minetest.item_eat
and minetest.register_on_item_eat
@@ -2537,12 +2567,15 @@ and minetest.auth_reload
call the authetification handler.
- Create a schematic from the volume of map specified by the box formed by p1 and p2.
- Apply the specified probability values to the specified nodes in
probability_list
.
probability_list
is an array of tables containing two fields, pos
and prob
.
-pos
is the 3D vector specifying the absolute coordinates of the node being modified,
+pos
is the 3D vector specifying the absolute coordinates of the
+ node being modified,
prob
is the integer value from 0
to 255
of the probability (see: Schematic specifier).
-- If there are two or more entries with the same pos value, the last entry is used.
+- If there are two or more entries with the same pos value, the
+ last entry is used.
- If
pos
is not inside the box formed by p1
and p2
, it is ignored.
- If
probability_list
equals nil
, no probabilities are applied.
-- Slice probability works in the same manner, except takes a field called
ypos
instead which
+ - Slice probability works in the same manner, except takes a field
+ called
ypos
instead which
indicates the y position of the slice with a probability applied.
- If slice probability list equals
nil
, no slice probabilities are applied.
@@ -2817,7 +2850,10 @@ Can be gotten via minetest.get_node_timer(pos)
.
This is basically a reference to a C++ ServerActiveObject
Methods
-remove()
: remove object (after returning from Lua)
+remove()
: remove object (after returning from Lua)
+- Note: Doesn't work on players, use minetest.kick_player instead
+
+
getpos()
: returns {x=num, y=num, z=num}
setpos(pos)
; pos
={x=num, y=num, z=num}
moveto(pos, continuous=false)
: interpolated move
@@ -2914,7 +2950,8 @@ Can be gotten via minetest.get_node_timer(pos)
.
-hud_add(hud definition)
: add a HUD element described by HUD def, returns ID number on success
+hud_add(hud definition)
: add a HUD element described by HUD def, returns ID
+ number on success
hud_remove(id)
: remove the HUD element of the specified id
hud_change(id, stat, value)
: change a value of a previously added HUD element
- element
stat
values: position
, name
, scale
, text
, number
, item
, dir
@@ -2966,16 +3003,19 @@ Can be gotten via minetest.get_node_timer(pos)
.
nil
: Disables override, defaulting to sunlight based on day-night cycle
-set_local_animation({x=0, y=79}, {x=168, y=187}, {x=189, y=198}, {x=200, y=219}, frame_speed=30)
:
- set animation for player model in third person view
-- stand/idle animation key frames
-- walk animation key frames
-- dig animation key frames
-- walk+dig animation key frames
-- animation frame speed
-
+-
+
set_local_animation(walk, dig, walk+dig, frame_speed=frame_speed)
+set animation for player model in third person view
+set_local_animation({x=0, y=79}, -- < stand/idle animation key frames
+ {x=168, y=187}, -- < walk animation key frames
+ {x=189, y=198}, -- < dig animation key frames
+ {x=200, y=219}, -- < walk+dig animation key frames
+ frame_speed=30): -- < animation frame speed
+
-set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})
: defines offset value for camera per player
+-
+
set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})
: defines offset value for camera per player
+
- in first person view
- in third person view (max. values
{x=-10/10,y=-10,15,z=-5/5}
)
@@ -3100,7 +3140,8 @@ for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
The map will be pre-loaded if two positions are passed to either.
Methods
-read_from_map(p1, p2)
: Reads a chunk of map from the map containing the region formed by p1
and p2
.
+read_from_map(p1, p2)
: Reads a chunk of map from the map containing the
+ region formed by p1
and p2
.
- returns actual emerged
pmin
, actual emerged pmax
@@ -3108,22 +3149,25 @@ The map will be pre-loaded if two positions are passed to either.
- important: data must be set using
VoxelManip:set_data
before calling this
-get_node_at(pos)
: Returns a MapNode
table of the node currently loaded in the VoxelManip
at that position
-set_node_at(pos, node)
: Sets a specific MapNode
in the VoxelManip
at that position
+get_node_at(pos)
: Returns a MapNode
table of the node currently loaded in
+ the VoxelManip
at that position
+set_node_at(pos, node)
: Sets a specific MapNode
in the VoxelManip
at
+ that position
get_data()
: Gets the data read into the VoxelManip
object
- returns raw node data is in the form of an array of node content IDs
set_data(data)
: Sets the data contents of the VoxelManip
object
update_map()
: Update map after writing chunk back to map.
-- To be used only by
VoxelManip
objects created by the mod itself; not a VoxelManip
that was
- retrieved from minetest.get_mapgen_object
+- To be used only by
VoxelManip
objects created by the mod itself;
+ not a VoxelManip
that was retrieved from minetest.get_mapgen_object
set_lighting(light, p1, p2)
: Set the lighting within the VoxelManip
to a uniform value
light
is a table, {day=<0...15>, night=<0...15>}
- To be used only by a
VoxelManip
object from minetest.get_mapgen_object
-- (
p1
, p2
) is the area in which lighting is set; defaults to the whole area if left out
+- (
p1
, p2
) is the area in which lighting is set;
+ defaults to the whole area if left out
get_light_data()
: Gets the light data read into the VoxelManip
object
@@ -3132,7 +3176,8 @@ The map will be pre-loaded if two positions are passed to either.
light = day + (night * 16)
-set_light_data(light_data)
: Sets the param1
(light) contents of each node in the VoxelManip
+set_light_data(light_data)
: Sets the param1
(light) contents of each node
+ in the VoxelManip
- expects lighting data in the same format that
get_light_data()
returns
@@ -3140,12 +3185,14 @@ The map will be pre-loaded if two positions are passed to either.
set_param2_data(param2_data)
: Sets the param2
contents of each node in the VoxelManip
calc_lighting(p1, p2)
: Calculate lighting within the VoxelManip
- To be used only by a
VoxelManip
object from minetest.get_mapgen_object
-- (
p1
, p2
) is the area in which lighting is set; defaults to the whole area if left out
+- (
p1
, p2
) is the area in which lighting is set; defaults to the whole area
+ if left out
update_liquids()
: Update liquid flow
-was_modified()
: Returns true
or false
if the data in the voxel manipulator had been modified since
- the last read from map, due to a call to minetest.set_data()
on the loaded area elsewhere
+was_modified()
: Returns true
or false
if the data in the voxel manipulator
+ had been modified since the last read from map, due to a call to
+ minetest.set_data()
on the loaded area elsewhere
get_emerged_area()
: Returns actual emerged minimum and maximum positions.
VoxelArea
@@ -3154,10 +3201,12 @@ It can be created via VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}
.
The coordinates are inclusive, like most other things in Minetest.
Methods
-getExtent()
: returns a 3D vector containing the size of the area formed by MinEdge
and MaxEdge
+getExtent()
: returns a 3D vector containing the size of the area formed by
+ MinEdge
and MaxEdge
getVolume()
: returns the volume of the area formed by MinEdge
and MaxEdge
index(x, y, z)
: returns the index of an absolute position in a flat array starting at 1
-- useful for things like
VoxelManip
, raw Schematic specifiers, PerlinNoiseMap:get2d
/3dMap
, and so on
+- useful for things like
VoxelManip
, raw Schematic specifiers,
+ PerlinNoiseMap:get2d
/3dMap
, and so on
indexp(p)
: same as above, except takes a vector
@@ -3188,30 +3237,32 @@ The coordinates are inclusive, like most other things in Minetest.
to_table()
: returns {[key1]=value1,...}
Mapgen objects
-A mapgen object is a construct used in map generation. Mapgen objects can be used by an on_generate
-callback to speed up operations by avoiding unnecessary recalculations; these can be retrieved using the
-minetest.get_mapgen_object()
function. If the requested Mapgen object is unavailable, or
-get_mapgen_object()
was called outside of an on_generate()
callback, nil
is returned.
+A mapgen object is a construct used in map generation. Mapgen objects can be used
+by an on_generate
callback to speed up operations by avoiding unnecessary
+recalculations; these can be retrieved using the minetest.get_mapgen_object()
+function. If the requested Mapgen object is unavailable, or get_mapgen_object()
+was called outside of an on_generate()
callback, nil
is returned.
The following Mapgen objects are currently available:
voxelmanip
-This returns three values; the VoxelManip
object to be used, minimum and maximum emerged position, in that
-order. All mapgens support this object.
+This returns three values; the VoxelManip
object to be used, minimum and maximum
+emerged position, in that order. All mapgens support this object.
heightmap
-Returns an array containing the y coordinates of the ground levels of nodes in the most recently
-generated chunk by the current mapgen.
+Returns an array containing the y coordinates of the ground levels of nodes in
+the most recently generated chunk by the current mapgen.
biomemap
-Returns an array containing the biome IDs of nodes in the most recently generated chunk by the
-current mapgen.
+Returns an array containing the biome IDs of nodes in the most recently
+generated chunk by the current mapgen.
heatmap
-Returns an array containing the temperature values of nodes in the most recently generated chunk by
-the current mapgen.
+Returns an array containing the temperature values of nodes in the most
+recently generated chunk by the current mapgen.
humiditymap
-Returns an array containing the humidity values of nodes in the most recently generated chunk by the
-current mapgen.
+Returns an array containing the humidity values of nodes in the most recently
+generated chunk by the current mapgen.
gennotify
-Returns a table mapping requested generation notification types to arrays of positions at which the
-corresponding generated structures are located at within the current chunk. To set the capture of positions
-of interest to be recorded on generate, use minetest.set_gen_notify()
.
+Returns a table mapping requested generation notification types to arrays of
+positions at which the corresponding generated structures are located at within
+the current chunk. To set the capture of positions of interest to be recorded
+on generate, use minetest.set_gen_notify()
.
Possible fields of the table returned are:
dungeon
@@ -3222,7 +3273,8 @@ of interest to be recorded on generate, use minetest.set_gen_notify()large_cave_end
decoration
-Decorations have a key in the format of "decoration#id"
, where id
is the numeric unique decoration ID.
+Decorations have a key in the format of "decoration#id"
, where id
is the
+numeric unique decoration ID.
Registered entities
- Functions receive a "luaentity" as
self
:
@@ -3277,7 +3329,8 @@ of interest to be recorded on generate, use minetest.set_gen_notify()