LuaLibraryTracker.wiki
author Wuzzy
Thu, 03 May 2018 00:08:47 +0100
changeset 1381 6695b6e1d39a
parent 1371 2f474a6a7c54
child 1397 63655141bb8f
permissions -rw-r--r--
LuaAPI: Point to HealHog
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1371
2f474a6a7c54 LuaLibraryTracker: better summary
Wuzzy
parents: 1370
diff changeset
     1
#summary Lua library documentation of Tracker; for keeping track of gears
1346
1886a29a6bce LuaLibraryTracker: labels
Wuzzy
parents: 1337
diff changeset
     2
#labels !LuaLibrary
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     3
= Lua library: `Tracker` =
1366
680a173ead44 LuaLibraryTracker: TOC -1
Wuzzy
parents: 1365
diff changeset
     4
<wiki:toc max_depth="2" />
1364
a0547181393a LuaLibraryTracker: TOC 2
Wuzzy
parents: 1363
diff changeset
     5
a0547181393a LuaLibraryTracker: TOC 2
Wuzzy
parents: 1363
diff changeset
     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
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    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:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    12
<code language="lua">function killall(gear)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
    SetHealth(gear, 0)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
function onGearDelete(gear)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
    if GetGearType(gear) == gtTarget then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
        runOnHogs(killall)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
This will kill all hogs if a target is destroyed.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
1364
a0547181393a LuaLibraryTracker: TOC 2
Wuzzy
parents: 1363
diff changeset
    23
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
    24
[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
    25
1369
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    26
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    27
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    28
== Tracking functions ==
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    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.
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    30
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
=== `trackGear(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
Will keep track of the gear.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    33
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    34
=== `trackDeletion(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    35
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
    36
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    37
=== `trackHiding(gear)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    38
Will keep track of the given hedgehog gear when it becomes hidden (e.g. with `HideHog`).
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    39
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    40
=== `trackRestoring(gear)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    41
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
    42
1369
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    43
=== `trackTeams()` ===
1370
12e73b288cf0 LuaLibraryTracker: trackTeams
Wuzzy
parents: 1369
diff changeset
    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`.
1369
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    45
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    46
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    47
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    48
== “`runOn`” functions ==
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    49
These functions are used to run a function on _tracked_ gears, teams and clans.
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    50
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    51
=== `runOnGears(func)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    52
Runs the function `func` on all tracked gears.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    53
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    54
=== `runOnHogs(func)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    55
Runs the function `func` on all tracked hedgehogs.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    56
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    57
=== `runOnHogsInTeam(func, team)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    58
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
    59
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    60
=== `runOnHogsInOtherTeams(func, team)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    61
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
    62
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    63
=== `runOnHogsInClan(func, clan)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    64
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
    65
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    66
=== `runOnHogsInOtherClans(func, clan)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    67
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
    68
1369
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    69
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    70
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    71
== Helper functions ==
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    72
=== `getFirstHogOfClan(clan)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    73
Returns the first hedgehog (alive or not) in the clan with clan ID `clan`.
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    74
1369
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    75
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    76
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    77
== Key-value storage ==
1368
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
    78
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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    79
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    80
=== `getGearValue(gear, key)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    81
Returns the gear value of the given `gear` for `key`.
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    82
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    83
=== `setGearValue(gear, key, value)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    84
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
    85
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    86
=== `increaseGearValue(gear, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    87
Increases the gear value for `key` by 1. This function *must not* be called if the current value is not a number.
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    88
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    89
=== `decreaseGearValue(gear, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    90
Decreases the gear value for `key` by 1. This function *must not* be called if the current value is not a number.
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    91
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    92
=== `getTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    93
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
    94
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    95
=== `setTeamValue(team, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    96
Sets the team value with given `key` to `value`. `team` is the team name.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    97
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    98
=== `increaseTeamValue(team, key)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    99
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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   100
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   101
=== `decreaseTeamValue(team, key)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   102
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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   103
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   104
=== `getClanValue(clan, key)` ===
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   105
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
   106
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   107
=== `setClanValue(clan, key, value)` ===
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   108
Sets the clan value with given `key` to `value`. `clan` is the clan ID.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   109
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   110
=== `increaseClanValue(clan, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   111
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
   112
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   113
=== `decreaseClanValue(clan, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   114
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
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   115
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   116
=== Examples ===
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   117
Assuming `gear` is a tracked gear, here are some simple usage examples:
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   118
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   119
<code lang="lua">
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   120
setGearValue(gear, "mutant", true)
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   121
local isMutant = getGearValue(gear, "mutant")
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   122
print(isMutant) -- prints "true"
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   123
</code>
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   124
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   125
<code lang="lua">
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   126
setGearValue(gear, "score", 0)
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   127
increaseGearValue(gear, "score")
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   128
local score = getGearValue(gear, "score")
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   129
print(score) -- prints "1"
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   130
</code>