This is a documentation for Board Game Arena: play board games online !
Game statistics: stats.json
In this file, you are describing game statistics, that will be displayed at the end of the game.
After modifying this file, you must use "Reload statistics configuration" in BGA Studio Control Panel -> Manage Games ("Game Configuration" section):
https://studio.boardgamearena.com/#!studio
There are 2 types of statistics:
- table statistics, that are not associated to a specific player (i.e.: one value for each game).
- player statistics, that are associated to each players (i.e.: one value for each player in the game).
Statistics types can be "int" for integer, "float" for floating point values, and "bool" for boolean.
Once you defined your statistics there, you can start using "initStat", "setStat" and "incStat" methods in your game logic, using statistics names defined below. See API https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics.
If you want to skip some of your statistics according to game variants, do not init it, or call set or inc on it. It will be displayed as "-" (instead of 0 if you init it and don't update it afterwards)
!! It is not a good idea to modify this file when a game is running !!
If your game is already public on BGA, please read the following before any change: https://en.doc.boardgamearena.com/Post-release_phase#Changes_that_breaks_the_games_in_progress
Notes:
- Statistic index is the reference used in setStat/incStat/initStat PHP method
- Statistic index must contains alphanumerical characters and no space. Example: 'turn_played'
- Statistics IDs must be >=10
- Two table statistics can't share the same ID, two player statistics can't share the same ID
- A table statistic can have the same ID as a player statistics, however its not recommended unless it is same conceptually (like turns_number is same statistic in both per table and per player)
- Statistics ID is the reference used by BGA website. If you change the ID, you lost all historical statistic data. Do NOT re-use an ID of a deleted statistic.
- Statistic name is the English description of the statistic as shown to players
- The order in which the stats will appear in the endscreen is determined by the order in the array, NOT by the ID. That is helpful for stats which getting added later but need to be higher up in the list.
- Statistic names and labels are automatically added to the translations system, so there is no need to wrap them in totranslate() calls
- Previously, this was a PHP file (stats.inc.php). You can continue to use this format for old projects. (Note: once a game has been committed with a
stats.jsonfile, it is not possible to go back without admin intervention.)
{
"table": {
"turns_number": {
"id": 10,
"name": "Number of turns",
"type": "int"
}
},
"player": {
"turns_number": {
"id": 10,
"name": "Number of turns",
"type": "int"
},
"player_teststat1": {
"id": 11,
"name": "player test stat 1",
"type": "int"
},
"player_teststat2": {
"id": 12,
"name": "player test stat 2",
"type": "float"
}
}
}
Sometimes you may want to display a label instead of a number (for instance if you want to indicate the winning faction as a table statistic, and the faction chosen by each player as a player statistic in a game like Terra Mystica).
You can do this by adding a "value_labels" key following the "table" and "players" keys. Please note that the labels apply to both table and player statistics, so you should pay attention to use the same statistic number for the same type of statistic (or to skip one number if labelling should not be applied for both)
{
"table": {
"winning_race": {
"id": 11,
"name": "Winning race",
"type": "int"
},
},
"value_labels": {
"11": [
"None (or tied)",
"Auren",
"Witches",
"Fakirs",
"Nomads",
"Chaos Magicians",
"Giants",
"Swarmlings",
"Mermaids",
"Dwarves",
"Engineers",
"Halflings",
"Cultists",
"Alchemists",
"Darklings"
]
}
}
If you want to consider some internal game statistics for game developer, publisher or admins's purpose only, simply add the following extra property : "display" => "limited". For instance :
{
"player_teststat2": {
"id": 12,
"name": "player test stat 2",
"type": "float",
"display": "limited"
}
}
Translations
Note that any name or value_labels text in these JSON files are automatically added to the translation system, even though they aren't wrapped in totranslate() calls.