1 #summary Lua library documentation: Tracker |
1 #summary Lua library documentation: Tracker |
2 #labels !LuaLibrary |
2 #labels !LuaLibrary |
3 = Lua library: `Tracker` = |
3 = Lua library: `Tracker` = |
4 |
|
5 *NOTE: Documentation of this library is incomplete, some functions are still undocumented.* |
|
6 |
|
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. |
4 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 |
5 |
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`. |
6 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 |
7 |
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: |
8 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: |
22 |
19 |
23 To see a commented example of the tracker in use by a script you can look at |
20 To see a commented example of the 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]. |
21 [https://hg.hedgewars.org/hedgewars/file/default/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons]. |
25 |
22 |
26 == Tracking functions == |
23 == Tracking functions == |
27 |
|
28 === `trackGear(gear)` === |
24 === `trackGear(gear)` === |
29 |
|
30 Will keep track of the gear. |
25 Will keep track of the gear. |
31 |
26 |
32 |
|
33 === `trackDeletion(gear)` === |
27 === `trackDeletion(gear)` === |
34 |
|
35 Will stop keeping track of the gear (gears not tracked will be ignored). |
28 Will stop keeping track of the gear (gears not tracked will be ignored). |
36 |
29 |
37 |
|
38 === `trackTeams()` === |
30 === `trackTeams()` === |
39 |
|
40 Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this). |
31 Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this). |
41 |
32 |
|
33 === `trackHiding(gear)` === |
|
34 Will keep track of the given hedgehog gear when it is hidden. |
|
35 |
|
36 === `trackRestoring(gear)` === |
|
37 Will keep track of the given hedgehog gear when it is un-hidden. |
42 |
38 |
43 == “`runOn`” functions == |
39 == “`runOn`” functions == |
44 |
|
45 === `runOnGears(func)` === |
40 === `runOnGears(func)` === |
46 |
|
47 Runs the function `func` on all gears. |
41 Runs the function `func` on all gears. |
48 |
42 |
49 |
|
50 === `runOnHogs(func)` === |
43 === `runOnHogs(func)` === |
51 |
|
52 Runs the function `func` on all hedgehogs. |
44 Runs the function `func` on all hedgehogs. |
53 |
45 |
|
46 === `runOnHogsInTeam(func, team)` === |
|
47 Runs the function `func` on all hedgehogs in the specified team (`team` = team name). |
54 |
48 |
55 === `runOnHogsInTeam(func, team)` === |
49 === `runOnHogsInOtherTeams(func, team)` === |
56 |
50 Runs the function `func` on all hedgehogs but those in the specified team (`team` = team name). |
57 Runs the function `func` on all hedgehogs in the specified team. |
|
58 |
|
59 |
|
60 === runOnHogsInOtherTeams(func, team) === |
|
61 |
|
62 Runs the function `func` on all hedgehogs but those in the specified team. |
|
63 |
|
64 |
51 |
65 === `runOnHogsInClan(func, clan)` === |
52 === `runOnHogsInClan(func, clan)` === |
66 |
53 Runs the function `func` on all hedgehogs in the specified clan (`clan` = clan ID). |
67 Runs the function `func` on all hedgehogs in the specified clan. |
|
68 |
|
69 |
54 |
70 === `runOnHogsInOtherClans(func, clan)` === |
55 === `runOnHogsInOtherClans(func, clan)` === |
|
56 Runs the function `func` on all hedgehogs but those in the specified clan (`clan` = clan ID). |
71 |
57 |
72 Runs the function `func` on all hedgehogs but those in the specified clan. |
58 == Key-value storage == |
|
59 For tracked gears, teams and clans, you can assign an arbitrary number of values. Each tracked object will have a simple key-value storage. Any data type (besides `nil`) can be used for keys and values. |
73 |
60 |
|
61 === `getGearValue(gear, key)` === |
|
62 Returns the gear value of the given gear and key. |
74 |
63 |
75 == Variable functions == |
64 === `setGearValue(gear, key, value)` === |
|
65 Sets the gear value with given `key` to `value`. |
76 |
66 |
77 _To be continued …_ |
67 === `increaseGearValue(gear, value)` === |
|
68 Increase a gear value by 1. This function *must not* be called if the current value is not a number. |
78 |
69 |
|
70 === `decreaseGearValue(gear, value)` === |
|
71 Decrease a gear value by 1. This function *must not* be called if the current value is not a number. |
|
72 |
|
73 === `getTeamValue(team, key)` === |
|
74 Returns the value of the given team (`team` is the team name) for the specified `key`. |
|
75 |
|
76 === `setTeamValue(team, key, value)` === |
|
77 Sets the team value with given `key` to `value`. `team` is the team name. |
|
78 |
|
79 === `increaseTeamValue(team, key)` === |
|
80 Increase a team value by 1. `team` is the team name. This function *must not* be called if the current value is not a number. |
|
81 |
|
82 === `decreaseTeamValue(team, key)` === |
|
83 Decrease a team value by 1. `team` is the team name. This function *must not* be called if the current value is not a number. |
|
84 |
|
85 === `getClanValue(team, key)` === |
|
86 Returns the value of the given clan (`clan` is the clan ID) for the specified `key`. |
|
87 |
|
88 === `setClanalue(team, key, value)` === |
|
89 Sets the clan value with given `key` to `value`. `clan` is the clan ID. |
|
90 |
|
91 === `increaseClanValue(team, key)` === |
|
92 Increase a clan value by 1. `clan` is the clan ID. This function *must not* be called if the current value is not a number. |
|
93 |
|
94 === `decreaseClanValue(team, key)` === |
|
95 Decrease a clan value by 1. `clan` is the clan ID. This function *must not* be called if the current value is not a number. |
|
96 |
|
97 == Convenience functions == |
|
98 === `getFirstHogOfClan(clan)` === |
|
99 Returns the first hedgehog (alive or not) in the clan with clan ID `clan`. |