#summary Overview of the Lua API

= Lua API: Overview =

This page is a brief overview of how the [LuaAPI Lua API] in Hedgewars is structured. For a beginner's guide, see [LuaGuide].

== How Hedgewars handles Lua scripts ==

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.

== Missions ==

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.

See [Missions] for details.

== 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. Mission maps can be found in singleplayer mode under the “training” button and in multiplayer mode, it is selectable as a map type.

See also [PresetMaps] for more information about such maps.

== 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.

== Scripting rules ==

To make sure your script is functional on multiple systems and for online play, some simple but important development rules need to be followed. See [LuaRules].

== 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.

A list of globals can be found in [LuaGlobals].

== Functions called by the game: Event handlers ==

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.

A list of event handlers can be found in [LuaEvents].

== Data types ==

This section defines some commonly used non-primitive parameter types which are used in multiple functions.

=== Color ===

Some functions take a `color` parameter.

Colors are stored in RGB or RGBA format and are specified as a three- or four-byte number, respecively.

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.

The first byte is for the red component, the second byte for the green component and the third byte for the blue component.

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”).

Specifying the color number becomes much easier if you write it in hexadecimal notation.

Examples for RGB (3-byte) colors:

<code language="lua">

c = 0x000000 -- black (R, G, B are all 0)

c = 0xFF0000 -- red

c = 0x00FF00 -- green

c = 0x0000FF -- blue

c = 0xFFFFFF -- white

c = 0x808080 -- gray (50%)</code>

Hint: On [http://www.colorpicker.com/] you find a color-picking tool for getting RGB colors easily.

=== Coordinates ===

Every position on the map can be addressed with Cartesian coordinates: X and Y. Those are integers.

 * X is the horizontal axis. It starts at 0 on the left side of the map and increases when you go right

 * Y is the vertical axis. It starts at 0 at the top of the map and increases when you go downwards

X and Y can be negative when you go above or left of the map boundaries.

Some global variables contain important coordinates, see [LuaGlobals].