= Lua guide =

This is both a simplistic introduction to Lua scripting in Hedgewars and a guide for more advanced control over the game. With Lua scripting, one can define own missions (both in training and campaign menu), [PresetMaps mission maps] (like Knockball) and styles (like Highlander).

A Lua script is used to make the game behave different by giving the Hedgewars engine different commands. The script gets called by the engine on different events and the script tells the engine what to do.

Lua is a programming language, and you must first learn some basics about the Lua programming language to get started. See [http://www.lua.org/] to learn more.

If you want to make a mission for multi player you create a map and create a new file `map.lua` in the map's folder.

If you want to make a training mission then you create a new `.lua` file under `Data/Missions/Training` folder. Campaign missions go into `Data/Missions/Training`.

If you want to make a custom game style like Highlander, create a new `.lua` file in `Data/Scripts/Multiplayer`.

To get started, the `.lua` file should be structured like this:

An example of setting up Barrel Mayhem in a style:

AddTeam("Team", 0xFF0002, "Simple", "Island", "Default", "hedgewars")

To be able to play you must add another team and hog that should have another team color (this team has `0xFF0002`) or if you only want one team add the game flag `gfOneClanMode`. Look into [LuaAPI] to see what the other parameters of `AddTeam` and `AddHog` are.

Here is an example of the initiation of a training mission:

    AddTeam("Team", 0xFF00002, "Simple", "Island", "Default", "hedgewars")

Mostly everything in Hedgewars are made out of gears: grenades, bazooka shells, and cakes just to name a few. But these are just the visible gears, the whip's effect and rising water are also gears. But for now we will focus on the more visible ones.

The hogs are gears, too and when you shoot with bazooka the bazooka shell will be created and explode when it hits the ground. When the shell is created the `onGearAdd` event is called and the `gear` parameter will be the bazooka.

And when it hits the ground, before the gear has been deleted, `onGearDelete` is invoked with the shell as parameter, after that it is removed.

Each gear has a [GearTypes gear type], for instance, a bazooka shell has the gear type of `gtShell`, a grenade has a gear type of `gtGrenade`, and so on. You will almost always need to check for the gear type with `GetGearType` in the `onGearAdd` function in order to do anything meaningful.

Gears also have a lot of various values to track their position, state, etc. These can be accessed and written to with several “getter” and “setter” functions like `GetPos`, `GetHealth`, `SetTag`, etc. See [LuaAPI] for a full list.

In Hedgewars, the gear values and some variable names do not always really mean what they seem to be, their concrete meaning often depends on the actual gear type. For instance, using `GetHealth(h)` on a hedgehog gear (gear type: `gtHedgehog`) will return its health (obviously). Less obviously, using `GetHealth` on a flying saucer gear (gear type: `gtJetpack`) will return its amount of fuel. To learn all the gory detaily about all those gears, see [GearTypes.

== Other important event handlers ==

The last very important event handlers are `onGameTick` and `onGameTick20`. `onGameTick` is called every game tick, that is every millisecond which is a thousand times a second. `onGameTick20` is called every 20 game ticks, that is, every 20 milliseconds. These functions are very important for specifying actions which need to happen regularily. It is important to know when to use `onGameTick`, and when to use `onGameTick20`. You can usually get away with just using `onGameTick` but must make sure any code inserted here must be efficient and fast, as this function is called very often. Complex code which takes more time to execute should go into `onGameTick20` instead.

If you need a different interval other than 1 or 20 milliseconds, you can use modulo on the `GameTicks` variable which holds the total number of game ticks since the beginning of the game.

== Getting started … for real ==

This was just a simplistic introduction which didn't cover everything. If you want to l

A good way to learn Lua scripting in Hedgewars is to read existing scripts. We recommend to take a look into `Data/Missions/Training/Basic_Training_-_Sniper_Rifle.lua` which is the Lua script for the Sniper Rifle target practice training mission. It should give you a rough “feeling” of how a script is supposed to look and is heavily commented.

Continue with the following pages to learn more:

* [LuaAPI] contains a reference of most available functions and global variables

* [LuaLibraries] contains information about “libraries”, that is, extra scripts you can include for even more functions. One common library is `Locale` for making a mission translatable

* [GearTypes] contains the list of all gear types, along with an explanation of how the gears and their values work