#summary List of stats functions in the Lua API
#labels !LuaFunctions

= Lua API: Stats functions =
This page contains a list of all functions in the [LuaAPI Lua API] related to game stats. The game stats are used to display the end result when a game ends, this includes the game result title, team rankings, health graph and other comments.

<wiki:toc max_depth="2" />

== <tt>!SendStat(TStatInfoType, statMessage[, teamName])</tt> ==

This function allows to change the details of the stats screen seen after the end of a game.

`TStatInfoType` is the piece of information you want to manipulate. The result of this functions varies greatly for different `TStatInfoType`s. The parameter `statMessage` is mandatory and is a string used for the statistics, its meaning depends on the `TStatInfoType`. The parameter `teamName` contains the name of a team which is relevant to the chosen stat. This parameter is not always required, this also depends on `TStatInfoType`.

This tables explains the different behaviours of this function for different values of `TStatInfoType`:

|| *`TStatInfoType`* || *Meaning of `statMessage`* || *Team parameter used?* ||
|| `siGraphTitle` || Title of the graph. If you use this, the health icon changes into a star. || No ||
|| `siGameResult` || Title of the stats screen, used to show the result of the game, i.e. who won the game || No ||
|| `siCustomAchievement` || A freeform text for a single “bullet point” in the “bullet point” list in the details section. For each time you call `SendStat` with this `TStatInfoType`, a new “bullet point” gets added to the list. || No ||
|| `siPointType` || Replaces the word “kills” in the ranking list. You have to call this each time before you report the score or kills of a team with `siPlayerKills`. There are a few special values you can use (see below). || No ||
|| `siPlayerKills` || Adds a team into the ranking with the given number of kills. The order in which this is called for each team matters. Unless the word “kills” has been replaced by `siPointType`, then that word is used instead. Only integers (converted to string) are possible. || Yes ||
|| `siClanHealth` || Value of a data point. This sets a single data point on the graph for the specified team. All teams will be converted to clans prior to drawing, there can only be one chart per clan. Subsequent calls will draw the next point along the horizontal axis; the frontend will then simply connect the dots in the final chart. Only whole numbers are supported. There must be at least 2 data points for any given clan, otherwise there won't be much to look at. ;-) You also should have called `SendHealthStatsOff` if to prevent the default health graphs to be drawn. || Yes ||
|| `siMaxStepKills` || Most hedgehogs killed in a round. `statMessage` must be in format “`<kills> <name of killer hedgehog> (<team name of killer>)`”. || No ||
|| `siMaxTeamDamage` || Team with most damage inflicted to self. `statMessage` must be in the format “`<damage> <team name>`”. || No ||
|| `siKilledHHs` || Total number of killed hedgehogs (converted to string). || No ||
|| `siTeamStats` || This does not have an effect. || No ||
|| `siMaxStepDamage` || Most damage in one turn for the “best shot award”. `statMessage` must be in format “`<damage> <hedgehog name> (<team name>)`”. || No ||
|| `siMaxTurnSkips` || Team with most skips. `statMessage` must be of format “`<number> <teamName>`”. || No ||
|| `siTeamRank` || Overwrite rank of team. `statMessage` is the rank of your choice. Must be sent before `siPlayerKills` of the team in question. || No ||

=== Values for `siPointType` ===

For `siPointType`, we support a few common point types. Just set `statMessage` to one of the following values below:

|| *Value of `statMessage`* || *Meaning* || *How it may appear in team rankings* ||
|| `"!POINTS"` || Number of points || Team 1 (25 points) ||
|| `"!CRATES"` || Number of crates || Team 1 (25 crates) ||
|| `"!TIME"` || Number of milliseconds, shown as seconds with 3 decimal places || Team 1 (0.025 seconds) ||
|| `"!TIME0"` … `"!TIME3"` || Number of milliseconds, shown as seconds with the decimal places specified in the number (e.g. `"!TIME2"` for 2 decimal places) || Team 1 (0.02 seconds) ||
|| `"!EMPTY"` || Don't display anything besides the team name || Team 1 ||
|| _Anything else_ || Custom text with number. Display `statMessage` after the number || Team 1 (25 stars) ||

If `siPointType` was not used, the point type will default to “number of kills” and is displayed in the ranking like “Team 1 (2 kills)”.

