Add more information to lua_api.txt

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index ec9a91bd4553692ff6845c0353c3bb97e0646542..1fbf7320db4d3e817515a9d3140fade94f089e13 100644 (file)
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1,17 +1,31 @@
 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
 -------------
@@ -32,9 +46,42 @@ On an installed version on linux:
   ~/.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
+|   `-- <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
 ----------------------------------------------
-"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.
@@ -49,12 +96,15 @@ 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 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
@@ -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
     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.register_entity(name, prototype table)