#summary Libraries for writing Lua scripts in Hedgewars.

= Introduction =

Libraries in scripts in Hedgewars are lua files that are used by many scripts to add a common function, as an example the Locale library that allows scripts to translate text. The variables in these files are not exposed to the script using it but all the functions can be called.

To use a library you only need to add one row at the top of the script:
<code lang="lua">
loadfile(GetDataPath() .. "Scripts/<Library Name>.lua")()
</code>
Where <Library Name> is replaced by the name. Do not forget the "()" at the end as this initialises the file.


= Locale =

This library allows you to translate string and should be used whenever a script has text. It loads the appropriate locale file and check automatically.

=== lang(text) ===
<blockquote>
Returns the localised string of text or if it is not found it returns text.
</blockquote>


= Utils =

This library includes miscellaneous functions to use, they are all independent of each other and can be used everywhere.

=== gearIsInBox(gear, x, y, w, h) ===
<blockquote>
Returns whether the gear is inside (centre point of the gear) a box with x and y as the top left corner and having the width and height of w and h respectively.
</blockquote>

=== gearIsInCircle(gear, x, y, r, useRadius) ===
<blockquote>
Returns whether the gear is inside a circle with x and y being the centre point and r being the radius of the circle. The boolean useRadius determine whether only the centre point of the gear will be used or the radius of the gear will be checked too.
</blockquote>


= Tracker =

This library is intended to be used if you need to keep track of gears. It can also keep track of teams and clans and as an extra functionality it can also store variables for a gear, team or clan.

To set it up you need to add some hooks in different events. The hooks trackGear and trackDeletion to onGearAdd and onGearDelete respectively. It is strongly recommended to only track the gears you are interested in as, especially with snow on, the amount of gears can go up high and that will slow down the script. To keep track of teams you need to keep track of gtHedgehog and gtResurrector (if resurrection might be used) and add trackTeams to onGameStart.

If you want to call a function on a couple of gears you will have to call the "runOn" functions. To these you will pass the function you want to be run as a variable to the function. The function must take a gear as a parameter, nothing else, for example:
<code lang="lua">
function killall(gear)
    SetHealth(gear, 0)
end

function onGearDelete(gear)
    if GetGearType(gear) == gtTarget then
        runOnHogs(killall)
    end
end
</code>
This will kill all hogs if a target is destroyed.

To see a commented example of the tracker in use by a script you can look at
[http://code.google.com/p/hedgewars/source/browse/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons]

== Tracking functions ==

=== trackGear(gear) ===
<blockquote>
Will keep track of the gear.
</blockquote>

=== trackDeletion(gear) ===
<blockquote>
Will stop keeping track of the gear (gears not tracked will be ignored).
</blockquote>

=== trackTeams() ===
<blockquote>
Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this).
</blockquote>

== "runOn" functions ==

=== runOnGears(func) ===
<blockquote>
Runs the function func on all gears.
</blockquote>

=== runOnHogs(func) ===
<blockquote>
Runs the function func on all hedgehogs.
</blockquote>

=== runOnHogsInTeam(func, team) ===
<blockquote>
Runs the function func on all hedgehogs in the specified team.
</blockquote>

=== runOnHogsInOtherTeams(func, team) ===
<blockquote>
Runs the function func on all hedgehogs but those in the specified team.
</blockquote>

=== runOnHogsInClan(func, clan) ===
<blockquote>
Runs the function func on all hedgehogs in the specified clan.
</blockquote>

=== runOnHogsInOtherClans(func, clan) ===
<blockquote>
Runs the function func on all hedgehogs but those in the specified clan.
</blockquote>

== Variable functions ==

to be continued...