The default point type and the special point types (those with the exclamation mark) will get localized in the frontend, including numerus form and decimal point. Do not enclose these special values in `loc()` (see [LuaLibraryLocale]).

If you use the custom text with number, it will not be localized by the frontend, but it's supposed to be localized in Lua instead, just use `loc()`. However, this type doesn't support localization of the numerus form and decimal point, so only use this one as a last resort.

=== Examples ===

<code language="lua">
-- will automatically change the health icon to a star
SendStat(siGraphTitle,'Custom Graph Title')

SendStat(siGameResult,'Winner is Team A!')

SendStat(siCustomAchievement,'This is a custom message posted in the Details section!')

-- Adds 3 teams into the ranking: First, Team A (with 3 kills), then Team B (1 kill) and then Team C (5 kills).
SendStat(siPlayerKills, "3", 'Team A')
SendStat(siPlayerKills, "1", 'Team B')
SendStat(siPlayerKills, "5", 'Team C')

-- In the next ranking, this changes the word “kill”/“kills” to ”point”/“points”
SendStat(siPointType, "!POINTS")

-- this will add Team D to the ranking and show “3 points“ in brackets (because of the siPointType above)
SendStat(siPlayerKills, "3", "Team D")

-- call siClanHealth to send the "value" of a clan that will be used for the graph creation
-- a good idea is to call it always for every hog by using the runOnGears(function)
-- in normal mode "value" represents clan health
SendStat(siClanHealth, "100", "teamName")

-- most hedgehogs killed in a round (hedgehogName is who killed them)
SendStat(siMaxStepKills, "1 hedgehogName (teamName)")

-- team with most damage inflicted to self
SendStat(siMaxTeamDamage, "100 teamName")

-- total number of killed hedgehogs
SendStat(siKilledHHs, "1")

-- best shot award
SendStat(siMaxStepDamage, "30 hedgehogName (teamName)")

-- team with most kills of own hedgehogs
SendStat(siMaxStepDamage, "2 teamName")

-- team with most skips
SendStat(siMaxTurnSkips, "3 teamName")

-- set 15 kills for team "MyTeam" and overwrite its rank to 3
SendStat(siTeamRank, "3")
SendStat(siPlayerKills, "15", "MyTeam")

</code>

<b>Important:</b>

  * As the game engine send stats to the frontend at the end of the game one should send her stats when the game is going to finish and right before the call of `EndGame()`. (Note: Stats are sent from the engine in `CheckForWin`. If conditions are met (win or draw) then `SendStats(uStats)` is called.)
  * Calling just `EndGame()` won’t produce any stats.
  * If one would like to produce a custom graph see also `SendHealthStatsOff()`.

== <tt>!SendHealthStatsOff()</tt> ==
Prevents the engine of sending health stats to the frontend. 

If any health stats haven’t been sent before this will cause the health graph to the stats page to be hidden. Use this function in the Lua scripts to produce custom graphs by calling it inside `onGameStart()` and using the `SendStat()` function.
f
== <tt>!SendAchievementsStatsOff()</tt> ==
Prevents the engine of populating the snarky comments in the “Details” section (internally known as “achievements”) of the stats screen, such as “best shot award”, etc. So you can start with a clean list when the game ends normally. This function needs to be called inside `onGameStart()`.

== <tt>!SendRankingStatsOff()</tt> ==
Prevents the engine of populating the team rankings in the stats screen, so you can start with a clean list when the game ends normally. This function needs to be called inside `onGameStart()`.

== <tt>!SendGameResultOff()</tt> ==
Prevents the engine of setting the game result text at the top of the stats screen, e.g. “Team 1 wins!” when the game ends normally. This function needs to be called inside `onGameStart()`.

== <tt>!GetTeamStats(teamname)</tt> ==
Returns a table of internal stats of a team. This table has the following fields:

 * `Kills`: Number of kills
 * `Suicides`: Number of suicides (not yet working)
 * `AIKills`: Number of AI kills
 * `TeamKills`: Number of hedgehogs killes in own team (excluding current hedghog)
 * `TurnSkips`: Number of skipped turns
 * `TeamDamage`: Damage inflicted to own team (excluding current hedgehog)