hwkb: LuaLibraryTracker.wiki@367b835ac926 (annotated)

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
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	23	== Tracking functions ==
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	24	=== `trackGear(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	25	Will keep track of the gear.
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	=== `trackDeletion(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	28	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	29
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	30	=== `trackTeams()` ===
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	31	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	32
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	33	=== `trackHiding(gear)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	34	Will keep track of the given hedgehog gear when it is hidden.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	35
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	36	=== `trackRestoring(gear)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	37	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	38
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	39	== “`runOn`” functions ==
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	40	=== `runOnGears(func)` ===
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	41	Runs the function `func` on all gears.
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	42
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	43	=== `runOnHogs(func)` ===
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	44	Runs the function `func` on all hedgehogs.
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	45
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	46	=== `runOnHogsInTeam(func, team)` ===
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	47	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	48
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	49	=== `runOnHogsInOtherTeams(func, team)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	50	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	51
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	52	=== `runOnHogsInClan(func, clan)` ===
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	53	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	54
bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	55	=== `runOnHogsInOtherClans(func, clan)` ===
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	56	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	57
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	58	== Key-value storage ==
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	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.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	60
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	61	=== `getGearValue(gear, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	62	Returns the gear value of the given gear and key.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	63
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	64	=== `setGearValue(gear, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	65	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	66
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	67	=== `increaseGearValue(gear, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	68	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	69
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	70	=== `decreaseGearValue(gear, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	71	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	72
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	73	=== `getTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	74	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	75
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	76	=== `setTeamValue(team, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	77	Sets the team value with given `key` to `value`. `team` is the team name.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	78
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	79	=== `increaseTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	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.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	81
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	82	=== `decreaseTeamValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	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.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	84
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	85	=== `getClanValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	86	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	87
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	88	=== `setClanalue(team, key, value)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	89	Sets the clan value with given `key` to `value`. `clan` is the clan ID.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	90
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	91	=== `increaseClanValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	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.
1329 bd781e19a52d Split Lua libraries into several sub-pages Wuzzy <almikes@aol.com> parents: diff changeset	93
1361 367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	94	=== `decreaseClanValue(team, key)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	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.
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	96
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	97	== Convenience functions ==
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	98	=== `getFirstHogOfClan(clan)` ===
367b835ac926 LuaLibraryTracker: Add missing functions Wuzzy parents: 1360 diff changeset	99	Returns the first hedgehog (alive or not) in the clan with clan ID `clan`.

author	Wuzzy
	Wed, 02 May 2018 23:31:07 +0100
changeset 1361	367b835ac926
parent 1360	3ea63f51e092
child 1362	e6cdbd0269d8
permissions	-rw-r--r--