LuaLibraryTracker.wiki
author Wuzzy <almikes@aol.com>
Wed, 17 Apr 2019 13:50:26 +0200
changeset 1749 91756d20ce3e
parent 1397 63655141bb8f
permissions -rw-r--r--
Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
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
1397
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
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.
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    12
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    13
=== Examples ===
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    14
Here's a minimal example which tracks all hedgehogs and kills them all when a target is destroyed:
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    15
<code language="lua">HedgewarsScriptLoad("Scripts/Tracker.lua")
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    16
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    17
function onGearAdd(gear)
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    18
    if GetGearType(gear) == gtHedgehog then
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    19
        trackGear(gear)
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    20
    end
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    21
end
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    22
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    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
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    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
a0547181393a LuaLibraryTracker: TOC 2
Wuzzy
parents: 1363
diff changeset
    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
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    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.
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    45
=== `trackHiding(gear)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    46
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
    47
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    48
=== `trackRestoring(gear)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    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
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    51
=== `trackTeams()` ===
1397
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    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
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    53
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    54
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    55
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    56
== “`runOn`” functions ==
1397
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    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
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    58
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    59
=== `runOnGears(func)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    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
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    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
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    65
Requires `trackTeams` to be called beforehand.
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    66
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    67
=== `runOnHogsInTeam(func, team)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    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
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    70
Requires `trackTeams` to be called beforehand.
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    71
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    72
=== `runOnHogsInOtherTeams(func, team)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    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
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    75
Requires `trackTeams` to be called beforehand.
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    76
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    77
=== `runOnHogsInClan(func, clan)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    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
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    80
Requires `trackTeams` to be called beforehand.
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    81
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    82
=== `runOnHogsInOtherClans(func, clan)` ===
1367
831b860f835d LuaLibraryTracker: hidden restored
Wuzzy
parents: 1366
diff changeset
    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
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    85
Requires `trackTeams` to be called beforehand.
63655141bb8f LuaLibraryTracker: clarify runOn
Wuzzy
parents: 1371
diff changeset
    86
1369
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    87
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    88
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    89
== Helper functions ==
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    90
=== `getFirstHogOfClan(clan)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    91
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
    92
1369
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    93
9818052b6fcb LuaLibraryTracker: reorg
Wuzzy
parents: 1368
diff changeset
    94
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    95
== Key-value storage ==
1368
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
    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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    97
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    98
=== `getGearValue(gear, key)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
    99
Returns the gear value of the given `gear` for `key`.
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   100
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   101
=== `setGearValue(gear, key, value)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   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
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   104
=== `increaseGearValue(gear, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   105
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
   106
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   107
=== `decreaseGearValue(gear, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   108
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
   109
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   110
=== `getTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   113
=== `setTeamValue(team, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   114
Sets the team value with given `key` to `value`. `team` is the team name.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   115
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   116
=== `increaseTeamValue(team, key)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   118
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   119
=== `decreaseTeamValue(team, key)` ===
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   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
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   121
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   122
=== `getClanValue(clan, key)` ===
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   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
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   125
=== `setClanValue(clan, key, value)` ===
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   126
Sets the clan value with given `key` to `value`. `clan` is the clan ID.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   127
1365
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   128
=== `increaseClanValue(clan, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   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
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   131
=== `decreaseClanValue(clan, key)` ===
f7ca5312d2ff LuaLibraryTracker: Fix typos and stuff
Wuzzy
parents: 1364
diff changeset
   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
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   133
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   134
=== Examples ===
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   135
Assuming `gear` is a tracked gear, here are some simple usage examples:
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   136
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   137
<code lang="lua">
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   138
setGearValue(gear, "mutant", true)
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   139
local isMutant = getGearValue(gear, "mutant")
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   140
print(isMutant) -- prints "true"
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   141
</code>
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   142
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   143
<code lang="lua">
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   144
setGearValue(gear, "score", 0)
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   145
increaseGearValue(gear, "score")
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   146
local score = getGearValue(gear, "score")
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   147
print(score) -- prints "1"
e073a4197c60 LuaLibraryTracker: Add examples
Wuzzy
parents: 1367
diff changeset
   148
</code>