LuaLibraries.wiki
author vittorio.giovara@gmail.com
Mon, 27 Jun 2011 22:35:05 +0000
changeset 115 3278ecf295a3
parent 103 023ff3c709ac
child 246 7b1a6c46c3b5
permissions -rw-r--r--
First release of the iOS guide
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     1
#summary Libraries for writing Lua scripts in Hedgewars.
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     2
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     3
= Introduction =
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     4
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     5
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.
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     6
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     7
To use a library you only need to add one row at the top of the script:
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     8
<code lang="lua">
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
     9
loadfile(GetDataPath() .. "Scripts/<Library Name>.lua")()
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    10
</code>
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    11
Where <Library Name> is replaced by the name. Do not forget the "()" at the end as this initialises the file.
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    12
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    13
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    14
= Locale =
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    15
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    16
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.
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    17
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    18
=== lang(text) ===
84
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    19
<blockquote>
6fa418422e57 Created wiki page through web user interface.
henrik.rostedt@gmail.com
parents:
diff changeset
    20
Returns the localised string of text or if it is not found it returns text.
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    21
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    22
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    23
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    24
= Utils =
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    25
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    26
This library includes miscellaneous functions to use, they are all independent of each other and can be used everywhere.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    27
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    28
=== gearIsInBox(gear, x, y, w, h) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    29
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    30
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.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    31
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    32
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    33
=== gearIsInCircle(gear, x, y, r, useRadius) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    34
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    35
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.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    36
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    37
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    38
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    39
= Tracker =
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    40
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    41
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.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    42
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    43
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.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    44
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    45
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:
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    46
<code lang="lua">
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    47
function killall(gear)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    48
    SetHealth(gear, 0)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    49
end
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    50
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    51
function onGearDelete(gear)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    52
    if GetGearType(gear) == gtTarget then
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    53
        runOnHogs(killall)
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    54
    end
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    55
end
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    56
</code>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    57
This will kill all hogs if a target is destroyed.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    58
103
023ff3c709ac Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 86
diff changeset
    59
To see a commented example of the tracker in use by a script you can look at
023ff3c709ac Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 86
diff changeset
    60
[http://code.google.com/p/hedgewars/source/browse/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons]
023ff3c709ac Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 86
diff changeset
    61
86
98504fb076c3 Spelling correction
Cairo@chusym.com
parents: 85
diff changeset
    62
== Tracking functions ==
85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    63
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    64
=== trackGear(gear) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    65
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    66
Will keep track of the gear.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    67
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    68
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    69
=== trackDeletion(gear) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    70
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    71
Will stop keeping track of the gear (gears not tracked will be ignored).
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    72
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    73
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    74
=== trackTeams() ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    75
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    76
Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this).
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    77
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    78
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    79
== "runOn" functions ==
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    80
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    81
=== runOnGears(func) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    82
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    83
Runs the function func on all gears.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    84
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    85
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    86
=== runOnHogs(func) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    87
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    88
Runs the function func on all hedgehogs.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    89
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    90
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    91
=== runOnHogsInTeam(func, team) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    92
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    93
Runs the function func on all hedgehogs in the specified team.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    94
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    95
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    96
=== runOnHogsInOtherTeams(func, team) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    97
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    98
Runs the function func on all hedgehogs but those in the specified team.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
    99
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   100
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   101
=== runOnHogsInClan(func, clan) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   102
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   103
Runs the function func on all hedgehogs in the specified clan.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   104
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   105
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   106
=== runOnHogsInOtherClans(func, clan) ===
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   107
<blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   108
Runs the function func on all hedgehogs but those in the specified clan.
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   109
</blockquote>
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   110
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   111
== Variable functions ==
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   112
9f1d2d3db844 Edited wiki page LuaLibraries through web user interface.
henrik.rostedt@gmail.com
parents: 84
diff changeset
   113
to be continued...