Add more information to lua_api.txt

This commit is contained in:
Perttu Ahola 2012-03-22 12:14:04 +02:00
parent 2469ce6067
commit fde676a43a

@ -1,17 +1,31 @@
Minetest Lua Modding API Reference 0.4.dev 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 Programming in Lua
------------------- -------------------
If you have any difficulty in understanding this, please read: If you have any difficulty in understanding this, please read:
http://www.lua.org/pil/ http://www.lua.org/pil/
Helper functions Startup
----------------- --------
dump2(obj, name="_", dumped={}) Mods are loaded during server startup from the mod load paths by running
^ Return object serialized as a string, handles reference loops the init.lua scripts.
dump(obj, dumped={})
^ Return object serialized as a string
Mod load path Mod load path
------------- -------------
@ -32,9 +46,42 @@ On an installed version on linux:
~/.minetest/mods/gameid/ <-- User-installed mods ~/.minetest/mods/gameid/ <-- User-installed mods
~/.minetest/worlds/worldname/worldmods ~/.minetest/worlds/worldname/worldmods
Mod directory structure
------------------------
mods
|-- modname
| |-- depends.txt
| |-- init.lua
| |-- textures
| | |-- modname_stuff.png
| | `-- modname_something_else.png
| `-- <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:
These textures will be transferred to the client and can be referred to
by the mod.
Naming convention for registered textual names 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 This is to prevent conflicting names from corrupting maps and is
enforced by the mod loader. enforced by the mod loader.
@ -49,12 +96,15 @@ Example: Any mod can redefine experimental:tnt by using the name
":experimental:tnt" when registering it. ":experimental:tnt" when registering it.
(also that mod is required to have "experimental" as a dependency) (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
------- -------
Aliases can be added by using minetest.register_alias(name, convert_to) 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 used for maintaining backwards compatibility.
This can be also used for setting quick access names for things, eg. if This can be also used for setting quick access names for things, eg. if
@ -299,6 +349,13 @@ To punch an entity/object in Lua, call ''object:punch(puncher, time_from_last_pu
* If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be * If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
automatically filled in based on the location of ''puncher''. 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 namespace reference
----------------------------- -----------------------------
minetest.register_entity(name, prototype table) minetest.register_entity(name, prototype table)