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

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

=== Special maps ===

=== How Lua scripts are used ===

=== Important things to know ===

=== Global variables/constants ===

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

=== Color ===

Some functions take a `color` parameter.

Colors are stored in RGB and are always specified as a three-byte number, where each byte defines a 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.

Specifying the color number becomes much easier if you write it in hexadecimal notation.

Examples:

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

== 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. You shouldn’t write to most of them.

|| *Identifier* || *Description* ||

|| `LAND_WIDTH` || The width of the landscape in pixels ||

|| `LAND_HEIGHT` || The height of the landscape in pixels ||

|| `WaterLine` || The y position of the water, used to determine at which position stuff drowns. Use `SetWaterLine` to change. ||

|| `ClansCount` || Number of clans in the game (teams with the same color belong to one clan) ||

|| `TeamsCount` || Number of teams in the game ||

|| `TurnTimeLeft` || Number of game ticks (milliseconds) left until the current turn ends. You can change this variable directly. ||

|| `GameTime` || Number of total game ticks ||

|| `TotalRounds` || Number of rounds that have passed ||

|| `CurrentHedgehog` || The hedgehog gear that is currently in play ||

=== !GameFlags ===

The !GameFlags are used to store simple boolean settings of the game. All game flags are stored together in a bitmask. You don’t have to worry about this too much, the functions in [LuaAPI#GameFlags] do all the bitmask handling for you.

|| *Identifier* || *Description (active state)* ||

|| `gfOneClanMode` || Used when only one clan is in the game. This game flag is primarily used for training missions. ||

|| `gfMultiWeapon` || TODO (Used in training missions.) ||

|| `gfForts` || Fort Mode ||

|| `gfDivideTeams` || The teams will start at opposite sites of the terrain. Two clans maximum. ||

|| `gfBorder` || An indestrctible border is active around the map. ||

|| `gfBottomBorder` || There is an indestructable border at the bottom of the map. ||

|| `gfShoppaBorder` || TODO ||

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

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

|| `gfDisableWind` || There is no wind. ||

|| `gfMoreWind` || There is always strong wind. ||

|| `gfTagTeam` || Tag Team: Teams in the same clan share their turn time. ||

|| *Identifier* || *Description (active state)* ||

|| `gfResetHealth` || The health of all living hedgehogs is reset at the end of each turn. ||

=== More constants ===

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

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

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

=== <tt>onPreviewInit()</tt> (0.9.21) ===

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

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

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

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

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

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

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

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

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

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

=== <tt>onGearWaterSkip(gear)</tt> (0.9.21) ===

This function is called when the gear `gear` skips over water.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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