#summary API for writing Lua scripts in Hedgewars.
#labels Featured

= Core Lua API documentation =

== Introduction ==

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.

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.

=== About this wiki page ===
This page might become outdated. For a list of undocumented functions, see [http://hw.ercatec.net/docs/lua_wiki_check.php].

<wiki:toc max_depth="4" />

== Overview ==
=== How Hedgewars handles Lua scripts ===
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.

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

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.

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

  	  	 
=== Functions called by the game: Event handlers ===
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.

== Data types ==
This section defines some commonly used non-primitive parameter types which are used in multiple functions. This section is a bit incomplete at the moment.

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


== Globally available variables and constants ==
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.

=== General variables and constants ===
Here are some unsorted variables or constants which are available in Lua. *Consider these variables to be read-only.*

|| *Identifier* || *Description* ||
|| `LOCALE` || Current locale identifier (e.g. `"de"` for German) ||
|| `INTERFACE` || Type of the game interface: `"desktop"` for desktop, `"touch"` for touchscreen ||
|| `MAX_HOG_HEALTH` || Maximum possible hedgehog health ||
|| `MAX_TURN_TIME` || Maximum possible turn time in milliseconds ||
|| `LAND_WIDTH` || The width of the landscape in pixels. Not available before `onGameStart` ||
|| `LAND_HEIGHT` || The height of the landscape in pixels. Not available before `onGameStart` ||
|| `LeftX` || X coordinate of the leftmost point of the landscape. Not available before `onGameStart` ||
|| `RightX` || X coordinate of the rightmost point of the landscape. Not available before `onGameStart` ||
|| `TopY` || Y coordinate of the topmost point of the landscape. Not available before `onGameStart` ||
|| `CursorX` || The X position of the cursor if the player is choosing a target. Otherwise, this equals `NO_CURSOR` ||
|| `CursorY` || The Y position of the cursor if the player is choosing a target. Otherwise, this equals `NO_CURSOR` ||
|| `WaterLine` || The y position of the water, used to determine at which position stuff drowns. Use `SetWaterLine` to change. ||
|| `ClansCount` || Number of clans, including defeated ones (a clan is a group of teams with same color) ||
|| `TeamsCount` || Number of teams, including defeated ones ||
|| `TurnTimeLeft` || Number of game ticks (milliseconds) left until the current turn ends. To set this value, use `SetTurnTimeLeft` ||
|| `ReadyTimeLeft` || Remaining ready time in millseconds, 0 if turn in progress. To set this value, use `SetReadyTimeLeft` ||
|| `GameTime` || Number of total game ticks ||
|| `TotalRounds` || Number of rounds that have passed. Equals `-1` if game has not started yet or hogs are still being placed. ||
|| `CurrentHedgehog` || The hedgehog gear that is currently in play ||
|| `AmmoTypeMax` || Maximum ammo type ID (useful to iterate through all ammo types, starting by 0) ||

=== !GameFlags ===
The !GameFlags are used to store simple boolean settings of the game.
You can read/modify them using the [LuaAPI#GameFlags_functions GameFlags-Functions].

|| *Identifier* || *Description (active state)* ||
|| `gfOneClanMode` || Used when only one clan is in the game. This game flag is primarily used for training missions. ||
|| `gfMultiWeapon` || Shooting any weapon enters multi-shot mode with infinite shots. The remaining shots counter for weapons like shotgun is suppressed. Intended for target practice missions, not recommended for anything else. ||
|| `gfSwitchHog` || Free hog switching at turn start ||
|| `gfDivideTeams` || Each clan will start in its own side of the terrain. No effect if `gfPlaceHog` is active. ||
|| `gfBorder` || An indestructible border is active around the map. ||
|| `gfBottomBorder` || There is an indestructable border at the bottom of the map. ||
|| `gfShoppaBorder` || The terrain edge will be replaced by a decorative black/yellow “danger stripe”. This has no gameplay effect. ||
|| `gfSolidLand` || The terrain is indestructible. ||
|| `gfLowGravity` || The gravity is low. ||
|| `gfLaserSight` || A laser sight is almost always active. ||
|| `gfInvulnerable` || All hedgehogs are invulnerable. ||
|| `gfVampiric` || All hedgehogs become vampires and get 80% of the damage they deal as health. ||
|| `gfKarma` || Attackers share the damage they deal to enemies. ||
|| `gfArtillery` || Hedgehogs can’t walk. ||
|| `gfRandomOrder` || The game is played in random order. ||
|| `gfPlaceHog` || Placement mode: At the beginning of the round, all hedgehogs are placed manually first. ||
|| `gfKing` || King Mode: One hedgehog per team becomes their king, if the king dies, the team loses. ||
|| `gfSharedAmmo` || Teams in the same clan share their ammo. Takes precedence over `gfPerHogAmmo`.  ||
|| `gfDisableGirders` || No girders will be created in random maps ||
|| `gfDisableLandObjects` || No land objects will be created in random maps ||
|| `gfAISurvival` || Computer-controlled hedgehogs will be revived after they die. ||
|| `gfInfAttack` || Attacks don’t end the turn. ||
|| `gfResetWeps` || The weapons will be reset to the initial state each turn. ||
|| `gfPerHogAmmo` || Each hedgehog has its own weapon stash. No effect if `gfSharedAmmo` is active. ||
|| `gfDisableWind` || There is no wind. ||
|| `gfMoreWind` || There is always strong wind. ||
|| `gfTagTeam` || Tag Team: Teams in the same clan share their turn time. ||
|| `gfResetHealth` || The health of all living hedgehogs is reset at the end of each turn. ||

=== Land flags ===
The land flags denote several types of terrain. Like all flags, they can be combined at will.

|| *Identifier* || *Meaning* ||
|| `lfIce` || Slippery terrain, hogs will slide on it. ||
|| `lfBouncy` || Bouncy terrain, hogs and some other gears will bounce off when they collide with it. ||
|| `lfIndestructible` || Almost indestructible terrain, most weapons will not destroy it. ||
|| `0` || Normal destroyable terrain. Note that this is the case when no other land flag is set. ||

=== More constants ===
More constants are at at [GearTypes Gear Types] , [AmmoTypes Ammo Types], [Sounds], [States], [Sprites], [VisualGearTypes Visual Gear Types].

== Event handlers ==
Lua scripts are supposed to _define_ these functions to do something. The functions are then _called_ by Hedgewars when a certain event has occoured.

=== <tt>onGameInit()</tt> ===
This function is called before the game loads its resources. One can read and modify various game variables here. These variables will become globally available after `onGameInit` has been invoked, but changing them has only an effect in `onGameInit`.
Most 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.

List of game variables:
|| *Identifier* || *Default* || *Description* ||
|| `Theme` || _depends_ || The theme to be used. When `Map` is set, a default value is used. For missions which don't use an image map, `Theme` *must* be set explicitly ||
|| `Map` || `""` || The image map being played or `""` if no image map is used ||
|| `Seed` || `0` || Seed of the random number generator ||
|| `LandDigest` || _N/A_ || Digest for the current map. Only meant for internal use by Hedgewars ||
|| `MapGen` || `mgRandom` || Type of map generator. One of `mgRandom`, `mgMaze`, `mgPerlin`, `mgDrawn`. ||
|| `TemplateFilter` || `0` || _unknown meaning_ ||
|| `TemplateNumber` || `0` || _unknown meaning_ ||
|| `MapFeatureSize` || `50` || Used by random maps to determine its “curvyness” or complexity. This value can be set by the user with the slider under the random map preview in the game setup screen. The user-set value ranges from 1 (leftmost position) to 25 (rightmost position). A good starting value is `12`. ||
|| `GameFlags` || `0` || All `GameFlags` combined as a bitmask. Setting `GameFlags` directly is discouraged, use the [LuaAPI#GameFlags_functions] instead ||
|| `Ready` || `5000` || Ready timer at the start of the turn (in milliseconds) ||
|| `Delay` || `100` || Delay between each turn in milliseconds ||
|| `TurnTime` || `45000` || Turn time in milliseconds ||
|| `GetAwayTime` || `100` || Retreat time in percent ||
|| `CaseFreq` || `5` || Probability that a crate drops in a turn. 0: never, >0: probability = `1/CaseFreq` ||
|| `MaxCaseDrops` || `5` || Maximum number of crates that can be in the game before the random crate drops stop ||
|| `HealthCaseProb` || `35` || Chance that a crate drop is a health crate, in percent (other crates are ammo or utility crates) ||
|| `HealthCaseAmount` || `25` || Amount of health in a health crate ||
|| `DamagePercent` || `100` || Global damage in percent, affects damage and knockback ||
|| `RopePercent` || `100` || Rope length in percent ||
|| `MinesNum` || `4` || Number of mines being placed on a medium-sized map ||
|| `MinesTime` || `3000` || Time for a mine to explode from activated (in milliseconds), `-1000` for random ||
|| `MineDudPercent` || `0` || Chance of mine being a dud, in percent ||
|| `AirMinesNum` || `0` || Number of air mines being placed on a medium-sized map ||
|| `Explosives` || `2` || Number of barrels being placed on a medium-sized map ||
|| `SuddenDeathTurns` || `15` || Number of rounds until Sudden Death begins, _after the first round is over_. E.g. 0 = SD starts in 2nd round ||
|| `WaterRise` || `47` || Height of water rise in pixels for each Sudden Death turn ||
|| `HealthDecrease` || `5` || Amount of health decreased on each turn in Sudden Death ||
|| `Goals` || `""` || Use this to add additional text to the goal text popup shown at the beginning and when using the quit or pause keys. The text is added to the default text which usually explains the game modifiers and does not replace it. Use `|` for line breaks. Also, all text before and including a `:` in a line will be highlighted. See also `ShowMission`. ||
|| `WorldEdge` || `weNone` || Type edges being used at the left and right sides of the terrain (see below). ||
|| `ScreenWidth` || _N/A_ || Width of the Hedgewars window or screen ||
|| `ScreenHeight` || _N/A_ || Height of the Hedgewars window or screen ||

The proper way to disable Sudden Death is by setting both `WaterRise` and `HealthDecrease` to `0`.

If you want to add teams or hogs manually, you have to do it here. If you want to draw your own map using `AddPoint` and `FlushPoints`, you have to do this within this function as well.

==== <tt>!WorldEdge</tt> ====
The value of `WorldEdge` can have the following values:

|| *Identifier* || *Meaning* ||
|| `weNone` || No world edges ||
|| `weBounce` || Bouncy world edges ||
|| `weWrap` || World wraps around at the edges ||
|| `weSea` || Ocean world edges ||

=== <tt>onGameStart()</tt> ===
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.

=== <tt>onPreviewInit()</tt> ===
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.

=== <tt>onParameters()</tt> ===
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.

=== <tt>onGameTick()</tt> ===
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`.

=== <tt>onGameTick20()</tt> ===
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.

=== <tt>onNewTurn()</tt> ===
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`)

=== <tt>onEndTurn()</tt> (0.9.24) ===
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.

=== <tt>onSkipTurn()</tt> (0.9.24) ===
This function calls when a hog skips its turn.

=== <tt>onSuddenDeath()</tt> ===
This function is called on the start of Sudden Death.

=== <tt>onGearAdd(gearUid)</tt> ===
This function is called when a new gear is added. Useful in combination with `GetGearType(gearUid)`.

=== <tt>onGearDelete(gearUid)</tt> ===
This function is called when a new gear is deleted. Useful in combination with `GetGearType(gearUid)`.

=== <tt>onVisualGearAdd(vgUid)</tt> (0.9.23) ===
This function is called when a new visual gear is added. Useful in combination with `GetVisualGearType(vgUid)`.

=== <tt>onVisualGearDelete(vgUid)</tt> (0.9.23) ===
This function is called when a new visual gear is deleted. Useful in combination with `GetVisualGearType(vgUid)`.

=== <tt>onGearDamage(gearUid, damage)</tt> ===
This function is called when a gear is damaged.

Example:

<code language="lua">    function onGearDamage(gear, damage)
        if (GetGearType(gear) == gtHedgehog) then
            -- adds a message saying, e.g. "Hoggy H took 25 points of damage"
            AddCaption(GetHogName(gear) .. ' took ' .. damage .. ' points of damage')
        end
    end</code>
=== <tt>onGearResurrect(gearUid, spawnedVGear) </tt> ===
This function is called when a gear is resurrected due to the hog effect `heResurrectable` being set (see `SetEffect`) and/or being an AI hog when the game modifier “AI Survival” (`gfAISurvival`) is active. It is *not* called when a hog was resurrected by the resurrector tool you can use in the game.

`spawnedVGear` is a visual gear handle of the “resurrection effect”. You can use this handle to modify or delete the resurrection animation.

=== <tt>onAmmoStoreInit()</tt> ===
This function is called when the game is initialized to request the available ammo and ammo probabilities. Use `SetAmmo` here.

=== <tt>onNewAmmoStore(team/clan index, hog index)</tt> ===
This function is identical to `onAmmoStoreInit` in function, but is called once per ammo store.  This allows different ammo sets for each clan, team or hedgehog depending on the mode.
If `gfSharedAmmo` is set, the parameters passed are the clan index, and `-1`, and the function will be called once for each clan.
If `gfPerHogAmmo` is set, the parameters passed are the team index and the hog index in that team, and the function will be called once for each hedgehog.
If neither is set, the parameters passed are the team index and `-1`, and the function will be called once for each team.

These indexes can be used to look up details of the clan/team/hedgehog prior to gear creation. Routines to do these lookups will be created as needed.
If you add this hook, the expectation is that you will call SetAmmo appropriately. Any values from `onAmmoStoreInit` are ignored.

=== <tt>onGearWaterSkip(gear)</tt> ===
This function is called when the gear `gear` skips over water.

=== <tt>onScreenResize()</tt> ===
This function is called when you resize the screen. Useful place to put a redraw function for any `vgtHealthTags` you're using.

=== <tt>onAttack()</tt> ===
This function is called when your Hedgehog attacks.

=== <tt>onHJump()</tt> ===
This function is called when you press the high jump key.

=== <tt>onLJump()</tt> ===
This function is called when you press the long jump key.

=== <tt>onPrecise()</tt> ===
This function is called when you press the precise key.

=== <tt>onLeft()</tt> ===
This function is called when you press the left key.

=== <tt>onRight()</tt> ===
This function is called when you press the right key.

=== <tt>onUp()</tt> ===
This function is called when you press the up key.

=== <tt>onDown()</tt> ===
This function is called when you press the down key.

=== <tt>onAttackUp()</tt> ===
This function is called when you release the attack key.

=== <tt>onDownUp()</tt> ===
This function is called when you release the down key.
 
=== <tt>onHogAttack(ammoType)</tt> ===
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.

=== <tt>onLeftUp()</tt> ===
This function is called when you release the left key.

=== <tt>onPreciseUp()</tt> ===
This function is called when you release the precise key.

=== <tt>onRightUp()</tt> ===
This function is called when you release the right key.

=== <tt>onSetWeapon(msgParam)</tt> ===
It is get called when a weapon is selected or switched.

`msgParam` tells you which ammo type was selected.

=== <tt>onSlot(msgParam)</tt> ===
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.).

=== <tt>onSwitch()</tt> ===
This function is called when a hog is switched to another.

=== <tt>onTaunt(msgParam)</tt> ===
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` ||

=== <tt>onTimer(msgParam)</tt> ===
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).

=== <tt>onUpUp()</tt> ===
This function is called when you release the up key.

=== <tt>onUsedAmmo(ammoType)</tt> (0.9.23) ===
Called after a weapon has been used completely, with `ammoType` as the used ammo type.

For example, it is called right after a bazooka is fired, when both shots of a shotgun have been fired, when extra time is used, or when all 4 shots of a portable portal device have been fired. It is also called when using a multi-shot ammo has been aborted by changing the weapon selection mid-way, because this still uses up the ammo.

*Warning:* In 0.9.24 or earlier, you must not manipulate any ammo within this callback, e.g. by using `AddAmmo`. The ammo storage might become garbled otherwise.

=== <tt>onHogHide(gearUid)</tt> ===
This function is called when a hedgehog with the gear ID `gearUid` is hidden (removed from the map).

=== <tt>onHogRestore(gearUid)</tt> ===
This function is called when a hedgehog with the specified gear ID `gearUid` is restored (unhidden).

=== <tt>onSpritePlacement(spriteId, centerX, centerY)</tt> ===
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.

=== <tt>onGirderPlacement(frameIdx, centerX, centerY)</tt> ===
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.

=== <tt>onRubberPlacement(frameIdx, centerX, centerY)</tt> ===
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.

=== <tt>onSpecialPoint(x, y, flags)</tt> ===
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 (as of 0.9.23).
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.

=== </t>onAchievementsDeclaration()</tt> ===
This function is called after the stats for the stats screen (after the game) have been generated. You are supposed to call `DeclareAchievement` here.

== Functions for creating gears ==

=== <tt>!AddGear(x, y, gearType, state, dx, dy, timer)</tt> ===
This creates a new gear at position x,y (measured from top left) of kind `gearType` (see [GearTypes Gear Types]).  Gears are dynamic objects or events in the world that affect the gameplay, including hedgehogs, projectiles, weapons, land objects, active utilities and a few more esoteric things.
The initial velocities are `dx` and `dy`. All arguments are numbers. The function returns the `uid` of the gear created. Gears can have multple states at once: `state` is a bitmask, the flag variables can be found in [States].

Example:

<code language="lua">    local gear = AddGear(0, 0, gtTarget, 0, 0, 0, 0)
    FindPlace(gear, true, 0, LAND_WIDTH)</code>

=== <tt>!AddVisualGear(x, y, visualGearType, state, critical [, layer])</tt> ===
This attempts to create a new visual gear at position x,y (measured from top left) of kind `visualGearType` (see [VisualGearTypes Visual Gear Types]).  Visual gears are decorational objects which are usually used for purely decorational graphical effects.  They have no effect on gameplay.  Visual gears are not the same as gears, but they share some similarities.

The function returns the `uid` of the visual gear created or `nil` if creation failed.  There is no guarantee that a visual gear will spawn.  *IMPORTANT: Do not rely on visual gears to spawn*. *Always* be prepared for this function to return `nil`.

Set `critical` to `true` if the visual gear is crucial to gameplay and must always be spawned when in-game.  Use `false` if it is just an effect or eye-candy, and its creation can be skipped when in fast-forward mode (such as when joining a room).

You can set an optional `layer` to specify which visual gears get drawn on top.

Most visual gears delete themselves eventually.

*NOTE:* Visual gears *must only* be used for decorational/informational/rendering purposes. *Never* use the visual gear's internal state to manipulate anything gameplay-related. Visual gears are not safe for reliable storage and using them as that would lead to strange bugs.

*NOTE:* Since 0.9.25, visual gears will never spawn when Hedgewars is run in a testing mode (i.e. not as the real game), so don't rely for visual gears to spawn even if they're critical.

Example:

<code language="lua">  -- adds an non-critical explosion at position 1000,1000. Returns 0 if it was not created.
    local vgear = AddVisualGear(1000, 1000, vgtExplosion, 0, false) 
</code>

=== <tt>!SpawnHealthCrate(x, y, [, health])</tt> ===
Spawns a health crate at the specified position. If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land). Set `health` for the initial health contained in the health crate. If not set, the default health (`HealthCaseAmount`) is used. Do not use a negative value for `health`.

=== <tt>!SpawnSupplyCrate(x, y, ammoType [, amount])</tt> (0.9.24) ===
Spawns an ammo or utility crate at the specified position with the given ammo type and an optional amount (default: 1). The crate type is chosen automatically based on the ammo type.
Otherwise, this function behaves like `SpawnAmmoCrate`.

=== <tt>!SpawnAmmoCrate(x, y, ammoType [, amount])</tt> ===
Spawns an ammo crate at the specified position with content of `ammoType` (see [AmmoTypes Ammo Types]). Any `ammoType` is permitted, an ammo crate is spawned even if the ammo is normally defined as an utility.
If `ammoType` is set to `amNothing`, a random weapon (out of the available weapons from the weapon scheme) will be selected. If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land). The `amount` parameter specifies the amount of ammo contained in the crate. If `amount` is `nil` or `0`, the value set by `SetAmmo` is used, or if `SetAmmo` has not been used, it falls back to the weapon scheme's value. If `amount` is equal to or greater than `AMMO_INFINITE`, the amount is infinite.

Note that in Lua missions, the default number of ammo in crates is 0, so it has to be set to at least 1 with `SetAmmo` first, see the example:

Example:

<code language="lua">    SetAmmo(amGrenade, 0, 0, 0, 1) -- grenade ammo crates now contain 1 grenade each
    SpawnAmmoCrate(0, 0, amGrenade) -- spawn grenade ammo crate at random position</code>

=== <tt>!SpawnUtilityCrate(x, y, ammoType [, amount])</tt> ===
Spawns an utility crate with some ammo at the specified position. The function behaves almost like `SpawnAmmoCrate`, the differences are 1) the crate looks different and 2) if `ammoType` is set to `amNothing`, a random utility out of the set of available utilities from the weapon scheme is chosen as content.

Example:

<code language="lua">    SetAmmo(amLaserSight, 0, 0, 0, 1)
    SpawnUtilityCrate(0, 0, amLaserSight)</code>

=== <tt>!SpawnFakeAmmoCrate(x, y, explode, poison) </tt> ===
Spawns a crate at the specified coordinates which looks exactly like a real ammo crate but contains not any ammo. It can be use useful for scripted events or to create a trap. If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land).
`explode` and `poison` are booleans.
If `explode` is `true`, the crate will explode when collected.
If `poison` is `true`, the collector will be poisoned.

Example:

<code language="lua">SpawnFakeAmmoCrate(500, 432, false, false) -- Spawns a fake ammo crate at the coordinates (500, 434) without explosion and poison.
</code>

=== <tt>!SpawnFakeHealthCrate(x, y, explode, poison) </tt> ===
Same as `SpawnFakeAmmoCrate`, except the crate will look like a health crate.

=== <tt>!SpawnFakeUtilityCrate(x, y, explode, poison) </tt> ===
Same as `SpawnFakeAmmoCrate`, except the crate will look like an utility crate.

=== <tt>!AddHog(hogname, botlevel, health, hat)</tt> ===
Adds a new hedgehog for current team (last created one with the `AddTeam` function), with a bot level, an initial health and a hat.

`botlevel` ranges from `0` to `5`, where `0` denotes a human player and `1` to `5` denote the skill level of a bot, where `1` is strongest and `5` is the weakest. Note that this is the reverse order of how the bot level is displayed in the game. Note that mixing human-controlled and computer-controlled hedgehogs in the same team is not permitted, but it is permitted to use different computer difficulty levels in the same team.

*Warning*: This only works in singleplayer mode (e.g. missions). Also, Hedgewars only supports up to 48 hedgehogs in a game. If you add more hedgehogs or call this function in multiplayer mode, Hedgewars might fail.

Example:

<code language="lua">    local player = AddHog("HH 1", 0, 100, "NoHat") -- botlevel 0 means human player
    SetGearPosition(player, 1500, 1000)</code>
== Functions to get gear properties ==

=== <tt>!GetGearType(gearUid)</tt> ===
This function returns the [GearTypes gear type] for the specified gear, if it exists.  If it doesn't exist, `nil` is returned.

=== <tt>!GetVisualGearType(vgUid)</tt> (0.9.23) ===
This function returns the [VisualGearTypes visual gear type] for the specified visual gear, if it exists.  If it doesn't exist, `nil` is returned.

=== <tt>!GetGearPosition(gearUid)</tt> ===
Returns x,y coordinates for the specified gear. Not to be confused with `GetGearPos`.

=== <tt>GetGearCollisionMask(gearUid)</tt> ===
Returns the current collision mask of the given gear. See `SetGearCollisionMask` for an explanation of the mask.

=== <tt>!GetGearRadius(gearUid)</tt> ===
Returns the `Radius` value for the specified gear. For most [GearTypes gear types] for “projectile” gears (like `gtShell` or `gtGrenade`), the radius refers to the gear's collision radius. This is an invisible circle around the center of the gear which is used for the collision checks. For a few gear types, its radius means something different, see [GearTypes] for a full list.

To set the `Radius` value, use `SetGearValues`.

=== <tt>!GetGearVelocity(gearUid)</tt> ===
Returns a tuple of dx,dy values for the specified gear.

=== <tt>!GetFlightTime(gearUid)</tt> ===
Returns the `FlightTime` of the specified gear. The `FlightTime` is a gear varialbe used to store a general time interval. The precise meaning of the `FlightTime` depends on the gear type.

For example: The `FlightTime` of a hedgehog (`gtHedgehog`) is the time since they last have stood on solid ground. For most projectile gear types (i.e. `gtShell`), it stores the time after it has been launched.

=== <tt>!GetGearElasticity(gearUid) </tt> ===
Returns the elasticity of the specified gear. The elasticity normally determines how strong the gear will bounce after collisions, where higher elasticity is for stronger bounces.

This is also useful for determining if a hog is on a rope or not. If a hog is attached to a rope, or is busy firing one, the elasticity of the rope will be a non-zero number.

=== <tt>!GetGearFriction(gearUid) </tt> ===
Returns the friction of the specified gear. The friction normally determines how well the gear will slide on terrain. Higher values are for increased sliding properties.

=== <tt>!GetHogClan(gearUid)</tt> ===
Returns the clan ID of the specified hedgehog gear.

=== <tt>!GetHogTeamName(gearUid)</tt> ===
Returns the name of the specified gear’s team. `gearUid` can be a hedgehog or a grave.

=== <tt>!GetHogName(gearUid)</tt> ===
Returns the name of the specified hedgehog gear.

=== <tt>!IsHogHidden(gearUid)</tt> (0.9.25) ===
Returns true if hedgehog gear is hidden (e.g. via `HideHog` or the !TimeBox), false if it isn't, nil if that hedgehog never existed.

=== <tt>!GetEffect(gearUid, effect)</tt> ===
Returns the state of given effect for the given hedgehog gear.

See `SetEffect` for further details.

=== <tt>!GetHogHat(gearUid)</tt> ===
Returns the hat of the specified hedgehog gear.

=== <tt>!GetHogFlag(gearUid)</tt> ===
Returns the name of the flag of the team of the specified hedgehog gear.

=== <tt>!GetHogFort(gearUid)</tt> (0.9.23) ===
Returns the name of the fort of the team of the specified hedgehog gear.

=== <tt>!GetHogGrave(gearUid)</tt> ===
Returns the name of the grave of the team of the specified hedgehog gear.

=== <tt>!GetHogVoicepack(gearUid)</tt> ===
Returns the name of the voicepack of the team of the specified hedgehog gear.

=== <tt>!GetAmmoCount(gearUid, ammoType)</tt> ===
Returns the ammo count of the specified ammo type for the specified hedgehog gear. If infinite, returns `AMMO_INFINITE`.

=== <tt>!GetAmmoTimer(gearUid, ammoType)</tt> (0.9.25) ===
Returns the currently configured ammo timer (in milliseconds) for the given hedgehog gear and specified ammo type. This is the timer which is set by the player by using the timer keys (1-5). For ammo types for which the timer cannot be changed, `nil` is returned.

Example:
<code lang="lua">GetAmmoTimer(CurrentHedgehog, amGrenade)
-- May return 1000, 2000, 3000, 4000 or 5000</code>

=== <tt>!IsHogLocal(gearUid)</tt> (0.9.23) ===
Returns `true` if the specified hedgehog gear is controlled by a human player on the computer on which Hedgewars runs on (i.e. not over a computer over the network). Also returns `true` if the hog is a member of any of the local clans. Returns `false` otherwise. Returns `nil` if `gearUid` is invalid.

This is perfect to hide certain captions like weapon messages from enemy eyes.

=== <tt>!GetGearTarget(gearUid, x, y) </tt> ===
Returns the x and y coordinate of target-based weapons/utilities. 
<b>Note:</b>: This can’t be used in `onGearAdd()` but must be called after gear creation. 

=== <tt>GetX(gearUid)</tt> ===
Returns x coordinate of the gear.

=== <tt>GetY(gearUid)</tt> ===
Returns y coordinate of the gear.

=== <tt>!GetState(gearUid)</tt> ===
Returns the state of the gear. The gear state is a bitmask which is built out of the variables as shown in [States].

This function is usually used in combination with `band` to extract the truth value of a single flag. It is also used together with `SetState` and `bor` in order to activate a single flag.

Examples:
<code language="lua">
local state = GetState(gear)
--[[ Stores the full raw bitmask of gear in state. Usually
useless on its own. ]]
</code>

<code language="lua">
isDrowning = band(GetState(CurrentHedgehog),gstDrowning) ~= 0
--[[ GetState(CurrentHedgehog) returns the state bitmask of
CurrentHedgehog, gstDrowning is a bitmask where only the
“drowning” bit is set. band does a bitwise AND on both, if
it returns a non-zero value, the hedgehog is drowning.]]
</code>

<code language="lua">
SetState(CurrentHedgehog, bor(GetState(CurrentHedgehog), gstInvisible))
--[[ first the state bitmask of CurrentHedgehog is bitwise ORed with
the gstInvisible flag, thus making the bit responsible for
invisiblity to become 1. Then the new bitmask is applied to
CurrentHedgehog, thus making it invisible.]]
</code>


=== <tt>!GetGearMessage(gearUid)</tt> ===
Returns the message of the gear. This is a bitmask built out of flags seen in [GearMessages].

=== <tt>!GetTag(gearUid)</tt> ===
Returns the tag of the specified gear (by `gearUid`). 

The `Tag` of a gear is just another arbitrary variable to hold the gear's state. The meaning of a tag depends on the gear type. For example, for `gtBall` gears, it specifies the ball color, for `gtAirAttack` gears (airplane) it specifies the direction of the plane, etc. See [GearTypes] for a full list. The returned value will be an integer.

Note that the word “tag” here does _not_ refer to the name and health tags you see above hedgehogs, this is something different. 

<code language="lua">
-- This adds a ball (the one from the ballgun) at (123, 456):
ball = AddGear(123, 456, gtBall, 0, 0, 0, 0)
-- The tag of a ball defines its color. It will automatically chosen at random when created.
colorTag = GetTag(ball)
-- Now colorTag stores the tag of ball (in this case a number denoting its color)
</code>

The meaning of tags are described in [GearTypes].

=== <tt>!GetFollowGear()</tt> ===
Returns the uid of the gear that is currently being followed.

=== <tt>!GetTimer(gearUid)</tt> ===
Returns the timer of the gear. This is for example the time it takes for watermelon, mine, etc. to explode. This is also the time used to specify the blowtorch or RC plane time. See [GearTypes] for a full list.

=== <tt>!GetHealth(gearUid)</tt> ===
Returns the health of the gear. Depending on the gear type, the gear's “health” can also refer to other things, see [GearTypes] for a full list.

=== <tt>!GetHogLevel(gearUid)</tt> ===
Returns the bot level ranging from `0` to `5`. `1` is the strongest bot level and `5` is the weakest one (this is the reverse of what players see). `0` is for human player.

=== <tt>!GetGearPos(gearUid)</tt> ===
Get the `Pos` value of the specified gear. `Pos` is just another arbitrary value to hold the state of the gear, such as `Tag` and `Health`, the meaning depends on the gear type. See [GearTypes] for the conrete meaning of a gear's `Pos` value. 

*Important*: Pos is *not* related to the gear's position, use `GetGearPosition` for that.

=== <tt>!GetGearValues(gearUid)</tt> ===
This returns a bunch of values associated with the gear, their meaning is often depending on the gear type and many values might be unused for certain gear types.

This is returned (all variables are integers):

`Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom`

A rough description of some of the parameters:

 * `Radius`: Effect or collision radius, most of the time
 * `ImpactSound`: Sound it makes on a collision (see [Sounds])
 * `Tint`: Used by some gear types to determine its colorization. The color is in RGBA format.
 * `Boom`: Used by most gears to determine the damage dealt.

Example:
<code language="lua">
-- Get all values in a single line of code:
local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom = GetGearValues(myGear)
</code>

=== <tt>!GetVisualGearValues(vgUid)</tt> ===
This returns the typically set visual gear values for the specified visual gear `vgUid`, useful if manipulating things like smoke, bubbles or circles. On success, it returns the following values:

`X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint`

 * `X`, `Y`: typically position
 * `dX`, `dY`: typically speed
 * `Angle` is usually the rotation angle
 * `Frame` is typically the animation frame
 * `FrameTicks` is usually an animation counter
 * `State` can have a variety of values, but is typically bit packed
 * `Timer` is usually the gear lifetime
 * `Tint` is the RGBA color

If the visual gear does not exist, `nil` is returned. Always check the result for `nil` before you plug in the values anywhere.

Most visual gears require little to no modification of parameters.

Example:

<code language="lua">-- Return visual gear values
local X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint = GetVisualGearValues(vgUid)
</code>

== Functions to modify gears ==

=== <tt>!HideHog(gearUid)</tt> ===
Removes a hedgehog from the map. The hidden hedgehog can be restored with `RestoreHog(gearUid)`. Since 0.9.23, returns `true` on success and `false` on failure (if gear does not exist / hog is already hidden).

Example: 

<code language="lua">    gear = AddGear(...)
     HideHog(gear) -- Hide the newly created gear.</code>

=== <tt>!RestoreHog(gearUid)</tt> ===
Restores a previously hidden hedgehog.  Nothing happens if the hedgehog does not exist or is not hidden.

Example: 

<code language="lua">    gear = AddGear(...)
     HideHog(gear) -- Hide the newly created gear.
     RestoreHog(gear) -- Restore the newly hidden gear.</code>

=== <tt>!DeleteGear(gearUid)</tt> ===
Deletes a gear.  If the specified gear did not exist, nothing happens.

Example:

<code language="lua">    gear = AddGear(...)
    DeleteGear(gear) -- Delete the newly created gear.</code>

=== <tt>!DeleteVisualGear(vgUid)</tt> ===
Deletes a visual gear.  If it does not exist, nothing happens. 

Note, most visual gears delete themselves after a while.



Example:

<code language="lua">    vgear = AddVisualGear(...)
    DeleteVisualGear(vgear) -- Delete the newly created visual gear.</code>

=== <tt>!SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom)</tt> ===
Sets various gear value for the specified gear (`gearUid`). The meaining of each value often depends on the gear type. See the documentation on !GetGearValues for a brief description of the gear values. If `gearUid` is invalid or the gear does not exist, nothing happens.

Set `nil` for each value you do not want to change.

Example:
<code language="lua">
-- Paints all RC planes into a white color
function onGearAdd(gear)
    if GetGearType(gear) == gtRCPlane then
         SetGearValues(gear, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xFFFFFFFF)
    end
end
</code>

=== <tt>!SetVisualGearValues(vgUid, X, Y, dX, dY, Angle, Frame, !FrameTicks, State, Timer, Tint)</tt> ===
This allows manipulation of the internal state of the visual gear `vgUid`. If `vgUid` is invalid or the `vgUid` does not refer to an existing visual gear, the function does nothing. Thus, you can safely call this function even if you are not sure if the visual gear actually exists.

All visual gear values are numbers. Each visual gear may be using these parameters differently, but the *usual* meaning of these is the following:

 * `X`, `Y`: Position
 * `dX`, `dY`: Speed along the X and Y axis
 * `Angle`: Current rotation
 * `Frame`: Image frame, if using a sprite sheet
 * `FrameTicks`: ???
 * `State`: Helper value to save some internal state
 * `Timer`: Time in milliseconds until it expires
 * `Tint`: RGBA color

Some visual gears interpret these values differently, just like normal gears. See [VisualGearTypes] for details.  Also, most visual gears are not using all possible values, while some values are just ignored.

Note that most visual gears require little to no modification of their values.

*NOTE:* *Never* use the visual gear's internal state to manipulate/store anything gameplay-related.  Visual gears are not safe for reliable storage and using them as that would lead to strange bugs.

Example 1:

<code language="lua">  -- set a circle to position 1000,1000 pulsing from opacity 20 to 200 (8%-78%), radius of 50, 3px thickness, bright red.
    SetVisualGearValues(circleUid, 1000,1000, 20, 200, 0, 0, 100, 50, 3, 0xff0000ff)</code>

Only the first argument is required. Everything else is optional. Any such argument which is declared as `nil` will not overwrite the corresponding value of the visual gear.

Example 2:

<code language="lua">  -- set a visual gear to position 1000,1000
    SetVisualGearValues(circleUid, 1000, 1000)</code>
<code language="lua">  -- set the tint of a visual gear to bright red.
    SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)</code>


=== <tt>!FindPlace(gearUid, fall, left, right[, tryHarder])</tt> ===
Finds a place for the specified gear between x=`left` and x=`right` and places it there. `tryHarder` is optional, setting it to `true`/`false` will determine whether the engine attempts to make additional passes, even attempting to place gears on top of each other.

Example:

<code language="lua">    gear = AddGear(...)
    FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code>
=== <tt>HogSay(gearUid, text, manner [,vgState])</tt> ===
Makes the specified gear say, think, or shout some text in a comic-style speech or thought bubble. `gearUid` is _not_ limited to hedgehogs, altough the function name suggests otherwise.

The `manner` parameter specifies the type of the bubble and can have one of these values:

|| *Value of `manner`* || *Looks* ||
|| `SAY_THINK` || Thought bubble ||
|| `SAY_SAY` || Speech bubble ||
|| `SAY_SHOUT` || Exclamatory bubble (denotes shouting) ||

There is a optional 4th parameter `vgState`, it defines wheather the speechbubble is drawn fully opaque or semi-transparent. The value `0` is the default value.

|| *Value of `vgState`* || *Effect* ||
|| `0` || If the specified gear is a hedgehog, and it’s the turn of the hedgehog’s team, the bubble is drawn fully opaque.<br>If the gear is a hedgehog, and it’s another team’s turn, the bubble is drawn translucent.<br>If the gear is not a hedgehog, the bubble is drawn fully opaque. ||
|| `1` || The bubble is drawn translucent. ||
|| `2` || The bubble is drawn fully opaque. ||

Examples:

<code language="lua">HogSay(CurrentHedgehog, "I wonder what to do …", SAY_THINK) -- thought bubble with text “I wonder what to do …”</code>
<code language="lua">HogSay(CurrentHedgehog, "I'm hungry.", SAY_SAY) -- speech bubble with text “I’m hungry.”</code>
<code language="lua">HogSay(CurrentHedgehog, "I smell CAKE!", SAY_SHOUT) -- exclamatory bubble with text “I smell CAKE!”</code>
=== <tt>!HogTurnLeft(gearUid, boolean)</tt> ===
Faces the specified hog left or right.

Example:

<code language="lua">    HogTurnLeft(CurrentHedgehog, true) -- turns CurrentHedgehog left 
    HogTurnLeft(CurrentHedgehog, false) -- turns CurrentHedgehog right</code>
=== <tt>!SetGearPosition(gearUid, x, y)</tt> ===
Places the specified gear exactly at the position (`x`,`y`). Not to be confused with `SetGearPos`.

=== <tt>SetGearCollisionMask(gearUid, mask)</tt> ===
Set the collision mask of the given gear with `gearUid`.
The collision mask defines with which gears and terrain types the gear can collide.

`mask` is a number between `0x0000` and `0xFFFF` and used as a bitfield, which means you can combine these flags with `bor`. These are the available flags:

|| *Identifier* || *Collision with …* ||
|| `lfLandMask` || Terrain ||
|| `lfCurHogCrate` || Current hedgehog, and crates ||
|| `lfHHMask` || Any hedgehogs ||
|| `lfNotHHObjMask` || Objects, not hogs (e.g. mines, explosives) ||
|| `lfAllObjMask` || Hedgehogs and objects ||

Beware, the collision mask is often set by the engine as well.

Examples:
<code language="lua">SetGearCollisionMask(gear, bnot(lfCurHogCrate))
-- Ignore collision with current hedgehog</code>

<code language="lua">SetGearCollisionMask(gear, 0xFFFF)
-- Collide with everything</code>

<code language="lua">SetGearCollisionMask(gear, lfAllObjMask)
-- Collide with hedgehogs and objects</code>

<code language="lua">SetGearCollisionMask(gear, 0x0000)
-- Collide with nothing</code>

There are actual more flags availbable, but they are not as useful for use in Lua and their constants have not been exposed to Lua. You can find the full range of flags in the engine source code (in Pascal):

[https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uConsts.pas#l112]

=== <tt>!SetGearVelocity(gearUid, dx, dy)</tt> ===
Gives the specified gear the velocity of `dx`, `dy`.

=== <tt>!SetFlightTime(gearUid, flighttime)</tt> ===
Sets the `FlightTime` of the given gear to `flighttime`. The meaning of `FlightTime` is explained in the section `GetFlightTime`.

=== <tt>!SetGearElasticity(gearUid, Elasticity) </tt> ===
Sets the elasticity of the specified gear. For most gears, the elasticity determines how strong the gear will bounce after collisions, where higher elasticity is for stronger bounces. Recommended are values between `0` and `9999`.

=== <tt>!SetGearFriction(gearUid, Friction) </tt> ===
Sets the friction of the specified gear. The friction normally determines how well the gear will slide on terrain. Higher values are for increased sliding properties. `0` is for no sliding whatsoever, where `9999` is for very long slides, greater values are not recommended.

=== <tt>!SetHealth(gearUid, health)</tt> ===
Sets the health of the specified gear. The “health” of a gear can refer to many things, depending on the gear type.

*Hint*: If you like to increase the health of a hedgehog with nice visual effects, consider using `HealHog` instead.

Use cases:

  * Setting the health of a hedgehog (`gtHedgehog`) to 99
  * Starting the RC Plane (`gtRCPlane`) with 10 bombs
  * Starting flying saucer (`gtJetpack`) with only 50% fuel
  * Setting all the mines (`gtMine`) to duds
  * And more!

See [GearTypes] for a full description.

<code language="lua">    function onGearAdd(gear)
       if (GetGearType(gear) == gtHedgehog) then
            -- Set hedgehog health to 99
            SetHealth(gear, 99)
       end
       if (GetGearType(gear) == gtRCPlaane) then
            -- Give the plane 10 bombs
            SetHealth(gear, 10)
       end
       if (GetGearType(gear) == gtJetpack) then
            -- Set fuel to 50% only
            SetHealth(gear, 1000)
       end
       if (GetGearType(gear) == gtMine) then
            -- Turn mine into dud
            SetHealth(gear, 0)
       end
    end</code>

=== <tt>HealHog(gearUid, healthBoost[, showMessage[, tint]])</tt> (0.9.24) ===
Convenience function to increase the health of a hedgehog with default visual effects.

Specifically, this increases the health of the hedgehog gear with the given ID `gearUid` by `healthBoost`, displays some healing particles at the hedgehog and shows the health increae as a message. This is similar to the behavour after taking a health crate, or getting a health boost from vampirism.

If `showMessage` is false, no message is shown. With `tint` you can set the RGBA color of the particles (default: `0x00FF00FF`).

This function does not affect the poison state, however (see `SetEffect`).

=== <tt>!SetEffect(gearUid, effect, effectState)</tt> ===
Sets the state for one of the effects <tt>heInvulnerable, heResurrectable, hePoisoned, heResurrected, heFrozen</tt> for the specified hedgehog gear.
A value of 0 usually means the effect is disabled, values other than that indicate that it is enabled and in some cases specify e.g. the remaining time of that effect.

|| *`effect`* || *Description* || *`effectState`* ||
|| `heInvulnerable` || Wether hog is invulnerable || Any non-zero value turns on invulnerability. `0` turns it off. ||
|| `hePoisoned` || Poison damage, damages hog each turn. || Amount of damage per turn. Use `0` to disable poisoning. ||
|| `heResurrectable` || Whether to resurrect the hog on death || With a non-zero value, the hedgehog will be resurrected and teleported to a random location on death. `0` disables this. ||
|| `heResurrected` || Whether the hedgehog has been resurrected once. This is only a subtle graphical effect. || With a non-zero value, the hedgehog was resurrected, `0` otherwise. ||
|| `heFrozen` || Freeze level. Frozen hedgehogs skip turn, are heavy and take half damage || The hog is considered frozen if the value is `256` or higher, otherwise not. A number of `256` or higher denotes “how frozen” the hedgehog is, i.e. how long it takes to melt. The freezer sets this to `199999` initially. The value will be reduced by `50000` each round. Being hit by a flame reduces this number by `1000`. The values `0` to `255` are used for the freeze/melt animations. ||
|| `heArtillery` || If enabled, the hedgehog can't walk (since 0.9.24). || `0` = disabled. `1` = permanently enabled. `2` = temporarily enabled (used by sniper rifle between shots) ||

Example (sets all bots poisoned with poison damage of 1):

<code language="lua">    function onGearAdd(gear)
        if (GetGearType(gear) == gtHedgehog) and (GetHogLevel(gear) > 0) then
            SetEffect(gear, hePoisoned, 1)
        end
    end</code>

=== <tt>CopyPV(gearUid, gearUid)</tt> ===
This sets the position and velocity of the second gear to the first one.

=== <tt>!FollowGear(gearUid)</tt> ===
Makes the game client follow the specifiec gear (if it exists). Does not work for visual gears.

=== <tt>!SetHogName(gearUid, name)</tt> ===
Sets the name of the specified hedgehog gear.

=== <tt>!SetHogTeamName(gearUid, name)</tt> ===
Sets the team name of the specified gear. The gear can be a hedgehog or grave.

=== <tt>!SetHogHat(gearUid, hat)</tt> ===
Sets the hat of the specified hedgehog gear.

=== <tt>!SetGearTarget(gearUid, x, y)</tt> ===
Sets the x and y coordinate of target-based weapons/utilities.
*Note*: This can’t be used in onGearAdd() but must be called after gear creation.

=== <tt>!SetState(gearUid, state)</tt> ===
Sets the state of the specified gear to the specified `state`. This is a bitmask made out of the variables as seen in [States].

This function is often used together with `GetState` and the bitmask utility functions `band` and `bnot` in order to manipulate a single flag.

Examples:
<code language="lua">
SetState(CurrentHedgehog, bor(GetState(CurrentHedgehog), gstInvisible))
--[[ first the state bitmask of CurrentHedgehog is bitwise ORed with
the gstInvisible flag, thus making the bit responsible for
invisiblity to become 1. Then the new bitmask is applied to
CurrentHedgehog, thus making it invisible. ]]
</code>

<code language="lua">
SetState(CurrentHedgehog, band(GetState(CurrentHedgehog), bnot(gstInvisible)))
--[[ The reverse of the above: This function toggles CurrentHedgehog’s
gstInvisible flag off, thus making it visible again. ]]
</code>

=== <tt>!SetGearMessage(gearUid, message)</tt> ===
Sets the gear messages of the specified gear. `message` is a bitmask built out of flags seen in [GearMessages].

=== <tt>!SetTag(gearUid, tag)</tt> ===
Sets the `Tag` value of the specified gear (by `gearUid`). The `Tag` value of a gear is simply an extra variable to modify misc. things. The meaning of a tag depends on the gear type. For example, for `gtBall` gears, it specifies the ball color, for `gtAirAttack` gears (airplane) it specifies the direction of the plane, etc. See [GearTypes] for a full list. `tag` has to be an integer.

Note that the word “tag” here does _not_ refer to the name and health tags you see above hedgehogs, this is something different. 

<code language="lua">
-- This adds a ball (the one from the ballgun) at (123, 456):
ball = AddGear(123, 456, gtBall, 0, 0, 0, 0)
-- This sets the tag of the gear. For gtBall, the tag specified the color. “8” is the color white.
SetTag(ball, 8) -- 
</code>

The meaning of tags are described in [GearTypes].

=== <tt>!SetTimer(gearUid, timer)</tt> ===
Sets the timer of the specified gear. Also see `GetTimer`.

=== <tt>!SetHogLevel(gearUid, level)</tt> ===
Sets the bot level from 0 to 5. `1` is the strongest bot level and `5` is the weakest one (this is the reverse of what players see). `0` means human player.

=== <tt>SetGearAIHints(gearUid, aiHint)</tt> ===
Set some behaviour hints for computer-controlled hedgehogs for any given gear with `gearUid`.

Set `aiHint` to either of:

 * `aihUsualProcessing`: AI hogs treat this gear the usual way. This is the default.
 * `aihDoesntMatter`: AI hogs don't bother attacking this gear intentionally.

Example:

<code language="lua">
SetGearAIHints(uselessHog, aihDoesntMatter)
-- This makes AI hogs stop caring about attacking uselessHog</code>

=== <tt>!SetGearPos(gearUid, value)</tt> ===
Sets the `Pos` value (not the position!) of the specified gear to specified value. See `GetGearPos` for more information.

== Gameplay functions ==

=== `GameFlags` functions ===

==== <tt>!ClearGameFlags()</tt> ====
Disables *all* !GameFlags.

==== <tt>!DisableGameFlags(gameflag, ...)</tt> ====
Disables the listed !GameFlags, without changing the status of other !GameFlags.

==== <tt>!EnableGameFlags(gameflag, ...)</tt> ====
Enables the listed !GameFlags, without changing the status of other !GameFlags. In missions, no !GameFlags are set initially.

==== <tt>!GetGameFlag(gameflag)</tt> ====
Returns `true` if the specified gameflag is enabled, otherwise `false`.

=== Turns ===
==== <tt>SkipTurn()</tt> (0.9.24) ====
Forces the current hedgehog to skip its turn.

==== <tt>EndTurn([noTaunts])</tt> (0.9.23) ====
Ends the current turn immediately.

Normally, a “Coward” taunt may be played and an announcer message may be shown (depending on the situation). Set the optional `noTaunts` parameter to `true` to force the engine to never play a taunt or show a message. `noTaunts` is `false` by default.

==== <tt>Retreat(time [, respectGetAwayTimeFactor)</tt> (0.9.25) ====
Forces the current turn into the retreating phase, as if the hog made an attack. That is, the current hedgehog is unable to attack or select a weapon, only movement is possible until the retreat time is up.

The retreat time must be set with `time` in milliseconds. By default, this time is automatically multiplied with get-away time percentage from the game scheme for seamless integration with schemes. If you want to ignore the game scheme for some reason and set the retreat time no matter what, set `respectGetAwayTimeFactor` to `false`.

If the current hedgehog was busy doing an attack, the attack is aborted, no shot is made. If this function is called in the ready phase of af a turn, the ready phase continues normally, but the turn will begin in the retreat phase instead.

Note: If you want the turn to end instantly, it is recommended to use `EndTurn` instead.

==== <tt>!SetTurnTimeLeft(newTurnTimeLeft)</tt> (0.9.25) ====
Set the remaining turn time in milliseconds. The current remaining turn time can be read from the variable `TurnTimeLeft`.

==== <tt>!SetReadyTimeLeft(newReadyTimeLeft)</tt> (0.9.25) ====
Set the remaining ready time in milliseconds. This function should only be called in onNewTurn. The current remaining ready time can be read from the variable `ReadyTimeLeft`.

==== <tt>!EndGame()</tt> ====
Makes the game end.

=== Environment ===
==== <tt>!SetGravity(percent)</tt> ====
Changes the current gravity of the game in percent (relative to default, integer value).
Setting it to 100 will set gravity to default gravity of hedgewars, 200 will double it, etc.

==== <tt>!GetGravity()</tt> ====
Returns the current gravity in percent.

==== <tt>!SetWaterLine(waterline)</tt> ====
Sets the water level (`WaterLine`) to the specified y-coordinate.

==== <tt>!SetWind(windSpeed)</tt> ====
Sets the current wind in the range of -100 to 100 inclusive. Use together with `gfDisableWind` for full control.

==== <tt>!GetWind()</tt> (0.9.24) ====
Returns current wind, expressed as a floating point number between -100 to 100 inclusive. Note there may be rounding errors.

==== <tt>!SetMaxBuildDistance(distInPx)</tt> ====
Sets the maximum building distance for of girders and rubber bands in pixels to `distInPx`. If `distInPx` is `0`, the limit is disabled. If called without arguments, the distance will be reset to the default value.

==== <tt>Explode(x, y, radius[, options])</tt> (0.9.24) ====
Cause an explosion or erase land, push or damage gears.

By default, an explosion destroys a circular piece of land and damages and pushes gears in its radius.

The explosion occours at coordinates `(x, y)` with the given `radius`. Assuming 100% damage, the explosion damage at the center equals the explosion radius.

The explosion will also have a visual effect (by spawning an explosion visual gear), unless the radius is very small.

`options` is a bitmask which can be used to tweak how the explosion behaves:

|| *Flag* || *Meaning* ||
|| `EXPLAutoSound` || Plays an appropriate sound ||
|| `EXPLNoDamage` || Deal no damage to gears ||
|| `EXPLDoNotTouchHH` || Do not push hedgehogs ||
|| `EXPLDoNotTouchAny` || Do not push any gears ||
|| `EXPLDontDraw` || Do not destroy land ||
|| `EXPLForceDraw` || Destroy land, even if `gfSolidLand` is active ||
|| `EXPLNoGfx` || Do not show an explosion animation and do not shake the screen ||
|| `EXPLPoisoned` || Poison all hedgehogs in explosion radius ||

`options` is assumed to be `EXPLAutoSound` by default. Set `options` to 0 to disable all flags.

Examples:
<code language="lua">
-- Simple explosion at (100, 50) with radius 50
Explode(100, 50, 50)

-- Simple explosion without sound
Explode(100, 50, 50, 0)

-- Fake explosion which only pushes gears but deals no damage to gears and terrain
Explode(500, 1000, 50, EXPLAutoSound + EXPLNoDamage + EXPLDontDraw)

-- Erase a circle of land without side effects
Explode(500, 100, 100, EXPLNoDamage + EXPLDoNotTouchAny + EXPLNoGfx)
</code>

=== Ammo ===
==== <tt>!SetAmmo(ammoType, count, probability, delay, numberInCrate)</tt> ====
This updates the settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This must only be used in the `onAmmoStoreInit()` event handler. In other places, this function will not work.

In Lua missions, for *all* ammo types, the ammo count, probability, delay and number in crates is set to 0 initially. Note: This also includes skip!

Parameters:

 * `ammoType`: Ammo type to be set
 * `count`: Initial ammo count. 9 = infinite
 * `probability`: Crate probability. Max. value is 9. 0 = never
 * `delay`: Number of rounds this ammo is delayed
 * `numberInCrate`: Amount of ammo in a crate

Example:

<code language="lua">    SetAmmo(amShotgun, 9, 0, 0, 0) -- unlimited amount of shotgun ammo for players
    SetAmmo(amGrenade, 0, 0, 0, 3) -- crates should contain always three grenade
    SetAmmo(amSkip, 9, 0, 0, 0) -- enable skip</code>

Hint: It is recommended to always enable skip in missions. Only in exceptional circumstances you should choose to not enable skip.

==== <tt>!GetAmmo(ammoType)</tt> ====
Returns ammo settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This function is analogue to `SetAmmo`.

This function returns four numbers, in this order: initial ammo count, probability, delay and number in crate. These values correspond to the parameters 2-5 provided in `SetAmmo` and have the same meaning.

Example:

<code language="lua">count, prob, delay, numberInCrate = GetAmmo(amGrenade) -- Get ammo settings of amGrenade</code>

==== <tt>!SetAmmoDelay(ammoType, delay)</tt> ====
Changes the delay of a specified [AmmoTypes Ammo Type].

==== <tt>!SetAmmoTexts(ammoType, name, caption, description [, showExtra])</tt> (0.9.23) ====
Allows you to overwrite the displayed name and tooltip descriptions of a given ammo type. This function must only be called either inside the `onGameStart` callback function, or after the engine has called `onGameStart`.

 * `ammoType`: The ammo type to set the text for
 * `name`: Name of the ammo type (e.g. “Grenade” for `amGrenade`), affects both name in ammo menu and in the “ticker” message on the screen top.
 * `caption`: The second line in the ammo menu (below the title). E.g. “Timed grenade” for `amGrenade`.
 * `description`: Description text in ammo menu, below the caption.
 * `showExtra`: If `false` the special “extra” text line like “Weapon is not yet available” or “Weapon does not end turn” will be suppressed

`title`, `caption`, `description` can be `nil`, in which case they will be reverted to the engine default value. This function returns `nil`.

Example:
<code language="lua">
-- Overwrites bazooka name and description
SetAmmoTexts(amBazooka, "Spoon Missile", "Crazy weapon", "This crazy weapon looks like a spoon and explodes on impact.|Attack: Hold to launch with more power")</code>

==== <tt>!SetAmmoDescriptionAppendix(ammoType, descAppend)</tt> (0.9.23) ====
Will set a string `descAppend` to be appended below the “core” description (ammo tooltip) of the specified `ammoType`, without changing the ordinary description.
Note that calling this function always sets the complete appended string, you can't use this function to append multiple texts in row.

This function is recommended if you have tweaked an existing ammo type only a little and want to keep the original description intact as much as possible.

Example:
<code language="lua">
-- Appends a text to the ammo tooltip of the bazooka but leaves name and main description intact
SetAmmoTexts(amBazooka, "This weapon deals double the damage than usually.")</code>

==== <tt>!AddAmmo(gearUid, ammoType, ammoCount)</tt> ====
Adds `ammoType` to the specified gear. The amount added is determined by the arguments passed via `SetAmmo()` in the `onAmmoStoreInit()` event handler. `ammoCount` is an optional parameter. If this is set, the ammo will **not** be added, but instead set to `ammoCount`. A value of `0` will remove the weapon, a value of `AMMO_INFINITE` will give infinite ammo.

==== <tt>!GetAmmoName(ammoType [, ignoreOverwrite ])</tt> (0.9.23) ====
Returns the localized name for the specified `ammoType`, taking an ammo name overwritten by `SetAmmoTexts` into account. If `ignoreOverwrite` is `true`, this function will always return the original ammo name of the weapon and ignores names which may have been overwritten by `SetAmmoTexts`.

=== Map ===
==== <tt>!MapHasBorder()</tt> ====
Returns `true`/`false` if the map has a border or not.

==== <tt>!TestRectForObstacle(x1, y1, x2, y2, landOnly)</tt> ====
Checks the rectangle between the given coordinates for possible collisions. Set `landOnly` to `true` if you don’t want to check for collisions with gears (hedgehogs, etc.).

==== <tt>!PlaceGirder(x, y, frameIdx)</tt> ====
Attempts to place a girder with centre points `x`, `y` and a certain length and orientation, specified by `frameIdx`. The girder can only be placed in open space and must not collide with anything so this function may fail. It will return `true` on successful placement and `false` on failure.

These are the accepted values for `frameIdx`:

|| *`frameIdx`* || *Length* || *Orientation* ||
|| 0 || short || horizontal ||
|| 1 || short || decreasing right ||
|| 2 || short || vertical ||
|| 3 || short || increasing right ||
|| 4 || long || horizontal ||
|| 5 || long || decreasing right ||
|| 6 || long || vertical ||
|| 7 || long || increasing right ||

==== <tt>!PlaceRubber(x, y, frameIdx)</tt> (0.9.23) ====
Attempts to place a rubber with centre points `x`, `y` and a certain orientation, specified by `frameIdx`. The rubber can only be placed in open space and must not collide with anything so this function may fail. It will return `true` on successful placement and `false` on failure.

These are the accepted values for `frameIdx`:

|| *`frameIdx`* || *Orientation* ||
|| 0 || horizontal ||
|| 1 || decreasing right ||
|| 2 || vertical ||
|| 3 || increasing right ||

==== <tt>!PlaceSprite(x, y, sprite, frameIdx, tint, behind, flipHoriz, flipVert, [, landFlag, ...])</tt> ====
Places a [Sprites sprite] at the specified position (`x`, `y`) on the map, it behaves like terrain then. Unlike `PlaceGirder`, this function does not check for collisions, so the sprite can be placed anywhere within map boundaries. The function returns `true` if the placement was successful, `false` otherwise. `frameIdx` is the frame index starting by 0. `frameIdx` is used if the sprite consists of several sub-images. Only a subset of the sprites is currently supported by this function:

 * `sprAmGirder`
 * `sprAmRubber`
 * `sprAMSlot`
 * `sprAMAmmos`
 * `sprAMAmmosBW`
 * `sprAMCorners`
 * `sprHHTelepMask`
 * `sprTurnsLeft`
 * `sprSpeechCorner`
 * `sprSpeechEdge`
 * `sprSpeechTail`
 * `sprTargetBee`
 * `sprThoughtCorner`
 * `sprThoughtEdge`
 * `sprThoughtTail`
 * `sprShoutCorner`
 * `sprShoutEdge`
 * `sprShoutTail`
 * `sprBotlevels`
 * `sprIceTexture`
 * `sprCustom1`
 * `sprCustom2`

`tint` is for an RGBA colouring to apply, this works about the same as `Tint` in gears. If `nil`, the original color is used.

`behind` indicates the sprite should not replace existing land.

`flipHoriz` and `flipVert` are for mirroring the sprite vertically and horizontally before placing, respectively.

The 9th and later arguments specify land flags (see the constants section) to be used for the newly created terrain. If omitted, `lfNormal` is assumed.

Example:

<code language="lua">PlaceSprite(2836, 634, sprAmGirder, 5)
-- Places the girder sprite as normal terrain at (2836, 634). The `frameIdx` 5 is for the long decreasing right girder.</code>
<code language="lua">PlaceSprite(1411, 625, sprAmRubber, 1, nil, nil, nil, nil, lfBouncy)
-- Places the rubber band sprite as bouncy terrain at (2836, 634). The `frameIdx` 1 is for the decreasing right rubber band.</code>

==== <tt>!EraseSprite(x, y, sprite, frameIdx, eraseOnLFMatch, onlyEraseLF, flipHoriz, flipVert, [, landFlag, ...])</tt> ====
Erases a [Sprites sprite] at the specified position (`x`, `y`) on the map. `frameIdx` is the frame index starting by 0. `sprite`, `frameIdx`, `flipHoriz` and `flipVert` behave the same as in `PlaceSprite`. For `sprite`, the same subset of sprites is permitted.

Set `eraseOnLFMatch` to `true` to erase all land for a pixel that matches any of the passed in land flags.  This is useful if, for example, an `lfBouncy` sprite was placed “behind” land using `PlaceSprite` and you want to remove it without destroying the non-bouncy terrain.

Set `onlyEraseLF` to `true` to only remove specific land flags. If for example a sprite consists of `lfIndestructible` and `lfBouncy`, and you call `EraseSprite` with `onlyEraseLF` and `lfIndestructible` set, the sprite will remain bouncy but can be destroyed.  You can use this to entirely remove all land flags from a sprite—at this point the sprite will be visual only, painted on the map but with no collision.

Examples:

<code language="lua">EraseSprite(2836, 634, sprAmGirder, 5)
-- Removes the girder sprite at (2836, 634). The frameIdx 5 is for the long decreasing right girder.</code>
<code language="lua">EraseSprite(1411, 625, sprAmRubber, 1, true, true, nil, nil, lfIndestructible)
-- Removes indestructibility from a rubber band sprite at (2836, 634). The frameIdx 1 is for the decreasing right rubber band.</code>

==== <tt>!AddPoint(x, y [, width [, erase] ])</tt> ====
This function is used to draw your own maps using Lua. The maps drawn with this are of type “hand-drawn”.

The function takes a `x`,`y` location, a `width` (means start of a new line) and `erase` (if `false`, this function will draw normally, if `true`, this function will erase drawn stuff).

This function must be called within `onGameInit`, where `MapGen` has been set to `mgDrawn`. You also should call `FlushPoints` when you are finished with drawing.

See [LuaDrawning] for some examples.

==== <tt>!FlushPoints()</tt> ====
Makes sure that all the points/lines specified using `AddPoint` are actually applied to the map. This function must be called within `onGameInit`.

=== Current hedgehog ===

==== <tt>!GetCurAmmoType()</tt> ====
Returns the currently selected [AmmoTypes Ammo Type].

==== <tt>!SwitchHog(gearUid)</tt> ====
This function will switch to the hedgehog with the specifiedd `gearUid`.

==== <tt>!SetWeapon(ammoType)</tt> ====
Sets the selected weapon of `CurrentHedgehog` to one of the [AmmoTypes Ammo Type].

Examples:

<code language="lua">
  SetWeapon(amBazooka) -- select the bazooka (if hog has one)
</code>
<code language="lua">
  SetWeapon(amNothing) -- unselects the weapon.
</code>

==== <tt>!SetNextWeapon()</tt> ====
This function makes the current hedgehog switch to the next weapon in list of available weapons. It can be used for example in trainings to pre-select a weapon.

==== <tt>!SetInputMask(mask)</tt> ====
Masks specified player input. This means that Hedgewars ignores certain player inputs, such as walking or jumping.

Example: 
<code language="lua">    -- masks the long and high jump commands
SetInputMask(band(0xFFFFFFFF, bnot(gmLJump + gmHJump))) 
    -- clears input mask, allowing player to take actions
    SetInputMask(0xFFFFFFFF) 
		</code>
*Note*: Using the input mask is an effective way to script uninterrupted cinematics, or create modes such as No Jumping.

*Note*: This function is used internally in the Animate [LuaLibraries library].

See also [GearMessages].

==== <tt>!GetInputMask()</tt> ====
Returns the current input mask of the player.

==== <tt>!SetVampiric(bool)</tt> (0.9.24) ====
Toggles vampirism mode for this turn. Set `bool` to `true` to enable (same effect as if the hedgehog has used Vampirism), `false` to disable.

==== <tt>!GetVampiric()</tt> (0.9.25) ====
Returns true if vampirism mode is currently active.

==== <tt>!SetLaserSight(bool)</tt> (0.9.24) ====
Toggles laser sight for this turn. Set `bool` to `true` to enable (same effect as if the hedgehog has used Laser Sight), `false` to disable.

==== <tt>!GetLaserSight()</tt> (0.9.25) ====
Returns true if laser sight (as utility) is currently active. The sniper rifle's built-in laser sight does not count.

==== <tt>!EnableSwitchHog()</tt> (0.9.25) ====
Enable hog switching mode for the current hedgehog. This function should be called while the hedgehog is standing on solid ground (`GetFlightTime` returns 0).

Internally, this tries to spawn a `gtSwitcher` gear which, as long it exists, handles the hog switching. You can delete this gear to stop the hog switching prematurely. If there already is a `gtSwitcher` gear, no additional gear is spawned.

On success, returns the `gtSwitcher` gear being spawned or, if hog switching mode is already active, returns the exsting gear. On failure, returns `nil`.

=== Randomness ===
==== <tt>!GetRandom(number)</tt> ====
Returns a randomly generated number in the range of 0 to number - 1. This random number uses the game seed, so is synchronised, and thus safe for multiplayer and saved games. Use `GetRandom` for anything that could impact the engine state. For example, a visual gear could simply use Lua’s `math.random`, but adding a regular gear should use `GetRandom`.

=== Clans and teams ===
==== <tt>!AddTeam(teamname, color, grave, fort, voicepack, flag)</tt> ====

Adds a new team.

You *must* call it only in `onGameInit`.
You *must* add at least one hedgehog with `AddHog` after calling this. The engine does not support empty teams.
`AddTeam` is only supported for singleplayer missions. You *must not* call this function in multiplayer.

Arguments:

 * `teamname`: The name of the team.
 * `color`: Team color, usually a number from -9 to -1 (see below)
 * `grave`: The name of the team’s grave (equals file name without the suffix)
 * `fort`: The name of the team’s fort (equals file name without the suffix and without the letter “L” or “R” before that suffix)
 * `voicepack`: The name of the team’s voice pack (equals the directory name)
 * `flag`: Optional argument for the name of the team’s flag (equals file name without the suffix). If set to `nil`, the flag “hedgewars” is used.

===== Clan color =====
Each team must have a color. The color also determines clan membership: Teams with equal color are in the same clan.

The team color is specified as a number from -9 to -1. This will select one of the 9 possible team colors as specified in the player's settings. As the actual colors are set by the player, you can't predict them, but you can usually trust these defaults:

 * `-1`: red
 * `-2`: blue
 * `-3`: cyan
 * `-4`: purple
 * `-5`: magenta
 * `-6`: green
 * `-7`: orange
 * `-8`: brown
 * `-9`: yellow

An older (and now discouraged) method of specifying the color is by hardcoding it as an RGB color (i.e. `0xDD0000`). This practice is now strongly discouraged because it will ignore the player-chosen color (which is *bad* for players with color blindness) and in 99% of cases you don't need it anyway. It should be only used for testing and debugging. 

===== Example =====

<code language="lua">AddTeam("team 1", -1, "Simple", "Tank", "Default", "hedgewars")
--[[ Adds a new team with name “team 1”, the first default color (usually red), the grave “Simple”,
the fort “Tank” the voicepack “Default” and the flag “hedgewars”. ]]</code>

==== <tt>!GetTeamName(teamIdx)</tt> (0.9.24) ====
Returns the name of the team with the index `teamIdx`. `teamIdx` is a number between 0 and `TeamsCount-1`.

==== <tt>!GetTeamIndex(teamname)</tt> (0.9.24) ====
Returns the team index (number between 0 and `TeamsCount-1`) of the team with the name `teamName`.

==== <tt>!GetTeamClan(teamname)</tt> (0.9.24) ====
Returns the clan ID of the team with the given `teamName`.

==== <tt>!DismissTeam(teamname)</tt> ====
Vaporizes all the hogs of the team with the given team name in a puff of smoke.

This function must not be called while it's the team's turn.

==== <tt>!SetTeamLabel(teamname[, label])</tt> (0.9.24) ====
Set or remove a label for the team with the given team name. The label is a string and will be displayed next to the team's health bar.

If `label` is `nil`, the label will be removed.

There's a special case: If the AI Survival game modifier is active, the AI kill counter will be replaced by the custom team label if it has been set. If `label` is set to `nil`, the default AI counter is shown again.

Use this to display a score, power value or another important team attribute. There's no hard length limit, but please try to keep it as short as possible to avoid visual clutter.

==== <tt>!GetClanColor(clan)</tt> ====
Returns the RGBA color of the chosen clan by its number. The color data type is described in [LuaAPI#Color].

==== <tt>!SetClanColor(clan, color)</tt> ====
Sets the RGBA color of the chosen clan by its number. The color data type is described in [LuaAPI#Color].

=== Campaign management ===
==== <tt>!SaveCampaignVar(varname, value)</tt> ====
Stores the value `value` (a string) into the campaign variable `varname` (also a string). Campaign variables allow you to save progress of a team in a certain campaign. Campaign variables are saved on a per-team per-campaign basis. They are written into the team file (see [ConfigurationFiles#TeamName.hwt]).

There are some special campaign variables which are used by Hedgewars to determine which missions to display in the campaign menu. This is described [ConfigurationFiles#%5BCampaign%20%3CCAMPAIGN_NAME%3E%5D here].

==== <tt>!GetCampaignVar(varname)</tt> ====
Returns the value of the campaign variable `varname` as a string. See also `SaveCampaignVar`.

== Functions affecting the GUI ==

=== <tt>!AddCaption(text)</tt> ===
Display an event text in the upper part of the screen. The text will be white and the caption group will be `capgrpMessage`.

Example:
<code language="lua">
AddCaption("Hello, world!")
</code>

=== <tt>!AddCaption(text, color, captiongroup)</tt> ===
Display an event text in the upper part of the screen with the specified RGBA text [LuaAPI#Color color] and caption group. Although an RBGA color is used, Hedgewars does not actually support transparent or semi-transparent captions, so the fourth byte is ignored. We recommend you to always specify a full opacity (`FF` in hexadecimal) for the caption.

|| *`captiongroup`* || *Meaning* ||
|| `capgrpGameState` || Used for important global game events, like Sudden Death ||
|| `capgrpAmmoinfo` || Used for new weapon crates and some other events ||
|| `capgrpVolume` || Used for “local” changes of client settings that don't affect gameplay, like volume change, auto camera on/off, etc. ||
|| `capgrpMessage` || Generic message ||
|| `capgrpMessage2` || Generic message ||
|| `capgrpAmmostate` || Used to show information about weapon state, i.e. bounce level, timer, remaining shots, etc. ||

The color can be specified in RGBA format, but you can (but don't have to) use one of the following built-in text color.

|| *Built-in color* || *Meaning* ||
|| `capcolDefault` || Default caption color ||
|| `capcolSetting` || Notification related to a local client setting (audio volume, auto camera on/off) ||

Example:
<code language="lua">
AddCaption("Melon bomb rain in 2 rounds!", 0xFF0000FF, capgrpGameState)
-- Green example message.
</code>

=== <tt>!ShowMission(caption, subcaption, text, icon, time [, forceDisplay])</tt> ===
This function will open the mission panel and set the texts in it.

Use to tell the player what he/she is supposed to do. If you use this function, a mission panel is shown for the amount of time specified in `time` (in milliseconds). If `time` is set to 0, it will be displayed for a default amount of time.
This function replaces the *entire* text of the mission panel. Compare this to the global `Goals` variable, which *adds* to the default text without replacing it.

`caption` is the text displayed in the first line, `subcaption` is displayed in the second line and `text` is the text displayed in the third and following lines.

`text` uses some special characters for formatting: `|` is used for a line break, and everything written before and including a `:` in a line is written in a lighter color.

`icon` accepts the following values:

|| *`icon`* || *What is shown* ||
|| _negative number_ || Icon of an ammo type. It is specified as the negative of an ammo type constant (see [AmmoTypes]), i.e. `-amBazooka` for the bazooka icon. ||
|| `0` || Golden crown ||
|| `1` || Target ||
|| `2` || Exclamation mark ||
|| `3` || Question mark ||
|| `4` || Golden star ||
|| `5` || Utility crate ||
|| `6` || Health crate ||
|| `7` || Ammo crate ||
|| `8` || Barrel ||
|| `9` || Dud mine ||

If the optional parameter `forceDisplay` is `true`, this mission panel cannot be removed manually by the player. It's `false` by default.

Example:
<code language="lua">
ShowMission(loc("Nobody Laugh"), loc("User Challenge"), loc("Eliminate the enemy before the time runs out"), 0, 0)
</code>

=== <tt>!HideMission()</tt> ===
Hides the mission panel if it is currently displayed, otherwise, this function does nothing.

=== <tt>!SetZoom(zoomLevel)</tt> ===
Sets the zoom level. The value for maximum zoom is currently 1.0 and for minimum 3.0 The default zoom level is 2.0

=== <tt>!GetZoom()</tt> ===
Returns the current zoom level.

=== <tt>!SetCinematicMode(enable)</tt> (0.9.23) ===
Turns on or off cinematic mode. Cinematic mode can be used for cutscenes etc.
If `enable` is set to `true`, cinematic mode is enabled,
if it is `false`, cinematic mode is disabled.

== Sound functions ==
=== <tt>!PlaySound(soundId, [gearUid [, instaVoice]])</tt> ===
Plays the specified sound. Possible values for `soundId` are listed on the [Sounds] page.

To play a voice (see [Taunts] for a list), you must also set `gearUid`. `gearUid` is the hedgehog gear which is used to “talk”.

If you play a voice, by default the voice will respect an internal queue and might be played with an delay in order to prevent annoying voice overlapping. Since version 0.9.24, you can disable this behaviour and force Hedgewars to instantly play the voice by also setting `instaVoice` to `true`. Only use `instaVoice` when you really need it.

=== <tt>!PlayMusicSound(soundId)</tt> (0.9.25) ===
Plays a sound as replacement for the background music. The sound is played once. The main music is paused and the sound is played instead. The main background music does not resume automatically, so you should call `StopMusicSound` after a while.

Example:
<code language="lua">
PlayMusicSound(sndRideOfTheValkyries) -- Replace the background music the Ride of the Valkyries
</code>

=== <tt>!StopMusicSound(soundId)</tt> (0.9.25) ===
Stops the specified “music sound” (if it was still playing) and resumes the main background music.

=== <tt>!SetSoundMask(soundId, isMasked)</tt> (0.9.24) ===
Disables a given sound (including taunts) from being played by the engine. `soundId` is a valid sound ID on [Sounds] or [Taunts]. `isMasked` is a boolean. If `true`, the sound will not be played by the engine anymore. If `false`, playing this sound is allowed again.

Sounds played by the Lua function `PlaySound` will always work, however, and ignore the sound mask.

Note: Due to the way the voices work internally in Hedgewars, if you want to play a masked voice, you have to set `instaVoice` to `true` when you call `PlaySound`. Otherwise, it won't work.

Example:

<code language="lua">SetSoundMask(sndIncoming, true)
-- Disable the “Incoming” sound from being played</code>

== File system functions ==
=== <tt>!HedgewarsScriptLoad(scriptPath [,mustExist])</tt> ===
Loads a script (i.e. a [LuaLibraries library]) from the specified `scriptPath`. The root directory is here Hedgewars’ data directory. There will be a Lua error if the script does not exist.

If `mustExist` is `false`, no Lua error will happen even when the script does not exist.

Returns `true` if the script was loaded successfully, `false` otherwise.

Example:
<code language="lua">
HedgewarsScriptLoad("/Scripts/Locale.lua")  -- loads locale library
</code>

== Stats functions ==
=== <tt>!SendStat(TStatInfoType, statMessage[, teamName])</tt> ===

This function allows to change the details of the stats screen seen after the end of a game.

`TStatInfoType` is the piece of information you want to manipulate. The result of this functions varies greatly for different `TStatInfoType`s. The parameter `statMessage` is mandatory and is a string used for the statistics, its meaning depends on the `TStatInfoType`. The parameter `teamName` contains the name of a team which is relevant to the chosen stat. This parameter is not always required, this also depends on `TStatInfoType`.

This tables explains the different behaviours of this function for different values of `TStatInfoType`:

|| *`TStatInfoType`* || *Meaning of `statMessage`* || *Team parameter used?* ||
|| `siGraphTitle` || Title of the graph. If you use this, the health icon changes into a star. || No ||
|| `siGameResult` || Title of the stats screen, used to show the result of the game, i.e. who won the game || No ||
|| `siCustomAchievement` || A freeform text for a single “bullet point” in the “bullet point” list in the details section. For each time you call `SendStat` with this `TStatInfoType`, a new “bullet point” gets added to the list. || No ||
|| `siPointType` || Replaces the word “kills” in the ranking list. You have to call this each time before you report the score or kills of a team with `siPlayerKills`. Sadly, grammatical number is currently not respected at all here. || No ||
|| `siPlayerKills` || Adds a team into the ranking with the given number of kills. The order in which this is called for each team matters. Unless the word “kills” has been replaced by `siPointType`, then that word is used instead. Only integers (converted to string) are possible. || Yes ||
|| `siClanHealth` || Value of a data point. This sets a single data point on the graph for the specified team. All teams will be converted to clans prior to drawing, there can only be one chart per clan. Subsequent calls will draw the next point along the horizontal axis; the frontend will then simply connect the dots in the final chart. Only whole numbers are supported. There must be at least 2 data points for any given clan, otherwise there won't be much to look at. ;-) You also should have called `SendHealthStatsOff` if to prevent the default health graphs to be drawn. || Yes ||
|| `siMaxStepKills` || Most hedgehogs killed in a round. `statMessage` must be in format “`<kills> <name of killer hedgehog> (<team name of killer>)`”. || No ||
|| `siMaxTeamDamage` || Team with most damage inflicted to self. `statMessage` must be in the format “`<damage> <team name>`”. || No ||
|| `siKilledHHs` || Total number of killed hedgehogs (converted to string). || No ||
|| `siTeamStats` || This does not have an effect. || No ||
|| `siMaxStepDamage` || Most damage in one turn for the “best shot award”. `statMessage` must be in format “`<damage> <hedgehog name> (<team name>)`”. || No ||
|| `siMaxTurnSkips` || Team with most skips. `statMessage` must be of format “`<number> <teamName>`”. || No ||
|| `siTeamRank` || Overwrite rank of team. `statMessage` is the rank of your choice. Must be sent before `siPlayerKills` of the team in question. || Mo ||

<b>Examples:</b>

<code language="lua">
-- will automatically change the health icon to a star
SendStat(siGraphTitle,'Custom Graph Title')

SendStat(siGameResult,'Winner is Team A!')

SendStat(siCustomAchievement,'This is a custom message posted in the Details section!')

-- Adds 3 teams into the ranking: First, Team A (with 3 kills), then Team B (1 kill) and then Team C (5 kills).
SendStat(siPlayerKills, "3", 'Team A')
SendStat(siPlayerKills, "1", 'Team B')
SendStat(siPlayerKills, "5", 'Team C')

-- In the next ranking, this changes the word “kills” to “points”,
-- call it just before sending kills/score for each team
-- in case you want to change the word i.e. print “point” or “points”
SendStat(siPointType, "points")

-- this will add Team D to the ranking and show “3 points“ in brackets (because of the siPointType above)
SendStat(siPlayerKills, "3", "Team D")

-- call siClanHealth to send the "value" of a clan that will be used for the graph creation
-- a good idea is to call it always for every hog by using the runOnGears(function)
-- in normal mode "value" represents clan health
SendStat(siClanHealth, "100", "teamName")

-- most hedgehogs killed in a round (hedgehogName is who killed them)
SendStat(siMaxStepKills, "1 hedgehogName (teamName)")

-- team with most damage inflicted to self
SendStat(siMaxTeamDamage, "100 teamName")

-- total number of killed hedgehogs
SendStat(siKilledHHs, "1")

-- best shot award
SendStat(siMaxStepDamage, "30 hedgehogName (teamName)")

-- team with most kills of own hedgehogs
SendStat(siMaxStepDamage, "2 teamName")

-- team with most skips
SendStat(siMaxTurnSkips, "3 teamName")

-- set 15 kills for team "MyTeam" and overwrite its rank to 3
SendStat(siPlayerKills, "15", "MyTeam")
SendStat(siTeamRank, "3")

</code>

<b>Important:</b>

  * As the game engine send stats to the frontend at the end of the game one should send her stats when the game is going to finish and right before the call of `EndGame()`. (Note: Stats are sent from the engine in `CheckForWin`. If conditions are met (win or draw) then `SendStats(uStats)` is called.)
  * Calling just `EndGame()` won’t produce any stats.
  * If one would like to produce a custom graph see also `SendHealthStatsOff()`.

=== <tt>!SendHealthStatsOff()</tt> ===
Prevents the engine of sending health stats to the frontend. 

If any health stats haven’t been sent before this will cause the health graph to the stats page to be hidden. Use this function in the Lua scripts to produce custom graphs by calling it inside `onGameStart()` and using the `SendStat()` function.
f
=== <tt>!SendAchievementsStatsOff()</tt> (0.9.23) ===
Prevents the engine of populating the snarky comments in the “Details” section (internally known as “achievements”) of the stats screen, such as “best shot award”, etc. So you can start with a clean list when the game ends normally. This function needs to be called inside `onGameStart()`.

=== <tt>!SendRankingStatsOff()</tt> (0.9.23) ===
Prevents the engine of populating the team rankings in the stats screen, so you can start with a clean list when the game ends normally. This function needs to be called inside `onGameStart()`.

=== <tt>!SendGameResultOff()</tt> (0.9.23) ===
Prevents the engine of setting the game result text at the top of the stats screen, e.g. “Team 1 wins!” when the game ends normally. This function needs to be called inside `onGameStart()`.

=== <tt>!GetTeamStats(teamname)</tt> (0.9.23) ===
Returns a table of internal stats of a team. This table has the following fields:

 * `Kills`: Number of kills
 * `Suicides`: Number of suicides (not yet working)
 * `AIKills`: Number of AI kills
 * `TeamKills`: Number of hedgehogs killes in own team (excluding current hedghog)
 * `TurnSkips`: Number of skipped turns
 * `TeamDamage`: Damage inflicted to own team (excluding current hedgehog)

== Math Functions ==

=== <tt>div(dividend, divisor)</tt> ===
Performs an integer division and returns the result.
The result is an integer and has the value of the first parameter (an integer) divided by the second parameter (another integer), rounded towards zero.

=== <tt>band(value1, value2)</tt> ===
Returns the bitwise logical AND of `value1` and `value2`.

=== <tt>bor(value1, value2)</tt> ===
Returns the bitwise logical OR of `value1` and `value2`.

=== <tt>bnot(value)</tt> ===
Returns the bitwise logical NOT of `value`.


== Debugging Functions ==
=== <tt>WriteLnToConsole(string)</tt> ===
Writes `string` to `Logs/game0.log`, found in the user data directory.

=== <tt>WriteLnToChat(string)</tt> (0.9.24) ===
Writes `string` into the chat.

=== <tt>DumpPoint(x, y)</tt> (0.9.23) ===
Converts the whole numbers `x` and `y` to strings and writes them to `Logs/game0.log`, one line each.

=== <tt>StartGhostPoints(count)</tt> ===
Just prints out “GHOST_POINTS” and the argument on the console. This function might change in later versions.

=== <tt>DeclareAchievement(id, teamname, location, value)</tt> ===
Declares an achievement with the identifier `id` achieved by the team `teamname` on the map `location` with an achievement value (e.g. score) of `value`. `value` must be an integer. You are supposed to call this function inside an `onAchievementsDeclaration` callback.

Currently, this actually just triggers a console output, but it might be changed later. The idea is to track multiplayer records.

Example:

<code language="lua">DeclareAchievement("height reached", teamname, "ClimbHome", -score)</code>
Records a team's best height in !ClimbHome.

=== <tt>!ParseCommand(string)</tt> ===
Makes the game client parse and execute the specified internal game engine command.

The available commands depend on the current engine protocol version. The *engine protocol can (and will) change* between releases.

**Important**: If you use `ParseCommand` to overcome a shortcoming in our Lua API (e.g. a missing function), please make sure to [https://issues.hedgewars.org/enter_bug.cgi report the issue].

With your report we can fix the shortcoming in future releases. We will try to remove the reliance on `ParseCommand` as good as possible. This will allow scripts to use the previously missing feature in a way that won’t break!

There are many available commands, but actual use in scripting is rare, and even then it's discouraged for long-term use. As of 0.9.24, the only command used in official scripts is:

 * `"draw <map>"`: Draws a hand-drawn map. `MapGen` must be `mgDrawn` for this to work. `<map>` is a string which must follow the format specified in [DrawnMapFormat]

Moreover, the control action names as listed in [ConfigurationFiles] (under “Binds”) can be used. Note we will eventually try to remove all `ParseCommand`s in the official scripts.

=== <tt>!EndLuaTest(success)</tt> ===
This function is used by the Hedgewars developers in testing scripts in order to test the game engine. The testing scripts can be found in the Hedgewars source code under `tests/lua`. This function is useless for anything else.

Calling this function ends an engine test and reports a test result.

`success` is either one of `TEST_SUCCESSFUL` to report a successful test or `TEST_FAILED` for a failed test.

See [EngineTestCases] to learn more about testing the engine.