#summary API for writing Lua scripts in Hedgewars.

#labels Featured

<wiki:toc max_depth="4" />

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

How Hedgewars handles Lua scripts As of Version 0.9.13 Hedgewars supports Lua scripts for two similar tasks: Define tutorial missions or provide special map behaviour for precreated maps.

=== About this wiki page ===

This page tends to become outdated. For a list of undocumented functions, see [http://hw.ercatec.net/docs/lua_wiki_check.php].

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

=== 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. Maps containing lua scripts will be listed with a "Mission:" prefix in map selection.

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

== Global available Constants ==

<blockquote><tt>LAND_WIDTH</tt>, <tt>LAND_HEIGHT</tt>

</blockquote>

<blockquote><tt>!ScreenWidth</tt>, <tt>!ScreenHeight</tt>, <tt>!WaterLine</tt></blockquote>

Game flags:

<blockquote><tt>gfForts, gfMultiWeapon, gfBorder, gfSolidLand, gfDivideTeams, gfLowGravity, gfLaserSight, gfInvulnerable, gfMines, gfVampiric, gfKarma, gfArtillery, gfOneClanMode, gfRandomOrder, gfKing, gfPlaceHog, gfSharedAmmo, gfDisableGirders, gfExplosives, gfDisableLandObjects, gfAISurvival, gfInfAttack, gfResetWeps, gfResetHealth, gfPerHogAmmo, gfDisableWind, gfMoreWind, gfTagTeam</tt></blockquote>

*Note:* A few of these, e.g. gfResetHealth (and probably gfTagTeam) are not yet exposed to lua.

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

Additional global changing variables accessible:

 * <tt>!ClansCount</tt> - number of clans in the game (teams with the same color belong to one clan)

 * <tt>!TeamsCount</tt> - number of teams in the game

 * <tt>!TurnTimeLeft</tt> - number of game ticks left until the current turn ends

 * <tt>!GameTime</tt> - number of total game ticks

 * <tt>!TotalRounds</tt> - number of round that has passed

 * <tt>!CurrentHedgehog</tt> - the hedgehog gear that is currently in play

== Event Handlers ==

=== <tt>onGameInit()</tt> ===

<blockquote>This function is called before the game loads its resources. One can modify various game variables here:

</blockquote>

 * <tt>Seed = 0</tt> - sets the seed of the random number generator

 * <tt>!EnableGameFlags(gfSolidLand, gfArtillery)</tt> - sets the !GameFlags (just 2 of them in this example), see above for the available flags/

 * <tt>!TurnTime = 60000</tt> - set the turntime in ms

 * <tt>!CaseFreq = 0</tt> - frequency of crate drops

 * <tt>!HealthCaseProb = 35</tt> - chance of receiving a health crate

 * <tt>!HealthCaseAmount = 25</tt> - amount of health in a health crate

 * <tt>!DamagePercent = 100</tt> - percent of damage to inforce

 * <tt>!MinesNum = 0</tt> - number of mines being placed (before 0.9.14 !LandAdds)

 * <tt>!MinesTime = 3</tt> - time for a mine to explode from activated, -1 for random

 * <tt>!MineDudPercent = 0</tt> - chance of mine being a dud

 * <tt>Explosives = 0</tt> - number of explosives being placed

 * <tt>Delay = 0</tt> - delay between each round

 * <tt>!SuddenDeathTurns = 30</tt> - turns until sudden death begins

 * <tt>!WaterRise = 47</tt> - height of water rise at sudden death in pixels

 * <tt>!HealthDecrease = 5</tt> - amount of health decreased on sudden death

 * <tt>Map = "Bamboo"</tt> - the map being played

 * <tt>Theme = "Bamboo"</tt> - the theme to be used

 * <tt>Ready = 5000</tt> - the ready timer at the start of the round

 * <tt>!MapGen</tt> - type of map generator. One of `mgRandom`, `mgMaze`, `mgPerlin`, `mgDrawn`.

 * <tt>!TemplateFilter</tt>

 * <tt>Goals = "Jumping is disabled"</tt> - if you want to add info to the game mode dialog, use "|" to separate lines

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

<blockquote>This function is called when the first round starts.

</blockquote>

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

=== <tt>onGameTick()</tt> ===

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

</blockquote>

=== <tt>onGameTick20()</tt> ===

<blockquote>This function is called every 20 game ticks, i.e. 50 times a second.  It reduces lua overhead for simple monitoring that doesn't need to happen every single tick.

</blockquote>

=== <tt>onNewTurn()</tt> ===

<blockquote>This function calls at the start of every turn.

</blockquote>

=== <tt>onGearAdd(gearUid)</tt> ===

<blockquote>This function is called when a new gear is added. Useful in

combination with <tt>!GetGearType(gearUid)</tt>.

</blockquote>

=== <tt>onGearDelete(gearUid)</tt> ===

<blockquote>This function is called when a new gear is deleted. Useful in

combination with <tt>!GetGearType(gearUid)</tt>.

</blockquote>

=== <tt>onGearDamage(gearUid, damage)</tt> ===

<blockquote>This function is called when a gear is damaged.

</blockquote>

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

<blockquote>This function is called when a gear is resurrected. CPU Hogs will resurrect if the !GameFlag gfAISurvival is enabled. Alternatively, specific gears can have heResurrectable set to true via !SetEffect.

</blockquote>

=== <tt>onAmmoStoreInit()</tt> ===

<blockquote>This function is called when the game is initialized to request the available ammo and ammo probabilities. Use !SetAmmo here.

</blockquote>

=== <tt>onNewAmmoStore(team/clan index, hog index)</tt> ===

<blockquote>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.</blockquote>

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>onScreenResize() (0.9.16) </tt> ===

<blockquote>This function is called when you resize the screen. Useful place to put a redraw function for any vgtHealthTags you're using.

</blockquote>

=== <tt>onAttack()</tt> ===

<blockquote>This function is called when your Hedgehog attacks.

</blockquote>

=== <tt>onHJump()</tt> ===

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

</blockquote>

=== <tt>onLJump()</tt> ===

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

</blockquote>

=== <tt>onPrecise()</tt> ===

<blockquote>This function is called when you press the precise key.

</blockquote>

=== <tt>onLeft()</tt> ===

<blockquote>This function is called when you press the left key.

</blockquote>

=== <tt>onRight()</tt> ===

<blockquote>This function is called when you press the right key.

</blockquote>

=== <tt>onUp()</tt> ===

<blockquote>This function is called when you press the up key.

</blockquote>

=== <tt>onDown()</tt> ===

<blockquote>This function is called when you press the down key.

</blockquote>

=== <tt>onAttackUp()</tt> ===

<blockquote>This function is called when you release the attack key.</blockquote>

=== <tt>onDownUp()</tt> ===

<blockquote>This function is called when you release the down key.</blockquote>

=== <tt>onHogAttack()</tt> ===

<blockquote>This function is called when you press the attack key.</blockquote>

=== <tt>onLeftUp()</tt> ===

<blockquote>This function is called when you release the left key.</blockquote>

=== <tt>onPreciseUp()</tt> ===

<blockquote>This function is called when you release the precise key.</blockquote>

=== <tt>onRightUp()</tt> ===

<blockquote>This function is called when you release the right key.</blockquote>

=== <tt>onSetWeapon()</tt> ===

<blockquote>It is get called when a weapon is selected or switched.</blockquote>

=== <tt>onSlot()</tt> ===

<blockquote>This function is called when a weapon slot (row in the weapon menu) is selected.</blockquote>

=== <tt>onSwitch()</tt> ===

<blockquote>This function is called when a hog is switched to another.</blockquote>

=== <tt>onTaunt()</tt> ===

<blockquote>This function is called when the player uses an animated   emote for example "/wave, /juggle and etc.</blockquote>

=== <tt>onTimer()</tt> ===

<blockquote>This function is called when one of the timer keys is pressed.</blockquote>

=== <tt>onUpUp()</tt> ===

<blockquote>This function is called when you release the up 

key.</blockquote>

=== <tt>onHogHide()</tt> (0.9.16) ===

<blockquote>This function is called when a hedgehog is hidden(removed from the map).</blockquote>

=== <tt>onHogRestore()</tt> (0.9.16) ===

<blockquote>This function is called when a hedgehog is restored (unhidden).</blockquote>

=== <tt>onSpritePlacement(spriteId, centerX, centerY)</tt> (0.9.21) ===

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> (0.9.21) ===

This function is called when a girder has been placed.

`frameIdx` is an integer and declares the length and orientation of the girder:

|| `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 ||

`centerX` and `centerY` are the coordinates of the girder’s center.

=== <tt>onRubberPlacement(frameIdx, centerX, centerY)</tt> (0.9.21) ===

This function is called when a rubber has been placed.

`frameIdx` is an integer which stands for the orientation of the rubber.

|| `frameIdx` || orientation ||

|| 0 || horizontal ||

|| 1 || decreasing right ||

|| 2 || vertical ||

|| 3 || increasing right ||

`centerX` and `centerY` are the coordinates of the rubber’s center.

== Functions for creating gears ==

=== <tt>!AddGear(x, y, gearType, state, dx, dy, timer)</tt> ===

<blockquote>This creates a new gear at position x,y (measured from top left) of kind gearType (see [GearTypes Gear Types]). 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].

</blockquote>

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

<blockquote>This creates a new visual gear at position x,y (measured from top left) of kind visualGearType (see [VisualGearTypes Visual Gear Types]).  The function returns the uid of the visual gear created.  Set critical to true if the visual gear is crucial to game play.  False if it is just an effect, and can be skipped when in fastforward (such as when joining a room).  A critical visual gear will always be created, a non-critical one may fail.  Most visual gears delete themselves. 

</blockquote>

Example:

<code language="lua">  -- adds an non-critical explosion at position 1000,1000. Returns 0 if it was not created.

    vgear = AddVisualGear(1000, 1000, vgtExplosion, 0, false) 

</code>

=== <tt>!SpawnHealthCrate(x, y)</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).

=== <tt>!SpawnAmmoCrate(x, y, ammoType)</tt> ===

Spawns an ammo crate at the specified position with content of ammoType (see [AmmoTypes Ammo Types]). If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land).

Because by default settings the number of ammo in crates is zero it has to be increased to at least one with SetAmmo first, see the example:

Example:

<code language="lua">    SetAmmo(amGrenade, 0, 0, 0, 1) -- see below

    SpawnAmmoCrate(0, 0, amGrenade) -- x=y=0 means random position on map</code>

=== <tt>!SpawnUtilityCrate(x, y, ammoType)</tt> ===

Spawns an utility crate at specified position with content of ammoType. If `x` and `y` are set to 0, the crate will spawn on a random position (but always on land).

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

Spawns a crate at the specified coordinates which looks exactly like a real health crate but it will not heal the player. 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.

=== <tt>!SpawnFakeUtilityCrate(x, y, explode, poison) </tt> ===

Spawns a crate at the specified coordinates which looks exactly like a real utility 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.

=== <tt>!AddHog(hogname, botlevel, health, hat)</tt> ===

Adds a new hedgehog for current team (last created one with the `AddTeam` function), with bot level and specified health, also hat.

`botlevel` ranges from `0` to `5`, where `0` denotes a human player and `1` to `5` denote the skill level of a bot.

Notice: This works only for singleplayers training missions for now and will desync multiplayer games.

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

<blockquote>returns one of [GearTypes Gear Types] for the specified gear

</blockquote>

=== <tt>!GetGearPosition(gearUid)</tt> ===

<blockquote>returns x,y coordinates for the specified gear

</blockquote>

=== <tt>!GetGearRadius(gearUid)</tt> ===

<blockquote>Returns radius for the specified gear

</blockquote>

=== <tt>!GetGearVelocity(gearUid)</tt> ===

<blockquote>returns tuple of dx,dy values for the specified gear

</blockquote>

=== <tt>!GetGearElasticity(gearUid) </tt> ===

<blockquote>Returns the elasticity of the specified gear. 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 non-zero.

</blockquote>

=== <tt>!GetHogClan(gearUid)</tt> ===

<blockquote>returns the clan id of the specified hedgehog gear

</blockquote>

=== <tt>!GetHogTeamName(gearUid)</tt> ===

<blockquote>returns the name of the specified hedgehog gear's team

</blockquote>

=== <tt>!GetHogName(gearUid)</tt> ===

<blockquote>returns the name of the specified hedgehog gear

</blockquote>

=== <tt>!GetEffect(gearUid, effect)</tt> ===

<blockquote>Returns the state of given effect for the given hedgehog gear.  

</blockquote>

see !SetEffect for further details

=== <tt>!GetHogHat(gearUid)</tt> ===

<blockquote>Returns the hat of the specified hedgehog gear

</blockquote>

=== <tt>!GetAmmoCount(gearUid, ammoType) (0.9.16)</tt> ===

<blockquote>Returns the ammo count of the specified ammo type for the specified hedgehog gear.

</blockquote>

=== <tt>!GetGearTarget(gearUid, x, y)  (0.9.16)</tt> ===

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

</blockquote>

=== <tt>GetX(gearUid)</tt> ===

<blockquote>returns x coordinate of the gear

</blockquote>

=== <tt>GetY(gearUid)</tt> ===

<blockquote>returns y coordinate of the gear

</blockquote>

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

<blockquote>returns the message of the gear.

</blockquote>

=== <tt>!GetTag(gearUid)</tt> ===

Returns the tag of the specified gear (by `gearUid`). 

A “tag” 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. `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)

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