Game statistics

Use stats.jsonc to list your game's statistics.

Definition

There are two types of statistics:

Table statistics are not associated with a specific player (one value per game).
Player statistics are associated with individual players (one value per player in each game).

stats.jsonc

 {
   "table": {
     "allIn": {
       "id": 10,
       "name": "Number of times all-in was called",
       "type": "int"
     }
   },
   "player": {
     "allIn": {
       "id": 10,
       "name": "Number of times all-in was called",
       "type": "int"
     },
     "trickWon": {
       "id": 11,
       "name": "Tricks won",
       "type": "int"
     },
     "avgTrickWonPerRound": {
       "id": 12,
       "name": "Average number of tricks won per round",
       "type": "float"
     }
   }
 }

After editing the file

Studio reads the file whenever you modify it to load the updated values. If your changes do not appear, your JSON may contain an error. Click Reload statistics configuration on the Manage game page to view the parsed JSON or an error message explaining what to fix, for example, if you used the same ID twice.

Modifying statistics for a game in production

If your game is already public on BGA, read the guidance on changes that affect games in progress before making any changes.

Statistic ID

Reserved IDs

Statistic IDs must be 10 or greater.

The statistic ID is the reference used by the BGA website. If you change it, you will lose all historical data for that statistic. Do not reuse the ID of a deleted statistic.

Statistic label (name)

Statistic names and labels are automatically added to the translation system.

Statistic type

Type	Value
`int`	Integer
`float`	Floating-point value
`bool`	Boolean

Initialization

In setupNewGame, initialize the statistics used in the game. See the game statistics API.

If some statistics apply only to specific game variants, initialize them only when the relevant variant is active. Uninitialized statistics are displayed as "-". Initializing a statistic to 0 without updating it displays 0 and includes that value in averages.

Updating statistics

During the game, you can increment statistics or set their values. See the game statistics API.

Compute the end-of-game statistics in the EndScore state.

For the example above, set the average value for each player in a loop:

modules/php/EndScore.php

$playerTrickWon = $this->bga->playerStats->get('avgTrickWonPerRound', $playerNo);
$playerAverageTrickWonPerRound = $playerTrickWon / $this->bga->globals->get(ROUND);
$this->bga->playerStats->set('avgTrickWonPerRound', $playerAverageTrickWonPerRound, $playerNo);

Labeled statistics

Sometimes you may want to display a label instead of a number. For example, in a game like Terra Mystica, you could display the winning faction as a table statistic and the faction chosen by each player as a player statistic.

To do this, add a value_labels key alongside the table and player keys. Labels apply to both table and player statistics with the same ID. Use the same ID only when the labels make sense for both statistics. Otherwise, use different IDs.

stats.jsonc

{
  "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"
    ]
  }
}

Limited access statistics

To restrict a statistic to game developers, publishers, and administrators, add the "display": "limited" property. For example:

stats.jsonc

{
  "player_teststat2": {
    "id": 12,
    "name": "player test stat 2",
    "type": "float",
    "display": "limited"
  }
}