author | Wuzzy |
Fri, 21 Jun 2019 23:04:09 +0100 | |
changeset 1928 | 9f6f8a9b85f8 |
parent 1817 | 817767cd393b |
child 2147 | 95a745f14f21 |
permissions | -rw-r--r-- |
1749
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
1 |
#summary Overview of the Lua API |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
2 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
3 |
= Lua API: Overview = |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
4 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
5 |
This page is a brief overview of how the [LuaAPI Lua API] in Hedgewars is structured. For a beginner's guide, see [LuaGuide]. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
6 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
7 |
== How Hedgewars handles Lua scripts == |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
8 |
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. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
9 |
|
1773 | 10 |
== Missions == |
11 |
Missions are located within text files inside `share/hedgewars/Data/Missions/`. The game will list all files with the `.lua` extension inside this directory in the missions and campaigns selection screens. You’ll find some scripts within this directory that contain several comments on the script lines and what they do. |
|
1749
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
12 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
13 |
See [Missions] for details. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
14 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
15 |
== Special maps == |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
16 |
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. Mission maps can be found in singleplayer mode under the “training” button and in multiplayer mode, it is selectable as a map type. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
17 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
18 |
See also [PresetMaps] for more information about such maps. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
19 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
20 |
== How Lua scripts are used == |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
21 |
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”). |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
22 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
23 |
== Important things to know == |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
24 |
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. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
25 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
26 |
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. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
27 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
28 |
== Global variables/constants == |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
29 |
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. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
30 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
31 |
A list of globals can be found in [LuaGlobals]. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
32 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
33 |
== Functions called by the game: Event handlers == |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
34 |
After successfully loading the Lua script, the game will call event functions on different occasions. To be used, they have to use the exact same name as defined in the Lua API. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
35 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
36 |
A list of event handlers can be found in [LuaEvents]. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
37 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
38 |
== Data types == |
1817 | 39 |
This section defines some commonly used non-primitive parameter types which are used in multiple functions. |
1749
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
40 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
41 |
=== Color === |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
42 |
Some functions take a `color` parameter. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
43 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
44 |
Colors are stored in RGB or RGBA format and are specified as a three- or four-byte number, respecively. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
45 |
In 3-byte (RGB) colors, each byte represents a color component. The value 0 means no intensity and 255 is largest intensity of the component. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
46 |
The first byte is for the red component, the second byte for the green component and the third byte for the blue component. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
47 |
Four-byte (RGBA) colors use the first 3 bytes for the color components (like for the 3-byte colors) and the fourth byte is used for opacity, where 255 means maximum opacity and 0 means fully transparent (also called the “alpha channel”). |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
48 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
49 |
Specifying the color number becomes much easier if you write it in hexadecimal notation. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
50 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
51 |
Examples for RGB (3-byte) colors: |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
52 |
<code language="lua"> |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
53 |
c = 0x000000 -- black (R, G, B are all 0) |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
54 |
c = 0xFF0000 -- red |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
55 |
c = 0x00FF00 -- green |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
56 |
c = 0x0000FF -- blue |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
57 |
c = 0xFFFFFF -- white |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
58 |
c = 0x808080 -- gray (50%)</code> |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
59 |
|
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
60 |
Hint: On [http://www.colorpicker.com/] you find a color-picking tool for getting RGB colors easily. |
91756d20ce3e
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
61 |