# HG changeset patch
# User sheepyluva@gmail.com
# Date 1366970348 0
# Node ID 6c0397400a9b34e8744f1d02ef286801e0780905
# Parent  5569dc51a89f5849962fffb2cb5ff9e91ea46519
Add Smaxx' nice lua API introduction from the hedgewars.org wiki

diff -r 5569dc51a89f -r 6c0397400a9b LuaAPI.wiki
--- a/LuaAPI.wiki	Tue Mar 26 16:58:02 2013 +0000
+++ b/LuaAPI.wiki	Fri Apr 26 09:59:08 2013 +0000
@@ -2,6 +2,41 @@
 #labels Featured
 <wiki:toc max_depth="3" />
 
+== Introduction ==
+
+Version 0.9.13 of Hedgewars introduced the ability to use Lua scripts to modify Hedgewars behaviour for different maps without having to recompile the whole game. The till then used triggers (only appeared in training maps) were removed.
+
+Lua is an easy to learn scripting language that's implemented using open source libraries. If you'd like to learn more about Lua, have a look at Lua's official homepage. Even though its easy to learn syntax this wiki page won't explain all basics of using Lua, e.g. declaring variables or using control structures. There are tons of step-by-step tutorials and documentation available on the internet. Just throw "Lua" into your favourite search engine and give it a try.
+
+
+How Hedgewars handles Lua scripts As of Version 0.9.13 Hedgewars supports Lua scripts for two similar tasks: Define tutorial missions or provide special map behaviour for precreated maps.
+
+
+=== Tutorial missions ===
+Tutorial missions are located within text files inside "share/hedgewars/Data/Missions/Training". The game will list all files with the lua extension inside this directory in the Training selection screen. You'll find some premade example scripts within this directory that contain several comments on the script lines and what they do.
+
+
+=== Special maps ===
+In addition to tutorial missions predrawn maps (maps not created using the random map creator) may contain a single lua script file named "map.lua". If it's there it will be used once the map is played. This way it's possible to play maps alone or over the internet using custom goals. Maps containing lua scripts will be listed with a "Mission:" prefix in map selection.
+
+
+=== How Lua scripts are used ===
+Several parts of script files are executed multiple times. In general, the whole script file is read while loading the map. Declarations as well as function calls outside functions are executed at once. Later on the game will call special predefined function names at special occassions such as the creation of new game objects (called gears).
+
+
+=== Important things to know ===
+It is possible to play missions in multiplayer. However this requires all participating players to have the exact same version of the map files, including the "map.lua" script file. If this isn't the case the game will probably desync and kick at least the one player using a different version of the map files. To avoid problems when running prepackaged maps, you should never modify any maps provided with the Hedgewars default package. Instead, create a copy of the existing map and modify this one. Feel free to share your work on the forums.
+Another thing to note is the current status of our scripting implementation. Similar to the whole game, this is still work in progress and we can't guarantee that scripts working in this version will run in future revisions of the game as we might extend, change or rename parts of the scripting engine.
+
+
+=== Global variables/constants ===
+Global variables are used by the game to interact with the scripts by passing and retrieving their values. While some of the variables are never read by the engine some allow you to modify the engine's behaviour, e.g. the theme to be used for the current map.
+
+  	  	 
+=== Functions called by the game: Event Handlers ===
+After successfully loading the Lua script the game will call the following functions on different occasions. To be used, they have to use the exact same name as defined below.
+
+
 == Global available Constants ==
 
 <blockquote><tt>LAND_WIDTH</tt>, <tt>LAND_HEIGHT</tt>