3 |
3 |
4 = Core Lua API documentation = |
4 = Core Lua API documentation = |
5 |
5 |
6 == Introduction == |
6 == Introduction == |
7 |
7 |
8 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. |
8 This page is the API reference for the Lua scripts in Hedgewars and contains all Lua functions, variables and features that Hedgewars supports. For a detailed introduction, see [LuaGuide]. |
9 |
|
10 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 [http://www.lua.org 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. |
|
11 |
|
12 === About this wiki page === |
|
13 This page might become outdated. For a list of undocumented functions, see [http://hw.ercatec.net/docs/lua_wiki_check.php]. |
|
14 |
9 |
15 <wiki:toc max_depth="4" /> |
10 <wiki:toc max_depth="4" /> |
16 |
11 |
17 == Overview == |
12 == Overview == |
18 === How Hedgewars handles Lua scripts === |
13 === How Hedgewars handles Lua scripts === |
19 As of Version 0.9.20, Hedgewars supports Lua scripts for two similar tasks: Define tutorial missions, campaign missions or provide special map behaviour for precreated maps. It is also used for multiplayer scripts to create new game styles. |
14 Hedgewars supports Lua scripts for two similar tasks: Define tutorial missions, campaign missions or provide special map behaviour for precreated maps. It is also used for multiplayer scripts to create new game styles. |
20 |
15 |
21 === Tutorial missions === |
16 === Tutorial missions === |
22 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. |
17 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. |
23 |
18 |
24 See [Missions] for details. |
19 See [Missions] for details. |
29 See also [PresetMaps] for more information about such maps. |
24 See also [PresetMaps] for more information about such maps. |
30 |
25 |
31 === How Lua scripts are used === |
26 === How Lua scripts are used === |
32 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”). |
27 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”). |
33 |
28 |
34 |
|
35 === Important things to know === |
29 === Important things to know === |
36 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. |
30 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. |
37 |
31 |
38 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. |
32 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. |
39 |
33 |
40 === Global variables/constants === |
34 === Global variables/constants === |
41 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. |
35 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. |
42 |
|
43 |
36 |
44 === Functions called by the game: Event handlers === |
37 === Functions called by the game: Event handlers === |
45 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. |
38 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. |
46 |
39 |
47 == Data types == |
40 == Data types == |
68 |
61 |
69 Hint: On [http://www.colorpicker.com/] you find a color-picking tool for getting RGB colors easily. |
62 Hint: On [http://www.colorpicker.com/] you find a color-picking tool for getting RGB colors easily. |
70 |
63 |
71 |
64 |
72 == Globally available variables and constants == |
65 == Globally available variables and constants == |
73 The following variables are made available by Hedgewars in Lua and can be used to quickly query a value. Lua scripts schould normally *not* write to these variables, only read from them. |
66 The following variables are made available by Hedgewars in Lua and can be used to quickly query a value. Lua scripts should *not* write to these variables, only read from them. |
74 |
67 |
75 === General variables and constants === |
68 === General variables and constants === |
76 Here are some unsorted variables or constants which are available in Lua. *Consider these variables to be read-only.* |
69 Here are some unsorted variables or constants which are available in Lua. *Consider these variables to be read-only.* |
77 |
70 |
78 || *Identifier* || *Description* || |
71 || *Identifier* || *Description* || |
1774 Calling this function ends an engine test and reports a test result. |
1767 Calling this function ends an engine test and reports a test result. |
1775 |
1768 |
1776 `success` is either one of `TEST_SUCCESSFUL` to report a successful test or `TEST_FAILED` for a failed test. |
1769 `success` is either one of `TEST_SUCCESSFUL` to report a successful test or `TEST_FAILED` for a failed test. |
1777 |
1770 |
1778 See [EngineTestCases] to learn more about testing the engine. |
1771 See [EngineTestCases] to learn more about testing the engine. |
|
1772 |
|
1773 == Undocumented functions == |
|
1774 This page might become outdated. For a list of undocumented functions, see [http://hw.ercatec.net/docs/lua_wiki_check.php]. |