Board Game Arena - User contributions [en]

Game meta-information: gameinfos.jsonc

2023-07-08T11:11:04Z

Polinow: Correct the English

{{Studio_Framework_Navigation}}

__TOC__

== Overview ==

From this file, you can edit the various meta-information of your game.

After modifying the file, don't forget to click on "Reload game informations" from the Control Panel so that the changes can be taken into account.

Note: if you break gameinfos and cannot load the management page, then reload using the direct URL: https://studio.boardgamearena.com/admin/studio/reloadGameInfos.html?game= (with your game name at the end of url).

Most of the information provided in this file is self-explanatory.

See sections below for specific cases.

==Publisher/Designer fields==

These fields should match the publisher/designer of the game. In the case of a public domain name, they should be left empty (empty string)

==Beta==

You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.

==Time Profiles==
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these values to match the real game duration.

==Number of players==

'''players'''
'players' => array( 3, 4, 6 ),

*during the first step of development of a game, it is recommended to have a "1 player" configuration: it is much easier to start/stop a game this way, as you don't need to switch players.
*if you change the minimum number of players from 1 to 2, for example, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.
But you can also unblock yourself by changing the number of players again, launching a game with a larger number, and then getting back to the number you want.

'''suggest_player_number''' / '''not_recommend_player_number'''
'suggest_player_number' => 3,
'not_recommend_player_number' => array( 6 ),

Don't specify anything here (null) if there is no configuration that is REALLY better/worse than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. Note that there can be at most one suggested player count (provide either null or a single number), but there can be several not recommended player counts (provide either null or an array of values).

