LuaLibraryTracker.wiki
author Wuzzy
Wed, 02 May 2018 23:31:53 +0100
changeset 1363 77bece04d563
parent 1362 e6cdbd0269d8
child 1364 a0547181393a
permissions -rw-r--r--
LuaLibraryTracker: TOC fix
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     1
#summary Lua library documentation: Tracker
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` =
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     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`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     7
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     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:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     9
<code language="lua">function killall(gear)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    10
    SetHealth(gear, 0)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    11
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    12
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
function onGearDelete(gear)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
    if GetGearType(gear) == gtTarget then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
        runOnHogs(killall)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
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
    19
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
To see a commented example of the tracker in use by a script you can look at
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
[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
    22
1363
77bece04d563 LuaLibraryTracker: TOC fix
Wuzzy
parents: 1362
diff changeset
    23
<wiki:toc max_depth="3" />
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
== Tracking functions ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    25
=== `trackGear(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    26
Will keep track of the gear.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    27
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    28
=== `trackDeletion(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    29
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
    30
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
=== `trackTeams()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this).
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    33
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    34
=== `trackHiding(gear)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    35
Will keep track of the given hedgehog gear when it is hidden.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    36
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    37
=== `trackRestoring(gear)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    38
Will keep track of the given hedgehog gear when it is un-hidden.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    39
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    40
== “`runOn`” functions ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    41
=== `runOnGears(func)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    42
Runs the function `func` on all gears.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    43
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    44
=== `runOnHogs(func)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    45
Runs the function `func` on all hedgehogs.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    46
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    47
=== `runOnHogsInTeam(func, team)` ===
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    48
Runs the function `func` on all hedgehogs in the specified team (`team` = team name).
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    49
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    50
=== `runOnHogsInOtherTeams(func, team)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    51
Runs the function `func` on all 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
    52
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    53
=== `runOnHogsInClan(func, clan)` ===
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    54
Runs the function `func` on all hedgehogs in the specified clan (`clan` = clan ID).
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    55
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    56
=== `runOnHogsInOtherClans(func, clan)` ===
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    57
Runs the function `func` on all 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
    58
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    59
== Key-value storage ==
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    60
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.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    61
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    62
=== `getGearValue(gear, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    63
Returns the gear value of the given gear and key.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    64
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    65
=== `setGearValue(gear, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    66
Sets the gear value with given `key` to `value`.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    67
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    68
=== `increaseGearValue(gear, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    69
Increase a gear value by 1. This function *must not* be called if the current value is not a number.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    70
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    71
=== `decreaseGearValue(gear, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    72
Decrease a gear value by 1. This function *must not* be called if the current value is not a number.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    73
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    74
=== `getTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    75
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
    76
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    77
=== `setTeamValue(team, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    78
Sets the team value with given `key` to `value`. `team` is the team name.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    79
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    80
=== `increaseTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    81
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.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    82
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    83
=== `decreaseTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    84
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.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    85
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    86
=== `getClanValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    87
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
    88
1361
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    89
=== `setClanalue(team, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    90
Sets the clan value with given `key` to `value`. `clan` is the clan ID.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    91
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    92
=== `increaseClanValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    93
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.
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
=== `decreaseClanValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    96
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.
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    97
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    98
== Convenience functions ==
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
    99
=== `getFirstHogOfClan(clan)` ===
367b835ac926 LuaLibraryTracker: Add missing functions
Wuzzy
parents: 1360
diff changeset
   100
Returns the first hedgehog (alive or not) in the clan with clan ID `clan`.