Minetest Lua Modding API Reference 0.4.dev
==========================================
+More information at http://c55.me/minetest/
+
+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 <celeron55@gmail.com>.
Programming in Lua
-------------------
If you have any difficulty in understanding this, please read:
http://www.lua.org/pil/
-Helper functions
------------------
-dump2(obj, name="_", dumped={})
-^ Return object serialized as a string, handles reference loops
-dump(obj, dumped={})
-^ Return object serialized as a string
+Startup
+--------
+Mods are loaded during server startup from the mod load paths by running
+the init.lua scripts.
Mod load path
-------------
~/.minetest/mods/gameid/ <-- User-installed mods
~/.minetest/worlds/worldname/worldmods
+Mod directory structure
+------------------------
+mods
+|-- modname
+| |-- depends.txt
+| |-- init.lua
+| |-- textures
+| | |-- modname_stuff.png
+| | `-- modname_something_else.png
+| |-- sounds
+| |-- media
+| `-- <custom data>
+`-- 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.
+
+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.
+
+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
----------------------------------------------
-"modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
+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.
":experimental:tnt" when registering it.
(also that mod is required to have "experimental" as a dependency)
-The ":" prefix can be used for maintaining backwards compatibility.
+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, eg. if
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:
+ eg. foomod_foothing.png
+ eg. foomod_foothing
+
+Sounds
+-------
+Only OGG 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_, eg. 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 on all clients
+{
+ gain = 1.0, -- default
+}
+-- Play locationless to a player
+{
+ to_player = name,
+ gain = 1.0, -- default
+}
+-- Play in a location
+{
+ pos = {x=1,y=2,z=3},
+ gain = 1.0, -- default
+ max_hear_distance = 32, -- default
+}
+-- Play connected to an object, looped
+{
+ object = <an ObjectRef>,
+ gain = 1.0, -- default
+ max_hear_distance = 32, -- default
+ loop = true, -- only sounds connected to objects can be looped
+}
+
Representations of simple things
--------------------------------
MapNode representation:
subtraction and whatever; you can define those that you need yourself.
stackstring/itemstring: A stack of items in serialized format.
-eg. 'node "default:dirt" 5'
-eg. 'tool "default:pick_wood" 21323'
-eg. 'craft "default:apple" 2'
+eg. 'default:dirt 5'
+eg. 'default:pick_wood 21323'
+eg. 'default:apple'
item: A stack of items in Lua table format.
-eg. {name="default:dirt", count=1, wear=0, metadata=""}
- ^ a single dirt node
+eg. {name="default:dirt", count=5, wear=0, metadata=""}
+ ^ 5 dirt nodes
eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
^ a wooden pick about 1/3 weared out
eg. {name="default:apple", count=1, wear=0, metadata=""}
Any time an item must be passed to a function, it can be an
ItemStack (see below), an itemstring or a table in the above format.
+SimpleSoundSpec:
+eg. ""
+eg. "default_place_node"
+eg. {}
+eg. {name="default_place_node"}
+eg. {name="default_place_node", gain=1.0}
+
Items
------
Node (register_node):
* If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
automatically filled in based on the location of ''puncher''.
+Helper functions
+-----------------
+dump2(obj, name="_", dumped={})
+^ Return object serialized as a string, handles reference loops
+dump(obj, dumped={})
+^ Return object serialized as a string
+
minetest namespace reference
-----------------------------
+minetest.get_current_modname() -> string
+minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
+^ Useful for loading additional .lua modules or static data from mod
+minetest.get_worldpath(modname) -> eg. "/home/user/.minetest/world"
+^ Useful for storing custom data
+
+minetest.debug(line)
+^ Goes to dstream
+minetest.log(line)
+minetest.log(loglevel, line)
+^ loglevel one of "error", "action", "info", "verbose"
+
minetest.register_entity(name, prototype table)
minetest.register_abm(abm definition)
minetest.register_node(name, node definition)
minetest.register_craftitem(name, item definition)
minetest.register_alias(name, convert_to)
minetest.register_craft(recipe)
+
minetest.register_globalstep(func(dtime))
minetest.register_on_placenode(func(pos, newnode, placer))
minetest.register_on_dignode(func(pos, oldnode, digger))
^ return true in func to disable regular player placement
^ currently called _before_ repositioning of player occurs
minetest.register_on_chat_message(func(name, message))
+
minetest.add_to_creative_inventory(itemstring)
minetest.setting_get(name) -> string or nil
minetest.setting_getbool(name) -> boolean value or nil
+
minetest.chat_send_all(text)
minetest.chat_send_player(name, text)
minetest.get_player_privs(name) -> set of privs
minetest.get_inventory(location) -> InvRef
^ location = eg. {type="player", name="celeron55"}
{type="node", pos={x=, y=, z=}}
-minetest.get_current_modname() -> string
-minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
-^ Useful for loading additional .lua modules or static data from mod
-minetest.get_worldpath(modname) -> eg. "/home/user/.minetest/world"
-^ Useful for storing custom data
-minetest.debug(line)
-^ Goes to dstream
-minetest.log(line)
-minetest.log(loglevel, line)
-^ loglevel one of "error", "action", "info", "verbose"
+minetest.sound_play(spec, parameters) -> handle
+^ spec = SimpleSoundSpec
+^ parameters = sound parameter table
+minetest.sound_stop(handle)
+
+minetest.after(time, func, param)
+^ Call function after time seconds
+^ param is optional; to pass multiple parameters, pass a table.
Global objects:
minetest.env - environment reference
selection_box = {type="regular"},
legacy_facedir_simple = false, -- Support maps made in and before January 2012
legacy_wallmounted = false, -- Support maps made in and before January 2012
+ sounds = {
+ footstep = <SimpleSoundSpec>,
+ dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
+ dug = <SimpleSoundSpec>,
+ },
}
Recipe: (register_craft)