** WARNING: The client API is currently unstable, and may break/change without warning. **
Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua scripting in run-time loaded mods.
A mod is a self-contained bunch of scripts, textures and other related things that is loaded by and interfaces with Minetest.
Transferring client-sided mods from the server to the client is planned, but not implemented yet.
If you see a deficiency in the API, feel free to attempt to add the functionality in the engine and API. You can send such improvements as source code patches on GitHub (https://github.com/minetest/minetest).
If you have any difficulty in understanding this, please read Programming in Lua.
Mods are loaded during client startup from the mod load paths by running
the init.lua
scripts in a shared environment.
In order to load client-side mods, the following conditions need to be satisfied:
1) $path_user/minetest.conf
contains the setting enable_client_modding = true
2) The client-side mod located in $path_user/clientmods/<modname>
is added to
`$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.
Note: Depending on the remote server's settings, client-side mods might not
be loaded or have limited functionality. See setting csm_restriction_flags
for reference.
RUN_IN_PLACE=1
(Windows release, local build)
$path_user
: <build directory>
$path_share
: <build directory>
RUN_IN_PLACE=0
: (Linux release)
$path_share
:
/usr/share/minetest
<install directory>/minetest-0.4.x
$path_user
:
$HOME/.minetest
C:/users/<user>/AppData/minetest
(maybe)Generic:
$path_share/clientmods/
$path_user/clientmods/
(User-installed mods)In a run-in-place version (e.g. the distributed windows version):
minetest-0.4.x/clientmods/
(User-installed mods)On an installed version on Linux:
/usr/share/minetest/clientmods/
$HOME/.minetest/clientmods/
(User-installed mods)Mods can be put in a subdirectory, if the parent directory, which otherwise
should be a mod, contains a file named modpack.conf
.
The file is a key-value store of modpack details.
name
: The modpack name.description
: Description of mod to be shown in the Mods tab of the main
menu.clientmods
├── modname
│ ├── mod.conf
│ ├── init.lua
└── another
The location of this directory.
An (optional) settings file that provides meta information about the mod.
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 main
menu.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.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.
NOTE: Client mods currently can't provide textures, sounds, or models by themselves. Any media referenced in function calls must already be loaded (provided by mods that exist on the server).
Registered names should generally be in this format:
"modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
This is to prevent conflicting names from corrupting maps and is enforced by the mod loader.
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.
NOTE: Connecting sounds to objects is not implemented.
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
{
gain = 1.0, -- default
}
-- Play locationless, looped
{
gain = 1.0, -- default
loop = true,
}
-- Play in a location
{
pos = {x = 1, y = 2, z = 3},
gain = 1.0, -- default
}
-- Play connected to an object, looped
{
object = <an ObjectRef>,
gain = 1.0, -- default
loop = true,
}
Looped sounds must either be connected to an object or played locationless.
""
"default_place_node"
{}
{name = "default_place_node"}
{name = "default_place_node", gain = 1.0}
{x=num, y=num, z=num}
For helper functions see "Vector helpers".
{type="nothing"}
{type="node", under=pos, above=pos}
{type="object", id=ObjectID}
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.
Formspec defines a menu. It is a string, with a somewhat strange format.
Spaces and newlines can be inserted between the blocks, as is used in the examples.
size[8,9]
list[context;main;0,0;8,4;]
list[current_player;main;0,5;8,4;]
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;]
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;]
size[<W>,<H>,<fixed_size>]
fixed_size
: true
/false
(optional)invsize[<W>,<H>;]
container[<X>,<Y>]
container_end[]
list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]
list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]
listring[<inventory location>;<list name>]
listring[]
listring[<inventory location>;<list name>]
for the last two inventory lists added by list[...]listcolors[<slot_bg_normal>;<slot_bg_hover>]
ColorString
listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]
ColorString
listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]
ColorString
tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]
<bgcolor>
tooltip background color as ColorString
(optional)<fontcolor>
tooltip font color as ColorString
(optional)image[<X>,<Y>;<W>,<H>;<texture name>]
item_image[<X>,<Y>;<W>,<H>;<item name>]
bgcolor[<color>;<fullscreen>]
ColorString
true
, the background color is drawn fullscreen (does not affect the size of the formspec)background[<X>,<Y>;<W>,<H>;<texture name>]
background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]
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>]
x
and y
position the field relative to the top left of the menuw
and h
are the size of the fieldh
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 fieldfield[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
x
and y
position the field relative to the top left of the menuw
and h
are the size of the fieldh
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 fielddefault
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
field[<name>;<label>;<default>]
size[]
elementfield_close_on_enter[<name>;<close_on_enter>]
textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
label[<X>,<Y>;<label>]
x
and y
work as per fieldlabel
is the text on the labelvertlabel[<X>,<Y>;<label>]
x
and y
work as per fieldlabel
is the text on the labelbutton[<X>,<Y>;<W>,<H>;<name>;<label>]
x
, y
and name
work as per fieldw
and h
are the size of the buttonh
label
is the text on the buttonimage_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
x
, y
, w
, h
, and name
work as per buttontexture name
is the filename of an imageimage_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]
x
, y
, w
, h
, and name
work as per buttontexture name
is the filename of an imagenoclip=true
means the image button doesn't need to be within specified formsizedrawborder
: draw button border or notpressed texture name
is the filename of an image on pressed stateitem_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]
x
, y
, w
, h
, name
and label
work as per buttonitem name
is the registered name of an item/node,
tooltip will be made out of its description
to override it use tooltip elementbutton_exit[<X>,<Y>;<W>,<H>;<name>;<label>]
image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]
x
and y
position the itemlist relative to the top left of the menuw
and h
are the size of the itemlistname
fieldname sent to server on doubleclick value is current selected elementlistelements
can be prepended by #color in hexadecimal format RRGGBB (only),
textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]
x
and y
position the item list relative to the top left of the menuw
and h
are the size of the item listname
fieldname sent to server on doubleclick value is current selected elementlistelements
can be prepended by #RRGGBB (only) in hexadecimal format
true
/false
: draw transparent backgroundminetest.explode_textlist_event
(main menu: engine.explode_textlist_event
)tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]
x
and y
position the itemlist relative to the top left of the menuname
fieldname data is transferred to Luacaption 1
...: name shown on top of tabcurrent_tab
: index of selected tab 1...transparent
(optional): show transparentdraw_border
(optional): draw borderbox[<X>,<Y>;<W>,<H>;<color>]
x
and y
position the box relative to the top left of the menuw
and h
are the size of boxcolor
is color specified as a ColorString
dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]
x
and y
position of dropdowncheckbox[<X>,<Y>;<name>;<label>;<selected>]
x
and y
: position of checkboxname
fieldname data is transferred to Lualabel
to be shown left of checkboxselected
(optional): true
/false
scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]
x
and y
: position of trackbarw
and h
: width and heightorientation
: vertical
/horizontal
0
-1000
)minetest.explode_scrollbar_event
(main menu: engine.explode_scrollbar_event
)table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]
tableoptions[]
tablecolumns[]
x
and y
: position the itemlist relative to the top left of the menuw
and h
are the size of the itemlistname
: fieldname sent to server on row select or doubleclickcell 1
...cell n
: cell contents given in row-major orderselected idx
: index of row to be selected within table (first row = 1
)minetest.explode_table_event
(main menu: engine.explode_table_event
)tableoptions[<opt 1>;<opt 2>;...]
table[]
color=#RRGGBB
ColorString
), defaults to #FFFFFF
background=#RRGGBB
ColorString
), defaults to #000000
border=<true/false>
true
)highlight=#RRGGBB
ColorString
), defaults to #466432
highlight_text=#RRGGBB
ColorString
), defaults to #FFFFFF
opendepth=<value>
depth < value
are open (default value = 0
)tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]
table[]
text
, image
, color
, indent
, tree
text
: show cell contents as textimage
: cell contents are an image index, use column options to define imagescolor
: cell contents are a ColorString and define color of following cellindent
: cell contents are a number and define indentation of following celltree
: same as indent, but user can open and close subtrees (treeview-like)align=<value>
text
and image
: content alignment within cells.
Available values: left
(default), center
, right
, inline
width=<value>
text
and image
: minimum width in em (default: 0
)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 columnstooltip=<value>
: tooltip text (default: empty)image
column options:
0=<value>
sets image for image index 01=<value>
sets image for image index 12=<value>
sets image for image index 20
.color
column options:
span=<value>
: number of following columns to affect (default: infinite)Note: do not use an element name starting with key_
; those names are reserved to
pass key press events to formspec!
vector.new(a[, b, c])
: returns a vector:
a
if a
is a vector.{x = a, y = b, z = c}
, if all a, b, c
are definedvector.direction(p1, p2)
: returns a vectorvector.distance(p1, p2)
: returns a numbervector.length(v)
: returns a numbervector.normalize(v)
: returns a vectorvector.floor(v)
: returns a vector, each dimension rounded downvector.round(v)
: returns a vector, each dimension rounded to nearest intvector.apply(v, func)
: returns a vectorvector.combine(v, w, func)
: returns a vectorvector.equals(v1, v2)
: returns a booleanFor the following functions x
can be either a vector or a number:
vector.add(v, x)
: returns a vectorvector.subtract(v, x)
: returns a vectorvector.multiply(v, x)
: returns a scaled vector or Schur productvector.divide(v, x)
: returns a scaled vector or Schur quotientdump2(obj, name="_", dumped={})
dump(obj, dumped={})
math.hypot(x, y)
math.sign(x, tolerance)
0
when the absolute value is within the tolerance (default: 0
)string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)
max_splits
is negative, do not limit splits.sep_is_pattern
specifies if separator is a plain string or a pattern (regex).string:split("a,b", ",") == {"a","b"}
string:trim()
string.trim("\n \t\tfoo bar\t ") == "foo bar"
minetest.wrap_text(str, limit)
: returns a string
minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))
: returns string "(X,Y,Z)"
minetest.string_to_pos(string)
: returns a position
nil
if the string can't be parsed to a position.minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")
: returns two positions
minetest.is_yes(arg)
arg
can be interpreted as yesminetest.is_nan(arg)
table.copy(table)
: returns a table
table
minetest.get_current_modname()
: returns the currently loading mod's name, when we are loading a modminetest.get_modpath(modname)
: returns virtual path of given mod including
the trailing separator. This is useful to load additional Lua files
contained in your mod:
e.g. dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")
minetest.get_language()
: returns two strings
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 hashraw
: return raw bytes instead of hex digits, default: falseminetest.colorspec_to_colorstring(colorspec)
: Converts a ColorSpec to a
ColorString. If the ColorSpec is invalid, returns nil
.
colorspec
: The ColorSpec to convertminetest.get_csm_restrictions()
: returns a table of Flags
indicating the
restrictions applied to the current mod.
load_client_mods
, chat_messages
, read_itemdefs
,
read_nodedefs
, lookup_nodes
, read_playerinfo
minetest.urlencode(str)
: Encodes non-unreserved URI characters by a
percent sign followed by two hex digits. See
RFC 3986, section 2.3.minetest.debug(...)
minetest.log(table.concat({...}, "\t"))
minetest.log([level,] text)
level
is one of "none"
, "error"
, "warning"
, "action"
,
"info"
, or "verbose"
. Default is "none"
.Call these functions only at load time!
minetest.register_globalstep(function(dtime))
minetest.register_on_mods_loaded(function())
minetest.register_on_shutdown(function())
minetest.register_on_receiving_chat_message(function(message))
true
to mark the message as handled, which means that it will not be shown to chatminetest.register_on_sending_chat_message(function(message))
true
to mark the message as handled, which means that it will not be sent to serverminetest.register_chatcommand(cmd, chatcommand definition)
minetest.unregister_chatcommand(name)
minetest.register_on_chatcommand(function(command, params))
minetest.registered_chatcommands
is checked to see if the command exists, but after the input is parsed.true
to mark the command as handled, which means that the default
handlers will be prevented.minetest.register_on_death(function())
minetest.register_on_hp_modification(function(hp))
minetest.register_on_damage_taken(function(hp))
minetest.register_on_formspec_input(function(formname, fields))
true
, remaining functions are not calledminetest.register_on_dignode(function(pos, node))
minetest.register_on_punchnode(function(pos, node))
minetest.register_on_placenode(function(pointed_thing, node))
minetest.register_on_item_use(function(item, pointed_thing))
minetest.register_on_modchannel_message(function(channel_name, sender, message))
sender
field is an empty string.minetest.register_on_modchannel_signal(function(channel_name, signal))
minetest.register_on_inventory_open(function(inventory))
If any function returns true, inventory doesn't open
minetest.sound_play(spec, parameters)
: returns a handle
spec
is a SimpleSoundSpec
parameters
is a sound parameter tablehandle:stop()
or minetest.sound_stop(handle)
handle
is a handle returned by minetest.sound_play
handle:fade(step, gain)
or minetest.sound_fade(handle, step, gain)
handle
is a handle returned by minetest.sound_play
step
determines how fast a sound will fade.
Negative step will lower the sound volume, positive step will increase
the sound volume.gain
the target gain for the fade.minetest.after(time, func, ...)
func
after time
seconds, may be fractionalfunc
minetest.get_us_time()
minetest.get_timeofday()
0
for midnight, 0.5
for middayminetest.get_node_or_nil(pos)
{name="node_name", param1=0, param2=0}
, returns nil
for unloaded areas or flavor limited areas.minetest.get_node_light(pos, timeofday)
pos
: The position where to measure the light.timeofday
: nil
for current time, 0
for night, 0.5
for day0
and 15
or nil
minetest.find_node_near(pos, radius, nodenames, [search_center])
: returns pos or nil
radius
: using a maximum metricnodenames
: e.g. {"ignore", "group:tree"}
or "default:dirt"
search_center
is an optional boolean (default: false
)
If true pos
is also checked for the nodesminetest.find_nodes_in_area(pos1, pos2, nodenames, [grouped])
pos1
and pos2
are the min and max positions of the area to search.nodenames
: e.g. {"ignore", "group:tree"}
or "default:dirt"
grouped
is true the return value is a table indexed by node name
which contains lists of positions.grouped
is false or absent the return values are as follows:
first value: Table with all node positions
second value: Table with the count of each node with the node name
as indexminetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)
: returns a
list of positions.
nodenames
: e.g. {"ignore", "group:tree"}
or "default:dirt"
minetest.line_of_sight(pos1, pos2)
: returns boolean, pos
false
pos1
: First positionpos2
: Second positionminetest.raycast(pos1, pos2, objects, liquids)
: returns Raycast
Raycast
object.pos1
: start of the raypos2
: end of the rayobjects
: if false, only nodes will be returned. Default is true
.liquids
: if false, liquid nodes won't be returned. Default is false
.minetest.find_nodes_with_meta(pos1, pos2)
minetest.get_meta(pos)
NodeMetaRef
at that positionminetest.get_node_level(pos)
minetest.get_node_max_level(pos)
minetest.send_chat_message(message)
message
was typed by the player into the terminal.minetest.run_server_chatcommand(cmd, param)
minetest.send_chat_message("/" .. cmd .. " " .. param)
minetest.clear_out_chat_queue()
minetest.localplayer
LocalPlayer
class reference for methods.minetest.get_privilege_list()
{priv1=true,...}
minetest.string_to_privs(str)
: returns {priv1=true,...}
minetest.privs_to_string(privs)
: returns "priv1,priv2,..."
minetest.get_player_names()
minetest.disconnect()
false
if the client is already disconnecting otherwise returns true
.minetest.get_server_info()
minetest.send_respawn()
minetest.get_mod_storage()
:
StorageRef
minetest.mod_channel_join(channel_name)
channel_name
, and creates it, if necessary. You
should listen from incoming messages with minetest.register_on_modchannel_message
call to receive incoming messages. Warning, this function is asynchronous.minetest.add_particle(particle definition)
minetest.add_particlespawner(particlespawner definition)
ParticleSpawner
, an object that spawns an amount of particles over time
secondsid
, and -1 if adding didn't succeedminetest.delete_particlespawner(id)
ParticleSpawner
with id
(return value from minetest.add_particlespawner
)minetest.parse_json(string[, nullvalue])
: returns something
nullvalue
: returned in place of the JSON null; defaults to nil
nullvalue
nil
parse_json("[10, {\"a\":false}]")
, returns {10, {a = false}}
minetest.write_json(data[, styled])
: returns a string or nil
and an error message
write_json({10, {a = false}})
, returns "[10, {\"a\": false}]"
minetest.serialize(table)
: returns a string
nil
s
into string form readable by minetest.deserialize
serialize({foo='bar'})
, returns 'return { ["foo"] = "bar" }'
minetest.deserialize(string)
: returns a table
minetest.deserialize
into a tablestring
is loaded in an empty sandbox environment.deserialize('return { ["foo"] = "bar" }')
, returns {foo='bar'}
deserialize('print("foo")')
, returns nil
(function call fails)
error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)
minetest.compress(data, method, ...)
: returns compressed_data
method
is a string identifying the compression method to be used."deflate"
"zstd"
...
indicates method-specific arguments. Currently defined arguments
are:
level
- Compression level, 0
-9
or nil
.level
- Compression level. Integer or nil
. Default 3
.
Note any supported Zstandard compression level could be used here,
but these are subject to change between Zstandard versions.minetest.decompress(compressed_data, method, ...)
: returns data
method
.minetest.compress()
for supported compression
methods....
indicates method-specific arguments. Currently, no methods use thisminetest.rgba(red, green, blue[, alpha])
: returns a string
minetest.rgba(10, 20, 30, 40)
, returns "#0A141E28"
minetest.encode_base64(string)
: returns string encoded in base64
minetest.decode_base64(string)
: returns string or nil on failure
minetest.gettext(string)
: returns string
fgettext_ne(string, ...)
fgettext(string, ...)
: returns string
minetest.pointed_thing_to_face_pos(placer, pointed_thing)
: returns a position
minetest.global_exists(name)
minetest.ui.minimap
Minimap
class reference for methods.minetest.camera
Camera
class reference for methods.minetest.show_formspec(formname, formspec)
: returns true on success
minetest.display_chat_message(message)
returns true on success
minetest.settings
: Settings object containing all of the settings from the
main config file (minetest.conf
). Check lua_api.md for class reference.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.An interface to use mod channels on client and server
leave()
: leave the mod channel.
channel_name
.is_writeable()
: returns true if channel is writable and mod can send over it.send_all(message)
: Send message
though the mod channel.
An interface to manipulate minimap on client UI
show()
: shows the minimap (if not disabled by server)hide()
: hides the minimapset_pos(pos)
: sets the minimap position on screenget_pos()
: returns the minimap current positionset_angle(deg)
: sets the minimap angle in degreesget_angle()
: returns the current minimap angle in degreesset_mode(mode)
: sets the minimap mode (0 to 6)get_mode()
: returns the current minimap modeset_shape(shape)
: Sets the minimap shape. (0 = square, 1 = round)get_shape()
: Gets the minimap shape. (0 = square, 1 = round)An interface to get or set information about the camera and camera-node. Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
set_camera_mode(mode)
0
for first-person, 1
for third person, and 2
for third person frontget_camera_mode()
get_fov()
Returns a table with X, Y, maximum and actual FOV in degrees:
{
x = number,
y = number,
max = number,
actual = number
}
get_pos()
get_offset()
get_look_dir()
get_look_vertical()
get_look_horizontal()
get_aspect_ratio()
An interface to retrieve information about the player.
This object will only be available after the client is initialized. Earlier accesses will yield a nil
value.
Methods:
get_pos()
get_velocity()
get_hp()
get_name()
get_wield_index()
get_wielded_item()
is_attached()
is_touching_ground()
is_in_liquid()
is_in_liquid_stable()
get_move_resistance()
is_climbing()
swimming_vertical()
get_physics_override()
returns:
{
speed = float,
jump = float,
gravity = float,
sneak = boolean,
sneak_glitch = boolean,
new_move = boolean,
}
get_override_pos()
get_last_pos()
get_last_velocity()
get_breath()
get_movement_acceleration()
returns acceleration of the player in different environments:
{
fast = float,
air = float,
default = float,
}
get_movement_speed()
returns player's speed in different environments:
{
walk = float,
jump = float,
crouch = float,
fast = float,
climb = float,
}
get_movement()
returns player's movement in different environments:
{
liquid_fluidity = float,
liquid_sink = float,
liquid_fluidity_smooth = float,
gravity = float,
}
get_last_look_horizontal()
:
get_last_look_vertical()
:
get_control()
:
returns pressed player controls
{
up = boolean,
down = boolean,
left = boolean,
right = boolean,
jump = boolean,
aux1 = boolean,
sneak = boolean,
zoom = boolean,
dig = boolean,
place = boolean,
}
get_armor_groups()
hud_add(definition)
nil
on failure.HUD definition
hud_get(id)
definition
of the HUD with that ID number or nil
, if non-existent.hud_remove(id)
true
on successhud_change(id, stat, value)
stat
values: position
, name
, scale
, text
, number
, item
, dir
true
on success, otherwise returns nil
An interface to read config files in the format of minetest.conf
.
It can be created via Settings(filename)
.
get(key)
: returns a valueget_bool(key)
: returns a booleanset(key, value)
remove(key)
: returns a boolean (true
for success)get_names()
: returns {key1,...}
write()
: returns a boolean (true
for success)
to_table()
: returns {[key1]=value1,...}
Node metadata: reference extra data and functionality stored in a node.
Can be obtained via minetest.get_meta(pos)
.
get_string(name)
get_int(name)
get_float(name)
to_table()
: returns nil
or a table with keys:
fields
: key-value storageinventory
: {list1 = {}, ...}}
Raycast
A raycast on the map. It works with selection boxes. Can be used as an iterator in a for loop as:
local ray = Raycast(...)
for pointed_thing in ray do
...
end
The map is loaded as the ray advances. If the map is modified after the
Raycast
is created, the changes may or may not have an effect on the object.
It can be created via Raycast(pos1, pos2, objects, liquids)
or
minetest.raycast(pos1, pos2, objects, liquids)
where:
pos1
: start of the raypos2
: end of the rayobjects
: if false, only nodes will be returned. Default is true.liquids
: if false, liquid nodes won't be returned. Default is false.next()
: returns a pointed_thing
with exact pointing location
minetest.get_node_def(nodename)
nodename
minetest.get_item_def(itemstring)
itemstring
{
has_on_construct = bool, -- Whether the node has the on_construct callback defined
has_on_destruct = bool, -- Whether the node has the on_destruct callback defined
has_after_destruct = bool, -- Whether the node has the after_destruct callback defined
name = string, -- The name of the node e.g. "air", "default:dirt"
groups = table, -- The groups of the node
paramtype = string, -- Paramtype of the node
paramtype2 = string, -- ParamType2 of the node
drawtype = string, -- Drawtype of the node
mesh = <string>, -- Mesh name if existent
minimap_color = <Color>, -- Color of node on minimap *May not exist*
visual_scale = number, -- Visual scale of node
alpha = number, -- Alpha of the node. Only used for liquids
color = <Color>, -- Color of node *May not exist*
palette_name = <string>, -- Filename of palette *May not exist*
palette = <{ -- List of colors
Color,
Color
}>,
waving = number, -- 0 of not waving, 1 if waving
connect_sides = number, -- Used for connected nodes
connects_to = { -- List of nodes to connect to
"node1",
"node2"
},
post_effect_color = Color, -- Color overlayed on the screen when the player is in the node
leveled = number, -- Max level for node
sunlight_propogates = bool, -- Whether light passes through the block
light_source = number, -- Light emitted by the block
is_ground_content = bool, -- Whether caves should cut through the node
walkable = bool, -- Whether the player collides with the node
pointable = bool, -- Whether the player can select the node
diggable = bool, -- Whether the player can dig the node
climbable = bool, -- Whether the player can climb up the node
buildable_to = bool, -- Whether the player can replace the node by placing a node on it
rightclickable = bool, -- Whether the player can place nodes pointing at this node
damage_per_second = number, -- HP of damage per second when the player is in the node
liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
liquid_viscosity = <number>, -- How slow the liquid flows *May not exist*
liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
liquid_range = <number>, -- How far the liquid flows *May not exist*
drowning = bool, -- Whether the player will drown in the node
floodable = bool, -- Whether nodes will be replaced by liquids (flooded)
node_box = table, -- Nodebox to draw the node with
collision_box = table, -- Nodebox to set the collision area
selection_box = table, -- Nodebox to set the area selected by the player
sounds = { -- Table of sounds that the block makes
sound_footstep = SimpleSoundSpec,
sound_dig = SimpleSoundSpec,
sound_dug = SimpleSoundSpec
},
legacy_facedir_simple = bool, -- Whether to use old facedir
legacy_wallmounted = bool -- Whether to use old wallmounted
move_resistance = <number>, -- How slow players can move through the node *May not exist*
}
{
name = string, -- Name of the item e.g. "default:stone"
description = string, -- Description of the item e.g. "Stone"
type = string, -- Item type: "none", "node", "craftitem", "tool"
inventory_image = string, -- Image in the inventory
wield_image = string, -- Image in wieldmesh
palette_image = string, -- Image for palette
color = Color, -- Color for item
wield_scale = Vector, -- Wieldmesh scale
stack_max = number, -- Number of items stackable together
usable = bool, -- Has on_use callback defined
liquids_pointable = bool, -- Whether you can point at liquids with the item
tool_capabilities = <table>, -- If the item is a tool, tool capabilities of the item
groups = table, -- Groups of the item
sound_place = SimpleSoundSpec, -- Sound played when placed
sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
node_placement_prediction = string -- Node placed in client until server catches up
}
register_chatcommand
){
params = "<name> <privilege>", -- Short parameter description
description = "Remove privilege from player", -- Full description
func = function(param), -- Called when command is run.
-- Returns boolean success and text output.
}
{
address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
ip = "203.0.113.156", -- The IP address of the server.
port = 30000, -- The port the client is connected to.
protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0.
}
hud_add
, hud_get
){
type = "image", -- see HUD element types, default "text"
-- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
hud_elem_type = "image",
-- ^ Deprecated, same as `type`. In case both are specified `type` will be used.
position = {x=0.5, y=0.5},
-- ^ Left corner position of element, default `{x=0,y=0}`.
name = "<name>", -- default ""
scale = {x=2, y=2}, -- default {x=0,y=0}
text = "<text>", -- default ""
number = 2, -- default 0
item = 3, -- default 0
-- ^ Selected item in inventory. 0 for no item selected.
direction = 0, -- default 0
-- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
alignment = {x=0, y=0}, -- default {x=0, y=0}
-- ^ See "HUD Element Types"
offset = {x=0, y=0}, -- default {x=0, y=0}
-- ^ See "HUD Element Types"
size = { x=100, y=100 }, -- default {x=0, y=0}
-- ^ Size of element in pixels
style = 0,
-- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace
}
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 ColorStringcolor
minetest.colorize(color, message)
:
minetest.get_color_escape_sequence(color) ..
message ..
minetest.get_color_escape_sequence("#ffffff")
minetest.get_background_escape_sequence(color)
color
is a ColorStringcolor
. Only defined for item descriptions and tooltips.minetest.strip_foreground_colors(str)
get_color_escape_sequence
.minetest.strip_background_colors(str)
get_background_escape_sequence
.minetest.strip_colors(str)
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.
To specify the value of the alpha channel, append #A
or #AA
to the end of
the color name (e.g. colorname#08
).
Color
{a = alpha, r = red, g = green, b = blue}
defines an ARGB8 color.
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.precision
: Waypoint precision, integer >= 0. Defaults to 10.
If set to 0, distance is not shown. Shown value is floor(distance*precision)/precision
.
When the precision is an integer multiple of 10, there will be log_10(precision)
digits after the decimal point.
precision = 1000
, for example, will show 3 decimal places (eg: 0.999
).
precision = 2
will show multiples of 0.5
; precision = 5 will show multiples of 0.2
and so on:
precision = n
will show multiples of 1/n
number:
An integer containing the RGB value of the color used to draw the
text.world_pos
: World position of the waypoint.offset
: offset in pixels from position.alignment
: The alignment of the waypoint.image_waypoint
Same as image
, but does not accept a position
; the position is instead determined by world_pos
, the world position of the waypoint.
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.world_pos
: World position of the waypoint.offset
: offset in pixels from position.add_particle
){
pos = {x=0, y=0, z=0},
velocity = {x=0, y=0, z=0},
acceleration = {x=0, y=0, z=0},
-- ^ Spawn particle at pos with velocity and acceleration
expirationtime = 1,
-- ^ Disappears after expirationtime seconds
size = 1,
collisiondetection = false,
-- ^ collisiondetection: if true collides with physical objects
collision_removal = false,
-- ^ collision_removal: if true then particle is removed when it collides,
-- ^ requires collisiondetection = true to have any effect
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ Uses texture (string)
animation = {Tile Animation definition},
-- ^ optional, specifies how to animate the particle texture
glow = 0
-- ^ optional, specify particle self-luminescence in darkness
}
ParticleSpawner
definition (add_particlespawner
){
amount = 1,
time = 1,
-- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
minpos = {x=0, y=0, z=0},
maxpos = {x=0, y=0, z=0},
minvel = {x=0, y=0, z=0},
maxvel = {x=0, y=0, z=0},
minacc = {x=0, y=0, z=0},
maxacc = {x=0, y=0, z=0},
minexptime = 1,
maxexptime = 1,
minsize = 1,
maxsize = 1,
-- ^ The particle's properties are random values in between the bounds:
-- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
-- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
collisiondetection = false,
-- ^ collisiondetection: if true uses collision detection
collision_removal = false,
-- ^ collision_removal: if true then particle is removed when it collides,
-- ^ requires collisiondetection = true to have any effect
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ Uses texture (string)
}