Another reason to leave it blank unless there is really strong reason to do so is that suggest_player_number also has an implication on the ELO calculation, whereby the K-factor is multiplied by the number of players up to a maximum of this value (or, no max if it's not provided). That is to say, a 6-player game with a suggestion of 3-players will have ELO calculated as if it were a 3-player game.

'''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.

==Colors==

'''player_colors'''
'player_colors' => array( "ff0000", "008000", "0000ff", "ffa500", "ffffff" ),

This array defines the default player colors, theoretically this can be bigger then maximum number of players but you have to support all of the in your game.
Your setupNewGame in php is responsible for attributing these values to players. See section "Player color preferences" in [[Main_game_logic:_yourgamename.game.php]] for details.

== Losers not ranked between themselves==

By default, all player are ranked, but in some games, the rules say that all non-winners are losers and not ranked between themselves. You can set this option to true so that for your game, there are only winners and losers, without a full ranking of all players.

The score in this case should be the same for the winners and 0 for the losers.

// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true
// The game end result will display "Winner" for the 1st player and "Loser" for all other players
'losers_not_ranked' => false,

==Disable player rotation in case of rematch==

By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.

// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same
// If you want to disable this, set this to true (even if the comment in your game file say the opposite).
'disable_player_order_swap_on_rematch' => false,

==Custom "buy this game" button==

By default, the "buy this game" button is a link to an Amazon search with the name of the game.

You can replace it by a different URL / game button label with :

'custom_buy_button' => array(
'url' => 'http://yoururl.com',
'label' => 'Name of the website'
),

Note : button label will be "Buy on <Name of the website>"

==Tags==

'''⚠ Note''': tags are no longer read from this file; setting tags for a game is done via the [[Game_metadata_manager|Game Metadata Manager]].

==Game Presentation==

Short game presentation text that will appear on the game description page, structured as an array of paragraphs.

Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)

Example:
'presentation' => array(
totranslate("This wonderful game is about geometric shapes!"),
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),
...
),

==Tie breaker description==
Describe tie breaker score calculation (player_score_aux in player table).

Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.

Example:
'tie_breaker_description' => totranslate("Number of remaining cards in hand"),

== Multiple tie breaker management ==

If your game has multiple tie breakers, here is what you should do.

Let's take this example: "In case of a tie, the winner is the game with the most remaining money, then number of buildings built, then number of cards in your hand".

In this example, your "player_score_aux" field might be calculated like this:

10000 * (remaining_money ) + 100 * (buildings_built) + (number_of_cards)

In this case, you should add the following in gameinfos.inc.php:

'tie_breaker_split' => array( 10000, 100 , 1 ),

It means that the first tie breaker has been multiplied by 10000, the second by 100, and the third by 1.

Using this, the result screen will be adapted to show exactly what is needed. For example:
* When 2 players are tied, it will show their remaining money.
* If their remaining money are equal, it will show the number of building built in addition to the remaining money.
*If these two tie breaker are still the same, it will show the 3 tie breaking values.

==Language dependency==

If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]

== Game page warning==

If a specific warning is needed on the game page (to discuss and validate with admins) it can be displayed from the game infos. For example for Texas Hold'em:

'gamepanel_page_warning' => totranslate("There is no real money involved on BGA: this game has the mechanism of Poker but is using points instead of real money."),

== Coop Elo Mode==

For cooperative games, by default players will earn as many Elo points as the score.

For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1300 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.

For this, you have to set up the coop_elo_mode parameter.

'''Warning: While this can reflect player skills more precisely compared to flat ELO gain, players may abandon losing games or avoid new players to prevent ELO loss.'''

Related discussion - https://forum.boardgamearena.com/viewtopic.php?f=3&t=24363

Here is an example using options and win/loss (score 1/0):

'coop_elo_mode' => [
'type' => 'points_references',
'references' => [
// Difficulty 1
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
// Difficulty 2
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
// Difficulty 3
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
// Difficulty 4
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
// Difficulty 5
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
],
],

Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:

'coop_elo_mode' => array(
'type' => 'points_references',
'references' => array(
array(
'players_nbr' => 2,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1350,
2 => 1425,
3 => 1500,
4 => 1576,
5 => 1651,
6 => 1727,
7 => 1802,
8 => 1878,
9 => 1953,
10 => 2029,
11 => 2104,
12 => 2180
)
),
array(
'players_nbr' => 3,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1400,
2 => 1470,
3 => 1541,
4 => 1612,
5 => 1683,
6 => 1754,
7 => 1825,
8 => 1895,
9 => 1966,
10 => 2018,
11 => 2095,
12 => 2250
)
),
array(
'players_nbr' => 4,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1430,
2 => 1505,
3 => 1580,
4 => 1655,
5 => 1730,
6 => 1805,
7 => 1880,
8 => 1955,
9 => 2030,
10 => 2105,
11 => 2180,
12 => 2330
)
),
array(
'players_nbr' => 5,
// 'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1480,
2 => 1558,
3 => 1636,
4 => 1714,
5 => 1792,
6 => 1870,
7 => 1949,
8 => 2027,
9 => 2105,
10 => 2183,
11 => 2261,
12 => 2340
)
)
)
),

[[Category:Studio]]

Game database model: dbmodel.sql

2023-07-05T05:29:28Z

Polinow: Corrected lots of minor English errors. Did not change any code, did not change any filenames, did not change any function names, etc.

{{Studio_Framework_Navigation}}

In this file, you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

__TOC__

== Create your schema ==

To build this file, we recommend you build the tables you need with the PhpMyAdmin tool (see the BGA user guide), and then export them and copy/paste the content to this file.

'''Note:''' the name of a column must not be the same as the name of the table, as the framework replay function relies on regexp substitution to save/restore the previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you are dealing with games with 50-500 pieces!
** If you have 5 tables for a card game with 30 cards - it is overkill
* The database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: if you have cards that have power, color, and special abilities. In the database, you only need to store the card type, all the other properties should not be there. The only exception is if it changes during the game.
* Columns should be permanent, independent of the game data, i.e. location, type, position, row, etc.
** Example: do not create columns such as Country1, Country2, Country3, etc.
* Do not store translatable strings in the database, use an integer number of "ident" to access properties
** i.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create a separate module in PHP to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method to handle a database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

By default, BGA creates four tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You '''MUST NOT MODIFY''' the schemas of the '''global''', '''stats''', or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

=== The '''player''' table ===

You may add columns to the '''player''' table. It is very practical to add simple values associated with players. '''NB:''' you must not alter existing columns created by the framework.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of the default "player" table are:
* player_no: the index of a player in natural playing order (starting with 1)
* player_id (int)
* player_name: (note: it is better to access this data with the getActivePlayerName() or loadPlayersBasicInfos() methods)
* player_score: the current score of a player (displayed in the player panel). You must update this field to update a player's score.
* player_score_aux: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])

* player_table_order: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order within the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th). Note: player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.

CAUTION: '''player_table_order''' is not guaranteed to be equal to the rank of the player in the table. For example, in a four-player game, if the table was full but the third player leaves before the game starts, the fourth player becomes the third on this table but their player_table_no is still equal to four! If another player then joins, their player_table_no will then be 5. Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read those values as ranks directly, but you can still deduce that <player B> was first on the table, then <player A>, then <player C>, and then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
You can create tables, using engine InnoDB.
See examples above on how to create tables.
Pay attention to the following:
* Always add IF NOT EXISTS
* Always set ENGINE=InnoDB DEFAULT CHARSET=utf8
* Define primary keys
* If you create NOT NULL fields after the game has gone into production, make sure you took care of the database migration

'''Note''': if you use comments, then you must not do it in the same line as the code.

Example:

<pre>
`activated` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out the whole column `activated` BOOL, and that code will not be executed.

== PHP ==
Database initialization should be in the function setupNewGame() in 'gamename.game.php'.

Database schema migration should be in the function upgradeTableDb(), see below.

Warning: all CREATE/ALTER tables and views should be in dbmodel.sql. Do not call these queries from PHP to avoid implicit commits https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
which will cause issues. The only time you can do such queries from PHP is in the upgradeTableDb() method.

== Errors Log ==
To trace Database creation, check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game to production, then you should implement the upgradeTableDb() method, see [[Post-release phase#Updating the database schema|Updating the database schema after release]]

[[Category:Studio]]