Luanti Lua Modding API Reference¶

WARNING: if you're looking for the minetest namespace (e.g. minetest.something), it's now called core due to the renaming of Luanti (formerly Minetest). minetest will keep existing as an alias, so that old code won't break.

Note that core has already existed since version 0.4.10, so you can use it safely without breaking backwards compatibility.

More information at http://www.luanti.org/
Additional documentation: https://docs.luanti.org/
(Unofficial) Luanti Modding Book by rubenwardy: https://rubenwardy.com/minetest_modding_book/
Modding tools: https://github.com/luanti-org/modtools

Introduction¶

Content and functionality can be added to Luanti using Lua scripting in run-time loaded mods.

A mod is a self-contained bunch of scripts, textures and other related things, which is loaded by and interfaces with Luanti.

Mods are contained and ran solely on the server side. Definitions and media files are automatically transferred to the client.

If you see a deficiency in the API, feel free to attempt to add the functionality in the engine and API, and to document it here.

Programming in Lua¶

If you have any difficulty in understanding this, please read Programming in Lua.

Startup¶

Mods are loaded during server startup from the mod load paths by running the init.lua scripts in a shared environment.

Paths¶

Luanti keeps and looks for files mostly in two paths. path_share or path_user.

path_share contains possibly read-only content for the engine (incl. games and mods). path_user contains mods or games installed by the user but also the users worlds or settings.

With a local build (RUN_IN_PLACE=1) path_share and path_user both point to the build directory. For system-wide builds on Linux the share path is usually at /usr/share/minetest while the user path resides in .minetest in the home directory. Paths on other operating systems will differ.

Numbers and integers¶

Lua 5.1 does not distinguish between floating-point numbers and integer numbers, but for some functions and data structures, Luanti will only accept integers (whole numbers).

Unless mentioned otherwise, number-type variables mentioned in this documentation are allowed to take any numeric value that Lua supports, both integer and floating-point numbers, positive and negative. If the word "number" is used, you can normally assume this to be the case. Exceptions: NaN, positive infinity and negative infinity should not be assumed to be supported unless mentioned explicitly.

Sometimes, the documentation will use the word "integer" (or "int" in short). In this case, only integer values are allowed, and fractional values must not be used. Integers can be positive or negative.

All integer values have a range with a defined minimum and maximum. Integer ranges are written as [min, max] and are inclusive. E.g. the integer range [0, 255] contains all integers from 0 to 255, including 0 and 255.

Some ranges in this documentation like [-2^15, 2^15-1] occur frequently, and may be abbreviated like so:

[s16]  = [-2^15    , 2^15-1] = [-32768, 32767]
[s32]  = [-2^31,   , 2^31-1] = [-2147483648, 2147483647]
[slua] = [-(2^53-1), 2^53-1] = [-9007199254740991, 9007199254740991]
[u16]  = [0,         2^16-1] = [0, 65535]
[u32]  = [0,         2^32-1] = [0, 4294967295]
[u64]  = [0,         2^64-1] = [0, 18446744073709551615]
[ulua] = [0,         2^53-1] = [0, 9007199254740991]
[imagesize]                  = [1, 23000]
[imageframe]                 = [0, 22999]

(s = "signed", ranges that include negative integers; u = "unsigned", ranges that don't include negative integers; these terms are borrowed from the C language)

The [slua] range is the safe integer range in Lua. This is the largest range of consecutive safe integers. An integer is 'safe' if it can be represented exactly as Lua number without loss of precision and it can be compared correctly. If you use an integer in Lua beyond that range, you might lose precision and numeric comparisons might return incorrect results. [ulua] is the same except it starts at 0.

The [imagesize] range represents the minimum and maximum width and height for texture modifiers.

The words "amount", "count", "index" and "bitfield" imply the use of an integer (e.g. an amount of items is an integer).

When the documentation expects an integer somewhere without specifying a range, assume the safe integer range ([slua]).

IMPORTANT: You must make sure your code only passes integers to any function or data structure that expects them. You must respect all integer ranges. Failing to do so may lead to undefined behavior and potential bugs.

Please note we don't have the resources to test every single edge case; we don't guarantee every number in range will work. Always use your own good judgement as well. Using extreme or unrealistic values within range is not forbidden, but please accept it if we are forced to restrict/fix a few of these ranges (in the documentation) in future releases.

Implementation details¶

In the Lua runtime used by Luanti, numbers are internally represented by the double data type of the C programming language. The range of [-(2^53-1), 2^53-1] is derived from IEEE-754 double-precision floating-point numbers. You can generally assume that on all systems that Luanti officially supports, the Lua number type implements IEEE-754 double-precision floating-point numbers.