Minetest Lua Modding API Reference 0.4.13
=========================================
* More information at
* Developer Wiki:
Introduction
------------
Content and functionality can be added to Minetest 0.4 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.
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. You can send such improvements as
source code patches to .
Programming in Lua
------------------
If you have any difficulty in understanding this, please read
[Programming in Lua](http://www.lua.org/pil/).
Startup
-------
Mods are loaded during server startup from the mod load paths by running
the `init.lua` scripts in a shared environment.
Paths
-----
* `RUN_IN_PLACE=1` (Windows release, local build)
* `$path_user`:
* Linux: ``
* Windows: ``
* `$path_share`
* Linux: ``
* Windows: ``
* `RUN_IN_PLACE=0`: (Linux release)
* `$path_share`
* Linux: `/usr/share/minetest`
* Windows: `/minetest-0.4.x`
* `$path_user`:
* Linux: `$HOME/.minetest`
* Windows: `C:/users//AppData/minetest` (maybe)
Games
-----
Games are looked up from:
* `$path_share/games/gameid/`
* `$path_user/games/gameid/`
where `gameid` is unique to each game.
The game directory contains the file `game.conf`, which contains these fields:
name =
e.g.
name = Minetest
The game directory can contain the file minetest.conf, which will be used
to set default settings when running the particular game.
### Menu images
Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory.
The images are named `$identifier.png`, where `$identifier` is one of `overlay,background,footer,header`.
If you want to specify multiple images for one identifier, add additional images named like `$identifier.$n.png`, with an ascending number $n starting with 1,
and a random image will be chosen from the provided ones.
Mod load path
-------------
Generic:
* `$path_share/games/gameid/mods/`
* `$path_share/mods/`
* `$path_user/games/gameid/mods/`
* `$path_user/mods/` (User-installed mods)
* `$worldpath/worldmods/`
In a run-in-place version (e.g. the distributed windows version):
* `minetest-0.4.x/games/gameid/mods/`
* `minetest-0.4.x/mods/` (User-installed mods)
* `minetest-0.4.x/worlds/worldname/worldmods/`
On an installed version on Linux:
* `/usr/share/minetest/games/gameid/mods/`
* `$HOME/.minetest/mods/` (User-installed mods)
* `$HOME/.minetest/worlds/worldname/worldmods`
Mod load path for world-specific games
--------------------------------------
It is possible to include a game in a world; in this case, no mods or
games are loaded or checked from anywhere else.
This is useful for e.g. adventure worlds.
This happens if the following directory exists:
$world/game/
Mods should be then be placed in:
$world/game/mods/
Modpack support
----------------
Mods can be put in a subdirectory, if the parent directory, which otherwise
should be a mod, contains a file named `modpack.txt`. This file shall be
empty, except for lines starting with `#`, which are comments.
Mod directory structure
------------------------
mods
|-- modname
| |-- depends.txt
| |-- screenshot.png
| |-- description.txt
| |-- init.lua
| |-- models
| |-- textures
| | |-- modname_stuff.png
| | `-- modname_something_else.png
| |-- sounds
| |-- media
| `--
`-- another
### modname
The location of this directory can be fetched by using
`minetest.get_modpath(modname)`.
### `depends.txt`
List of mods that have to be loaded before loading this mod.
A single line contains a single modname.
Optional dependencies can be defined by appending a question mark
to a single modname. Their meaning is that if the specified mod
is missing, that does not prevent this mod from being loaded.
### `screenshot.png`
A screenshot shown in modmanager within mainmenu.
### `description.txt`
A File containing description to be shown within mainmenu.
### `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.
`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
to read custom or existing settings at load time, if necessary.
### `models`
Models for entities or meshnodes.
### `textures`, `sounds`, `media`
Media files (textures, sounds, whatever) that will be transferred to the
client and will be available for use by the mod.
Naming convention for registered textual names
----------------------------------------------
Registered names should generally be in this format:
"modname:" ( can have characters a-zA-Z0-9_)
This is to prevent conflicting names from corrupting maps and is
enforced by the mod loader.
### Example
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.
### Aliases
Aliases can be added by using `minetest.register_alias(name, convert_to)`.
This will make Minetest to convert things called name to things called
`convert_to`.
This can be used for maintaining backwards compatibility.
This can be also used for setting quick access names for things, e.g. if
you have an item called `epiclylongmodname:stuff`, you could do
minetest.register_alias("stuff", "epiclylongmodname:stuff")
and be able to use `/giveme stuff`.
Textures
--------
Mods should generally prefix their textures with `modname_`, e.g. given
the mod name `foomod`, a texture could be called:
foomod_foothing.png
Textures are referred to by their complete name, or alternatively by
stripping out the file extension:
* e.g. `foomod_foothing.png`
* e.g. `foomod_foothing`
Texture modifiers
-----------------
There are various texture modifiers that can be used
to generate textures on-the-fly.
### Texture overlaying
Textures can be overlaid by putting a `^` betwMinetest Android port
=====================
Date: 2014 06 28
Controls
--------
The Android port doesn't support everything you can do on PC due to the
limited capabilities of common devices. What can be done is described
below:
While you're playing the game normally (that is, no menu or inventory is
shown), the following controls are available:
* Look around: touch screen and slide finger
* double tap: place a node or use selected item
* long tap: dig node
* touch shown buttons: press button
* Buttons:
** left upper corner: chat
** right lower corner: jump
** right lower corner: crouch
** left lower corner: walk/step...
left up right
down
** left lower corner: display inventory
When a menu or inventory is displayed:
* double tap outside menu area: close menu
* tap on an item stack: select that stack
* tap on an empty slot: if you selected a stack already, that stack is placed here
* drag and drop: touch stack and hold finger down, move the stack to another
slot, tap another finger while keeping first finger on screen
--> places a single item from dragged stack into current (first touched) slot
Special settings
----------------
There are some settings especially useful for Android users. Minetest's config
file can usually be found at /mnt/sdcard/Minetest.
* gui_scaling: this is a user-specified scaling factor for the GUI- In case
main menu is too big or small on your device, try changing this
value.
* inventory_image_hack: if your inventory items are messed up, try setting
this to true
Known issues
------------
Not all issues are fixed by now:
* Unable to exit from volume menu -- don't use the volume menu, use Android's
volume controls instead.
* 512 MB RAM seems to be inadequate -- this depends on the server you join.
Try to play on more lightweight servers.
Versioning
----------
Android version numbers are 4 digits instead of Minetest's 3 digits. The last
number of Android's version represents the Android internal version code. This
version code is strictly incremental. It's incremented for each official
Minetest Android build.
E.g. prerelease Minetest Android builds have been 0.4.9.3, while the first
official version most likely will be 0.4.10.4
Requirements
------------
In order to build, your PC has to be set up to build Minetest in the usual
manner (see the regular Minetest documentation for how to get this done).
In addition to what is required for Minetest in general, you will need the
following software packages. The version number in parenthesis denotes the
version that was tested at the time this README was drafted; newer/older
versions may or may not work.
* android SDK (x86_64 20131030)
* android NDK (r9d)
* wget (1.13.4)
Additionally, you'll need to have an Internet connection available on the
build system, as the Android build will download some source packages.
Build
-----
Debug build:
* Enter "build/android" subdirectory
* Execute "make"
* Answer the questions about where SDK and NDK are located on your filesystem
* Wait for build to finish
After the build is finished, the resulting apk can be fond in
build/android/bin/. It will be called Minetest-debug.apk
Release build:
* In order to make a release build you'll have to have a keystore setup to sign
the resulting apk package. How this is done is not part of this README. There
are different tutorials on the web explaining how to do it
- choose one yourself.
* Once your keystore is setup, enter build/android subdirectory and create a new
file "ant.properties" there. Add following lines to that file:
> key.store=<path to your keystore>
> key.alias=Minetest
* Execute "make release"
* Enter your keystore as well as your Mintest key password once asked. Be
careful it's shown on console in clear text!
* The result can be found at "bin/Minetest-release.apk"
Other things that may be nice to know
------------
* The environment for Android development tools is saved within Android build
build folder. If you want direct access to it do:
> make envpaths
> . and_env
After you've done this you'll have your path and path variables set correct
to use adb and all other Android development tools
* You can build a single dependency by calling make and the dependency's name,
e.g.:
> make irrlicht
* You can completely cleanup a dependency by calling make and the "clean" target,
e.g.:
> make clean_irrlicht