6 == Introduction == |
6 == Introduction == |
7 This Lua 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. |
7 This Lua 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. |
8 |
8 |
9 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`. |
9 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`. |
10 |
10 |
11 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: |
11 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. |
12 <code language="lua">function killall(gear) |
12 |
|
13 === Examples === |
|
14 Here's a minimal example which tracks all hedgehogs and kills them all when a target is destroyed: |
|
15 <code language="lua">HedgewarsScriptLoad("Scripts/Tracker.lua") |
|
16 |
|
17 function onGearAdd(gear) |
|
18 if GetGearType(gear) == gtHedgehog then |
|
19 trackGear(gear) |
|
20 end |
|
21 end |
|
22 |
|
23 local function killAll(gear) |
13 SetHealth(gear, 0) |
24 SetHealth(gear, 0) |
14 end |
25 end |
15 |
26 |
16 function onGearDelete(gear) |
27 function onGearDelete(gear) |
17 if GetGearType(gear) == gtTarget then |
28 if GetGearType(gear) == gtTarget then |
18 runOnHogs(killall) |
29 runOnGears(killAll) |
19 end |
30 end |
20 end</code> |
31 end</code> |
21 This will kill all hogs if a target is destroyed. |
|
22 |
32 |
23 To see a commented example of `Tracker` in use by a script you can look at |
33 To see a commented example of `Tracker` in use by a script you can look at |
24 [https://hg.hedgewars.org/hedgewars/file/default/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons]. |
34 [https://hg.hedgewars.org/hedgewars/file/default/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons]. |
25 |
|
26 |
|
27 |
35 |
28 == Tracking functions == |
36 == Tracking functions == |
29 These functions must be called to start tracking stuff. *IMPORTANT:* The other functions will only work on tracked objects. So make sure you track the things you care about. |
37 These functions must be called to start tracking stuff. *IMPORTANT:* The other functions will only work on tracked objects. So make sure you track the things you care about. |
30 |
38 |
31 === `trackGear(gear)` === |
39 === `trackGear(gear)` === |
39 |
47 |
40 === `trackRestoring(gear)` === |
48 === `trackRestoring(gear)` === |
41 Will keep track of the given hedgehog gear when it becomes restored, i.e. no longer hidden (e.g. with `RestoreHog`). |
49 Will keep track of the given hedgehog gear when it becomes restored, i.e. no longer hidden (e.g. with `RestoreHog`). |
42 |
50 |
43 === `trackTeams()` === |
51 === `trackTeams()` === |
44 Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this). If you want to use any of the team or clan-related functions below, you *must* call this function in `onGameStart`. |
52 Will start the tracking of teams, clans and hedgehogs (individual hogs can be tracked without this). If you want to use any of the team or clan-related functions below, you *must* call this function in `onGameStart`. |
45 |
53 |
46 |
54 |
47 |
55 |
48 == “`runOn`” functions == |
56 == “`runOn`” functions == |
49 These functions are used to run a function on _tracked_ gears, teams and clans. |
57 These functions are used to run a function on _tracked_ gears, teams and clans. The passed function is assumed to take a single argument, which is a gear ID. |
50 |
58 |
51 === `runOnGears(func)` === |
59 === `runOnGears(func)` === |
52 Runs the function `func` on all tracked gears. |
60 Runs the function `func` on all tracked gears. |
53 |
61 |
54 === `runOnHogs(func)` === |
62 === `runOnHogs(func)` === |
55 Runs the function `func` on all tracked hedgehogs. |
63 Runs the function `func` on all tracked hedgehogs. |
56 |
64 |
|
65 Requires `trackTeams` to be called beforehand. |
|
66 |
57 === `runOnHogsInTeam(func, team)` === |
67 === `runOnHogsInTeam(func, team)` === |
58 Runs the function `func` on all tracked hedgehogs in the specified team (`team` = team name). |
68 Runs the function `func` on all tracked hedgehogs in the specified team (`team` = team name). |
|
69 |
|
70 Requires `trackTeams` to be called beforehand. |
59 |
71 |
60 === `runOnHogsInOtherTeams(func, team)` === |
72 === `runOnHogsInOtherTeams(func, team)` === |
61 Runs the function `func` on all tracked hedgehogs but those in the specified team (`team` = team name). |
73 Runs the function `func` on all tracked hedgehogs but those in the specified team (`team` = team name). |
62 |
74 |
|
75 Requires `trackTeams` to be called beforehand. |
|
76 |
63 === `runOnHogsInClan(func, clan)` === |
77 === `runOnHogsInClan(func, clan)` === |
64 Runs the function `func` on all tracked hedgehogs in the specified clan (`clan` = clan ID). |
78 Runs the function `func` on all tracked hedgehogs in the specified clan (`clan` = clan ID). |
65 |
79 |
|
80 Requires `trackTeams` to be called beforehand. |
|
81 |
66 === `runOnHogsInOtherClans(func, clan)` === |
82 === `runOnHogsInOtherClans(func, clan)` === |
67 Runs the function `func` on all tracked hedgehogs but those in the specified clan (`clan` = clan ID). |
83 Runs the function `func` on all tracked hedgehogs but those in the specified clan (`clan` = clan ID). |
|
84 |
|
85 Requires `trackTeams` to be called beforehand. |
68 |
86 |
69 |
87 |
70 |
88 |
71 == Helper functions == |
89 == Helper functions == |
72 === `getFirstHogOfClan(clan)` === |
90 === `getFirstHogOfClan(clan)` === |