author | Wuzzy |
Tue, 17 Jul 2018 13:32:36 +0100 | |
changeset 1483 | 26ce5d1ea7c1 |
parent 1397 | 63655141bb8f |
permissions | -rw-r--r-- |
1371 | 1 |
#summary Lua library documentation of Tracker; for keeping track of gears |
1346 | 2 |
#labels !LuaLibrary |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
3 |
= Lua library: `Tracker` = |
1366 | 4 |
<wiki:toc max_depth="2" /> |
1364 | 5 |
|
6 |
== Introduction == |
|
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
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. |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
8 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
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`. |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
10 |
|
1397 | 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 |
||
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) |
|
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
24 |
SetHealth(gear, 0) |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
25 |
end |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
26 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
27 |
function onGearDelete(gear) |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
28 |
if GetGearType(gear) == gtTarget then |
1397 | 29 |
runOnGears(killAll) |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
30 |
end |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
31 |
end</code> |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
32 |
|
1364 | 33 |
To see a commented example of `Tracker` in use by a script you can look at |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
34 |
[https://hg.hedgewars.org/hedgewars/file/default/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons]. |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
35 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
36 |
== Tracking functions == |
1365 | 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. |
38 |
||
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
39 |
=== `trackGear(gear)` === |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
40 |
Will keep track of the gear. |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
41 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
42 |
=== `trackDeletion(gear)` === |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
43 |
Will stop keeping track of the gear (gears not tracked will be ignored). |
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
44 |
|
1361 | 45 |
=== `trackHiding(gear)` === |
1367 | 46 |
Will keep track of the given hedgehog gear when it becomes hidden (e.g. with `HideHog`). |
1361 | 47 |
|
48 |
=== `trackRestoring(gear)` === |
|
1367 | 49 |
Will keep track of the given hedgehog gear when it becomes restored, i.e. no longer hidden (e.g. with `RestoreHog`). |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
50 |
|
1369 | 51 |
=== `trackTeams()` === |
1397 | 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`. |
1369 | 53 |
|
54 |
||
55 |
||
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
56 |
== “`runOn`” functions == |
1397 | 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. |
1365 | 58 |
|
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
59 |
=== `runOnGears(func)` === |
1367 | 60 |
Runs the function `func` on all tracked gears. |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
61 |
|
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
62 |
=== `runOnHogs(func)` === |
1367 | 63 |
Runs the function `func` on all tracked hedgehogs. |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
64 |
|
1397 | 65 |
Requires `trackTeams` to be called beforehand. |
66 |
||
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
67 |
=== `runOnHogsInTeam(func, team)` === |
1367 | 68 |
Runs the function `func` on all tracked hedgehogs in the specified team (`team` = team name). |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
69 |
|
1397 | 70 |
Requires `trackTeams` to be called beforehand. |
71 |
||
1361 | 72 |
=== `runOnHogsInOtherTeams(func, team)` === |
1367 | 73 |
Runs the function `func` on all tracked hedgehogs but those in the specified team (`team` = team name). |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
74 |
|
1397 | 75 |
Requires `trackTeams` to be called beforehand. |
76 |
||
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
77 |
=== `runOnHogsInClan(func, clan)` === |
1367 | 78 |
Runs the function `func` on all tracked hedgehogs in the specified clan (`clan` = clan ID). |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
79 |
|
1397 | 80 |
Requires `trackTeams` to be called beforehand. |
81 |
||
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
82 |
=== `runOnHogsInOtherClans(func, clan)` === |
1367 | 83 |
Runs the function `func` on all tracked hedgehogs but those in the specified clan (`clan` = clan ID). |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
84 |
|
1397 | 85 |
Requires `trackTeams` to be called beforehand. |
86 |
||
1369 | 87 |
|
88 |
||
1365 | 89 |
== Helper functions == |
90 |
=== `getFirstHogOfClan(clan)` === |
|
91 |
Returns the first hedgehog (alive or not) in the clan with clan ID `clan`. |
|
92 |
||
1369 | 93 |
|
94 |
||
1361 | 95 |
== Key-value storage == |
1368 | 96 |
For tracked gears, teams and clans, you can assign an arbitrary number of values. Each tracked object has a simple key-value storage. This means, a tracked object has an arbitrary number of keys, each of which holds one arbitrary value. Any data type (besides `nil`) can be used for keys and values. Initially, all keys have the value `nil`. |
1361 | 97 |
|
98 |
=== `getGearValue(gear, key)` === |
|
1365 | 99 |
Returns the gear value of the given `gear` for `key`. |
1361 | 100 |
|
101 |
=== `setGearValue(gear, key, value)` === |
|
1365 | 102 |
Sets the gear value for given `key` to `value`. |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
103 |
|
1365 | 104 |
=== `increaseGearValue(gear, key)` === |
105 |
Increases the gear value for `key` by 1. This function *must not* be called if the current value is not a number. |
|
1361 | 106 |
|
1365 | 107 |
=== `decreaseGearValue(gear, key)` === |
108 |
Decreases the gear value for `key` by 1. This function *must not* be called if the current value is not a number. |
|
1361 | 109 |
|
110 |
=== `getTeamValue(team, key)` === |
|
111 |
Returns the value of the given team (`team` is the team name) for the specified `key`. |
|
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
112 |
|
1361 | 113 |
=== `setTeamValue(team, key, value)` === |
114 |
Sets the team value with given `key` to `value`. `team` is the team name. |
|
115 |
||
116 |
=== `increaseTeamValue(team, key)` === |
|
1365 | 117 |
Increases the team value for `key` by 1. `team` is the team name. This function *must not* be called if the current value is not a number. |
1361 | 118 |
|
119 |
=== `decreaseTeamValue(team, key)` === |
|
1365 | 120 |
Decreases the team value for `key` by 1. `team` is the team name. This function *must not* be called if the current value is not a number. |
1361 | 121 |
|
1365 | 122 |
=== `getClanValue(clan, key)` === |
1361 | 123 |
Returns the value of the given clan (`clan` is the clan ID) for the specified `key`. |
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
124 |
|
1365 | 125 |
=== `setClanValue(clan, key, value)` === |
1361 | 126 |
Sets the clan value with given `key` to `value`. `clan` is the clan ID. |
127 |
||
1365 | 128 |
=== `increaseClanValue(clan, key)` === |
129 |
Increases the clan value for `key` by 1. `clan` is the clan ID. This function *must not* be called if the current value is not a number. |
|
1329
bd781e19a52d
Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff
changeset
|
130 |
|
1365 | 131 |
=== `decreaseClanValue(clan, key)` === |
132 |
Decreases the clan value for `key` by 1. `clan` is the clan ID. This function *must not* be called if the current value is not a number. |
|
1368 | 133 |
|
134 |
=== Examples === |
|
135 |
Assuming `gear` is a tracked gear, here are some simple usage examples: |
|
136 |
||
137 |
<code lang="lua"> |
|
138 |
setGearValue(gear, "mutant", true) |
|
139 |
local isMutant = getGearValue(gear, "mutant") |
|
140 |
print(isMutant) -- prints "true" |
|
141 |
</code> |
|
142 |
||
143 |
<code lang="lua"> |
|
144 |
setGearValue(gear, "score", 0) |
|
145 |
increaseGearValue(gear, "score") |
|
146 |
local score = getGearValue(gear, "score") |
|
147 |
print(score) -- prints "1" |
|
148 |
</code> |