#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` (`12` in 1.0.0) || 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` || Time the current hedgehog needs to be inactive before gear stuff gets updated in infinite attack mode, like applying hog damage and deaths. This is quite an obscure variable, only change it if you know what you're doing ||

|| `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. The text supports the same special characters as in `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>onCaseDrop(gear)</tt> ===

This function calls between two turns right after the moment at which the game *might* drop a crate according to the game scheme settings. It does not matter if it actually wants to drop a crate.

If a crate was dropped, `gear` is the crate gear that was dropped, if no crate was dropped, `gear` is `nil`.

This function is useful to add custom crate drops as well.

=== <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>onGameResult(winningClan)</tt> (0.9.25) ===

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

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

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