#summary List of event handlers in the Lua API

= Lua API: Event handlers =

Event handlers are [LuaAPI Lua] functions that Hedgewars calls on certain events. Lua scripts are supposed to _define_ these functions to do something. The functions are then _called_ by Hedgewars when a certain event has occured. For an example of how this works, see [LuaGuide].

This page is a list of all supported event handlers in Hedgewars.

This function is called before the game loads its resources. One can read and modify various [LuaGlobals#Game_variables game variables] here. These variables will become globally available after `onGameInit` has been invoked, but changing them has only an effect in `onGameInit`.

Most game variables are optional, but for missions, `Theme` must be set by the scripter if you want to use a random map, rather than an image map. All other variables do not need to be set by the scripter and have default values.

For a list of game variables that can be set here, see [LuaGlobals#Game_variables].

This function is called when the first round starts.

Can be used to show the mission and for more setup, for example initial target spawning.

At this stage, the global variables `LeftX`, `RightX`, `TopY`, `LAND_WIDTH` and `LAND_HEIGHT` become available.

This function is called when the map preview in the frontend is initialized. This happens when the script is selected or you change a map generator parameter.

It is useful for scripts which create their own maps (see `AddPoint` and `FlushPoints`). If you create a map in this function, a preview will be generated from this map and is exposed to the frontend.

This function is called when the script parameters (as specified in the game scheme) become available. The script parameter string is stored in the global variable `ScriptParam`.

Please note that it is normally not safe to call many of the other functions inside this function, this function is called very early in the game, only use this to initialize variables and other internal stuff like that.

*Tip*: If you use the Params library  (`/Scripts/Params.lua`), you can make the task of dissecting the string into useful values a bit easier, but it’s not required. (The Params library is not documented yet, however).

*Tip*: If you use this callback, make sure to document the interpretation of the parameters so others know how to set the parameters properly.

This function is called on every game tick, i.e. 1000 times a second. If you just need to check on something periodically, consider `onGameTick20`.

This function is called every 20 game ticks, which equals 50 times a second. It reduces Lua overhead for simple monitoring that doesn’t need to happen every single tick.

This function calls at the start of every turn. You can set `ReadyTimeLeft` here to change the ready time for this turn. (See also: `Ready`)

This function calls at the end of every turn. The end of a turn is defined as the point of time after the current hedgehog lost control and all the important gears are either gone or have settled.

`CurrentHedgehog` holds the gear ID of the hedgehog whose turn just ended.

This function is called at one of the earliest possible moment after the end of a turn. After this callback, Hedgewars then performs all the other stuff between turns. This includes things like: Applying poison or Sudden Death damage, calculating total hog damage, rising the water in Sudden Death, dropping a crate, checking victory, giving control to the next hog.

Because this function is called *before* victories are checked, this is useful to set up your victory conditions here.

This function calls when a hog skips its turn.

This function calls when the game ends with a winner or in a draw. If a clan wins, `winningClan` is the clan ID of the winning clan. If the game ends in a draw, `winningClan` is set to -1.

This function is called on the start of Sudden Death.

This function is called when your Hedgehog attacks.

This function is called when you press the high jump key.

This function is called when you press the long jump key.

This function is called when you press the precise key.

This function is called when you press the left key.

This function is called when you press the right key.

This function is called when you press the up key.

This function is called when you press the down key.

This function is called when you release the attack key.

This function is called when you release the down key.

This function is called when you press the attack key. Beginning with 0.9.21, the parameter `ammoType` is provided. It contains the ammo type of the weapon used for the attack. 

Note: If you want to detect when a turn was skipped, use `onSkipTurn()`. There is no guarantee that `onHogAttack(amSkip)` is called in such an event.

This function is called when you release the left key.

This function is called when you release the precise key.

This function is called when you release the right key.

It is get called when a weapon is selected or switched.

`msgParam` tells you which ammo type was selected.

This function is called when one of the weapon slot keys has been pressed.

`msgParam` tells the slot number minus 1 (i.e. `0` is for slot number 1, `1` is for slot number 2, etc.).

This function is called when a hog is switched to another.

This function is called when the player uses an animated emote for example by using the chat commands `/wave`, `/juggle`, etc.

`msgParam` tells you which animation was played:

|| *`msgParam`* || *Animation* || *Associated chat command* ||

|| 0 || Rolling up || `/rollup` ||

|| 1 || Sad face || `/sad` ||

|| 2 || Waving hand || `/wave` ||

|| 3 || Stupid winner's grin / “Awesome” face || `/hurrah` ||

|| 4 || Peeing || `/ilovelotsoflemonade` ||

|| 5 || Shrug || `/shrug` ||

|| 6 || Juggling || `/juggle` ||

This function is called when one of the timer keys is pressed.

`msgParams` tells the set timer in seconds (i.e. `3` for the 3 seconds timer key).

This function is called when you release the up key.

This function is called when a hedgehog with the gear ID `gearUid` is hidden (removed from the map).

This function is called when a hedgehog with the specified gear ID `gearUid` is restored (unhidden).

This function is called when a [Sprites Sprite] has been placed.

`spriteID` is the type of the sprite, you find a list at [Sprites Sprites]. `centerX` and `centerY` are the coordinates of the center of the sprite.

This function is called when a girder has been placed.

`frameIdx` is used for the length and orientation of the girder. The possible values are explained in `PlaceGirder`. `centerX` and `centerY` are the coordinates of the girder’s center.

This function is called when a rubber has been placed.

`frameIdx` is used for the rubber orientation. The possible values are explained in `PlaceRubber`. `centerX` and `centerY` are the coordinates of the rubber’s center.

This is used while a special hand-drawn map is loaded. The engine is building these hand-drawn maps by reading points from the map definition. Optionally, some of these points may be “special”. These are not actually drawn on the map, but are used to store additional information for a position on the map. Special points currently need to be added manually in the map, the in-game editor is not able to add those yet.

Now, when such a special point at the coordinates `x` and `y` with an assigned value of `flags` is added, this function is called. `flags` is a whole number between `0` and `255` inclusive.

This function is used in Racer and !TechRacer to define waypoints.