Game statistics: stats.json - Revision history

N e s s u n o: /* File Structure */

2026-09-18T12:05:50Z

File Structure

← Older revision		Revision as of 14:05, 18 September 2026
Line 11:		Line 11:
	* player statistics, that are associated to each players (i.e.: one value for each player in the 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.		Statistics types can be "int" for integer, "float" for floating point values, and "bool" for boolean (0 false, any other value true).

	Once you defined your statistics there, you can start using "tableStats->init / playerStats->init", "tableStats->set / playerStats->set" and "tableStats->inc / playerStats->inc" methods		Once you defined your statistics there, you can start using "tableStats->init / playerStats->init", "tableStats->set / playerStats->set" and "tableStats->inc / playerStats->inc" methods

Thoun at 12:07, 15 April 2026

2026-04-15T12:07:07Z

← Older revision		Revision as of 14:07, 15 April 2026
Line 1:		Line 1:
	{{Studio_Framework_Navigation}}		{{Studio_Framework_Navigation}}

	In this file, you are describing game statistics, that will be displayed at the end of the		In this file, you are describing game statistics, that will be displayed at the end of the game.
	~~game~~.
			Note: you can use jsonc instead of json, to allow comments in the Json.

	=== File Structure ===		=== File Structure ===

Thoun at 09:55, 17 March 2026

2026-03-17T09:55:02Z

← Older revision		Revision as of 11:55, 17 March 2026
Line 3:		Line 3:
	In this file, you are describing game statistics, that will be displayed at the end of the		In this file, you are describing game statistics, that will be displayed at the end of the
	game.		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~~

	=== File Structure ===		=== File Structure ===

Thoun: /* Generate PHP initialization */

2025-12-10T08:56:14Z

Generate PHP initialization

← Older revision		Revision as of 10:56, 10 December 2025
Line 79:		Line 79:
	</pre>		</pre>
	Then on the result string do right click > Copy string content and paste it in your PHP setupNewGame function (this is assuming you want to init all your stats to 0).		Then on the result string do right click > Copy string content and paste it in your PHP setupNewGame function (this is assuming you want to init all your stats to 0).

			To get example of inc of those stats, do
			<pre>
			['table', 'player'].map(type => Object.keys(stats[type]).map(key => `$this->${type}Stats->inc('${key}', 1${type === 'player' ? ', $playerId' : ''});`).join('\n')).join('\n')
			</pre>

	=== Labeled stats ===		=== Labeled stats ===

Thoun at 08:52, 10 December 2025

2025-12-10T08:52:03Z

← Older revision		Revision as of 10:52, 10 December 2025
Line 8:		Line 8:

	https://studio.boardgamearena.com/#!studio		https://studio.boardgamearena.com/#!studio

			=== File Structure ===

	There are 2 types of statistics:		There are 2 types of statistics:

Thoun at 08:51, 10 December 2025

2025-12-10T08:51:07Z

← Older revision		Revision as of 10:51, 10 December 2025
Line 39:		Line 39:
	* (Number of table statistics) + (Number of player statistics × Maximum number of players) should not exceed ~930, or the game will crash. (Note: the maximum limit is not precise - Seems having stats around 980 broke the game, but reducing to around 930 solved this)		* (Number of table statistics) + (Number of player statistics × Maximum number of players) should not exceed ~930, or the game will crash. (Note: the maximum limit is not precise - Seems having stats around 980 broke the game, but reducing to around 930 solved this)

			<pre>
	{		{
	"table": {		"table": {
Line 66:		Line 66:
	}		}
	}		}
			</pre>

			=== Generate PHP initialization ===

			In the Chrome DevTool console (F12), write
			<pre>
			stats = <Ctrl+V of the content of your stats.json file>

			['table', 'player'].map(type => `$this->${type}Stats->init([${Object.keys(stats[type]).map(key => `'${key}'`).join(',')}], 0);`).join('\n')
			</pre>
			Then on the result string do right click > Copy string content and paste it in your PHP setupNewGame function (this is assuming you want to init all your stats to 0).

			=== Labeled stats ===

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

Line 100:		Line 114:
	}		}
	</pre>		</pre>

			=== Limited access stats ===

	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 :		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 :

Thoun at 09:23, 22 October 2025

2025-10-22T09:23:16Z

← Older revision		Revision as of 11:23, 22 October 2025
Line 15:		Line 15:
	Statistics types can be "int" for integer, "float" for floating point values, and "bool" for boolean.		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		Once you defined your statistics there, you can start using "tableStats->init / playerStats->init", "tableStats->set / playerStats->set" and "tableStats->inc / playerStats->inc" methods
	in your game logic, using statistics names defined below.		in your game logic, using statistics names defined below.
	See API https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics.		See API https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics.
Line 27:		Line 27:

	Notes:		Notes:
	* Statistic index is the reference used in ~~setStat~~/~~incStat~~/~~initStat~~ PHP method		* Statistic index is the reference used in set/inc/init PHP method
	* Statistic index must contains alphanumerical characters and no space. Example: 'turn_played'		* Statistic index must contains alphanumerical characters and no space. Example: 'turn_played'
	* Statistics IDs must be >=10		* Statistics IDs must be >=10

Ufm at 04:51, 16 February 2025

2025-02-16T04:51:03Z

← Older revision		Revision as of 06:51, 16 February 2025
Line 37:		Line 37:
	* Statistic names and labels are automatically added to the translations system, so there is no need to wrap them in totranslate() calls		* 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 <code>stats.json</code> file, it is not possible to go back without admin intervention.		* 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 <code>stats.json</code> file, it is not possible to go back without admin intervention.
	* ~~The maximum number~~ of statistics ~~appears to be 324. This can be any combination~~ of ~~table and~~ player statistics. ~~This~~ is ~~true even if you don't use~~ the ~~"Reload statitics configuration" after saving stats.json.~~		* (Number of table statistics) + (Number of player statistics × Maximum number of players) should not exceed ~930, or the game will crash. (Note: the maximum limit is not precise - Seems having stats around 980 broke the game, but reducing to around 930 solved this)

Kayvon: Correction

2025-02-14T01:21:33Z

Correction

← Older revision		Revision as of 03:21, 14 February 2025
Line 36:		Line 36:
	* 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.		* 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		* 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 <code>stats.json</code> file, it is not possible to go back without admin intervention.)		* 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 <code>stats.json</code> file, it is not possible to go back without admin intervention.
	* Apparently, it is not necessary to use the "Reload statistics configuration" button with stats.json. Once they've been loaded, they're automatically refreshed.		* The maximum number of statistics appears to be 324. This can be any combination of table and player statistics. This is true even if you don't use the "Reload statitics configuration" after saving stats.json.
	* The maximum number of statistics appears to be 324. This can be any combination of table and player statistics.

Kayvon: Observations about reloading stats and the maximum number of stats

2025-02-14T01:18:43Z

Observations about reloading stats and the maximum number of stats

← Older revision		Revision as of 03:18, 14 February 2025
Line 37:		Line 37:
	* Statistic names and labels are automatically added to the translations system, so there is no need to wrap them in totranslate() calls		* 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 <code>stats.json</code> file, it is not possible to go back without admin intervention.)		* 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 <code>stats.json</code> file, it is not possible to go back without admin intervention.)
			* Apparently, it is not necessary to use the "Reload statistics configuration" button with stats.json. Once they've been loaded, they're automatically refreshed.
			* The maximum number of statistics appears to be 324. This can be any combination of table and player statistics.