#summary API for writing Lua scripts in Hedgewars.

#labels Featured

<wiki:toc max_depth="3" />

== 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>!RealTime</tt> - number of total 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>!GameFlags = gfSolidLand + gfArtillery + ...</tt> - sets the gameflags, 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>

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

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

</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 lang="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 gfAISurvival is included in !GameFlags. 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>

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

</blockquote>

Example:

<code lang="lua">    local gear = !AddGear(0, 0, gtTarget, 0, 0, 0, 0)

    !FindPlace(gear, true, 0, LAND_WIDTH)</code>

=== <tt>!AddVisualGear(x, y, viusalGearType, 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 lang="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> ===

<blockquote>Spawns a health crate at the specified position.

</blockquote>

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

<blockquote>Spawns an ammo crate at the specified position with content of ammoType (see [AmmoTypes Ammo Types]). 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:

</blockquote>

Example:

<code lang="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> ===

<blockquote>Spawns an utility crate at specified position with content of ammoType.

</blockquote>

Example:

<code lang="lua">    !SetAmmo(amLaserSight, 0, 0, 0, 1)

    !SpawnUtilityCrate(0, 0, amLaserSight)</code>

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

<blockquote>Adds a new team. Note that this can only be done in onGameInit(), not at a later time. First argument is the team name followed by color, grave, fort, voicepack and flag settings.

</blockquote>

Notice: This works only for singleplayer's training missions for now and will desync multiplayer games. Flag setting is dev only.

Example:

<code lang="lua">    !AddTeam("team 1", 14483456, "Simple", "Island", "Default", "hedgewars")</code>

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

<blockquote>Adds a new hedgehog for current team (last created one), with botlevel and specified health also head.

</blockquote>

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

Example:

<code lang="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>

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

<blockquote>returns the state of the gear. This is one of [States]

</blockquote>

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

<blockquote>returns the message of the gear.

</blockquote>

=== <tt>!GetFollowGear()</tt> ===

<blockquote>Returns the uid of the gear that is currently being followed.

</blockquote>

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

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

</blockquote>

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

<blockquote>returns the health of the gear

</blockquote>

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

<blockquote>returns the bot level from 0 to 5. 0 means human player.

</blockquote>

=== <tt>!GetVisualGearValues(vgUid)</tt> ===

<blockquote>This returns the typically set visual gear values, useful if manipulating things like smoke or bubbles or circles.  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 and Tint is the colour.

Most visual gears require little to no modification of parameters.

</blockquote>

Example:

<code lang="lua">    !GetVisualGearValues(vgUid) -- return visual gear values

</code>

== Functions to modify gears ==

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

<blockquote>Removes a hedgehog from the map. The hidden hedgehog can be restored with !RestoreHog(gearUid). The current hedgehog cannot be hidden!</blockquote>

Example: 

<code lang="lua">    gear = !AddGear(...)

     !HideHog(gear) -- Hide the newly created gear.</code>

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

<blockquote>Restores a previously hidden hedgehog.</blockquote>

Example: 

<code lang="lua">    gear = !AddGear(...)

     !HideHog(gear) -- Hide the newly created gear.

     !RestoreHog(gear) -- Restore the newly hidden gear.</code>

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

<blockquote>Deletes a Gear</blockquote>

Example:

<code lang="lua">    gear = !AddGear(...)

    !DeleteGear(gear) -- Delete the newly created gear.</code>

=== <tt>!DeleteVisualGear(vgUid)</tt> ===

<blockquote>Deletes a Visual Gear.  Note, most visual gears delete themselves.</blockquote>

Example:

<code lang="lua">    vgear = !AddVisualGear(...)

    !DeleteVisualGear(vgear) -- Delete the newly created visual gear.</code>

=== <tt>!SetVisualGearValues(vgUid, X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint)</tt> ===

<blockquote>This allows manipulation of many of the visual gear values.  Calling GetVisualGearValues first is recommended on most visual gears unless you are controlling all the key values.  In the case of vgtCircle, the visual gear values are mapped as follows.  X, Y: position.  State: radius. Timer: Thickness.  FrameTicks: pulsation speed (0 to disable).  dX, dY: min/max pulsation opacity (0-255). Tint: colour, RGBA.

Most visual gears require little to no modification of parameters.

</blockquote>

Example:

<code lang="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>

=== <tt>!FindPlace(gearUid, fall, left, right, tryHarder) (0.9.16)</tt> ===

<blockquote>Finds a place for the specified gear between x=left and x=right and places it there. 0.9.16 adds an optional fifth parameter, tryHarder. Setting to true/false will determine whether the engine attempts to make additional passes, even attempting to place gears on top of each other.

</blockquote>

Example:

<code lang="lua">    gear = !AddGear(...)

    !FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code>

=== <tt>!HogSay(gearUid, text, manner)</tt> ===

<blockquote>Makes the specified gear say, think, or shout some text in a bubble.

</blockquote>

Example:

<code lang="lua">    !HogSay(!CurrentHedgehog, "I wonder what to do...", SAY_THINK) -- thought bubble with text

    !HogSay(!CurrentHedgehog, "I'm hungry...", SAY_SAY) -- speech bubble with text

    !HogSay(!CurrentHedgehog, "I smell CAKE!", SAY_SHOUT) -- exclamatory bubble with text

</code>

=== <tt>!HogTurnLeft(gearUid, boolean)</tt> ===

<blockquote>Faces the specified hog left or right.

</blockquote>

Example:

<code lang="lua">    !HogTurnLeft(!CurrentHedgehog, true) -- turns !CurrentHedgehog left 

    !HogTurnLeft(!CurrentHedgehog, false) -- turns !CurrentHedgehog right</code>

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

<blockquote>Places the specified gear exactly at the position (x,y).

</blockquote>

=== <tt>!SetGearVelocity(gearUid, dx, dy)</tt> ===

<blockquote>Gives the specified gear the velocity of dx, dy.

</blockquote>

=== <tt>!SetAmmo(ammoType, count, probability, delay, numberInCrate)</tt> ===

<blockquote>This updates the settings for a specified [AmmoTypes Ammo Type] as of count available for players, spawn probability, availability delay in turns, and the number available in crates. This is supposed to be used in the onAmmoStoreInit() event handler.

</blockquote>

Example:

<code lang="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</code>

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

<blockquote>Adds ammoType to the specified gear. The amount added is determined by the arguments passed via !SetAmmo() in the onAmmoStoreInit() event handler. In 0.9.16 ammo can be set directly via the optional third parameter, ammoCount. A value of 0 will remove the weapon, a value of 100 will give infinite ammo.

*Note:* The effectiveness of this function may be limited due to problems with gfPerHogAmmo in lua scripting.

</blockquote>

=== <tt>!SetHealth(gearUid, health)</tt> ===

<blockquote>Sets the health of the specified gear.

This can be used for purposes other than killing hedgehogs.

For example:

  * Starting the RC Plane 10 shots

  * Starting Flying Saucer (gtJetpack) with only 50% fuel.

  * Setting all the mines to duds.

  * (And more!)

<code lang="lua">    function onGearAdd(gear)

       if (!GetGearType(gear) == gtRCPlaane) then

            !SetHealth(gear, 10)

       end

       if (!GetGearType(gear) == gtJetpack) then

            !SetHealth(gear, 1000)

       end

       if (!GetGearType(gear) == gtMine) then

            !SetHealth(gear, 0)

       end

    end</code>