Back to homepage
LuaStats
History
List of stats functions in the Lua API
LuaFunctions
Updated Sat, 12 Oct 2019 11:44:28 +0100 by Wuzzy

Lua API: Stats functions

This page contains a list of all functions in the 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.

SendStat(TStatInfoType, statMessage[, teamName])

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

-- 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")

Important:

  • 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() .

SendHealthStatsOff()

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

SendAchievementsStatsOff()

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() .

SendRankingStatsOff()

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() .

SendGameResultOff()

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() .

GetTeamStats(teamname)

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)