Board Game Arena - User contributions [en]

Main game logic: Game.php

2026-09-30T13:22:58Z

Nalka: No reports in forums

{{Studio_Framework_Navigation}}

This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.

This is the main class that implements the "server" callbacks. As it is a server it cannot initiate any data communicate with the game client (running in browser) and only can respond to client using notifications.

Your php class instance won't be in memory between two callbacks, every time client send a request a new class will be created, constructor will be called and eventually your callback function.

'''Note:''' this file is now named Game.php, located in the modules/php directory. If you see it named yourgamename.game.php in the root dir, it's the legacy usage. In the legacy usage, the namepaces don't exists.

== File Structure ==

The details of how the file is structured are described directly with comments in the code skeleton provided to you.

Here is the basic structure:

* '''__construct''': the game constructor, where you define global variables and initiaze class members.
* '''setupNewGame''': initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.
* '''getAllDatas''': where you retrieve all game data during a complete reload of the game. Return value must be associative array. Value of 'players' is reserved for returning players data from players table, if you set it it must follow certain rules
$result ['players'] = $this->getCollectionFromDb("SELECT `player_id` `id`, `player_score` `score`, `player_no` `no`, `player_color` `color` FROM `player`");
// Returned value must include ['players'][$player_id]]['score'] for scores to populate when F5 is pressed.
getAllDatas accepts a magic parameter <code>int $currentPlayerId</code> (or <code>int $currentPlayerNo</code>) to fetch the information from the point of view of the current player id (or no). It should not have any other parameter.
* '''getGameProgression''': where you compute the game progression indicator. Returns a number indicating percent of progression (0-100). Used to calculate ELO changes of remaining players when a player quits, or as a conceding requirement (in non-tournament 2 player games, a player may concede if the progression is at least 50%).
* Utility functions: your utility functions.
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]).
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* '''initTable''': (not part of template) - this function is called for every php callback by the framework and it can be implement by the game (empty by default). You can use it in rare cases where you need to read database and manipulate some data before any ANY php entry functions are called (such as getAllDatas,action*,st*, etc). Note: it is not called before arg* methods
* '''zombieTurn''': what to do it's the turn of a zombie player.
* '''upgradeTableDb''': function to migrate database if you change it after release on production.
* '''getGameName''': returns the game name. This will be setup when you create the project. If you are copying files in from another project, make sure you keep this function intact. It must return the right game name, or lots of things will be broken.

== Accessing player information ==

'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!

; getPlayerCount() (or getPlayersNumber() that is an alias )
: Returns the number of players playing at the table
: Note: doesn't work in the beggining of setupNewGame (use count($players) instead). It will work after initialization of player table.

; <nowiki>getActivePlayerId(): string</nowiki>
: Get the "active_player", whatever what is the current state type.
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

; getActivePlayerName()
: Get the "active_player" name
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getPlayerNameById($player_id)
: Get the name by id

; getPlayerNameByNo($playerNo)
: Get the name by no

; getPlayerColorById($player_id)
: Get the color by id

; getPlayerNoById($player_id)
: Get 'player_no' (number) by id

; getPlayerIdByNo(int $playerNo) int
: Get the player id by player no.

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.
: The content of each value is:
: * player_name - the name of the player
: * player_color (ex: ff0000) - the color code of the player (as string)
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3

<pre>
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $info) {
$player_color = $info['player_color'];
...
}
</pre>
Note: if you want array of player ids only you can do this:
$player_ids = array_keys($this->loadPlayersBasicInfos());

; getCurrentPlayerId(bool $bReturnNullIfNotLogged = false) string
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).
: '''Be careful''': This is not necessarily the active player!
: In general, you shouldn't use this method. It is available as a magic param in act functions, and also in getAllDatas, and shouldn't be needed anywhere.
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(),
: otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).

; getCurrentPlayerName(bool $bReturnEmptyIfNotLogged = false) string
: Get the "current_player" name.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above). Can be easily replaced by $this->getPlayerNameById($currentPlayerId);

; getCurrentPlayerColor()
: Get the "current_player" color.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above). Can be easily replaced by $this->getPlayerColorById($currentPlayerId);

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above). Should never be needed, zombie players should behave like real players, and everything specific to zombie should be set in the zombie method only.

; isSpectator()
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).

For player score and tiebreaker, see [[Main game logic: Game.php#Manage player scores and Tie breaker]]

== Accessing the database ==

The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.

'''IMPORTANT'''

BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.

However there are sets of database operation that will do implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).

All methods below are part of game class (and view class) and can be accessed using $this->

; DbQuery( string $sql )
: This is the generic method to access the database.
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database. Returns result of the query.
: For SELECT queries, the specialized methods below are much better.
: Do not use method for TRUNCATE, DROP and other table altering operations. See disclamer above about implicit commits. If you really need TRUNCATE use DELETE FROM xxx instead.

; getUniqueValueFromDB( string $sql )
: Returns a unique value from DB or null if no value is found.
: $sql must be a SELECT query.
: Raise an exception if more than 1 row is returned.

; getCollectionFromDB( string $sql, bool $bSingleValue=false ) array
: Returns an associative array of rows for a sql SELECT query.
: The key of the resulting associative array is the first field specified in the SELECT query.
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.
: First column must be a primary or alternate key (semantically, it does not actually have to declared in sql as such).
: The resulting collection can be empty (it won't be null).
: If you specified $bSingleValue=true and if your SQL query requests 2 fields A and B, the method returns an associative array "A=>B", otherwise its A=>[A,B]
: Note: The name a bit misleading, it really return associative array, i.e. map and NOT a collection. You cannot use it to get list of values which may have duplicates (hence primary key requirement on first column). If you need simple array use getObjectListFromDB() method.

Example 1:
<pre>
$result = $this->getCollectionFromDB( "SELECT `player_id` `id`, `player_name` `name`, `player_score` `score` FROM `player`" );

Result:
[
1234 => [ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
1235 => [ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getCollectionFromDB( "SELECT `player_id` `id`, `player_name` `name` FROM `player`", true );

Result:
[
1234 => 'myuser0',
1235 => 'myuser1'
]

</pre>

; getNonEmptyCollectionFromDB(string $sql) array
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.

; getObjectFromDB(string $sql) array
: Returns one row for the sql SELECT query as an associative array or null if there is no result (where fields are keys mapped to values)
: Raise an exception if the query return more than one row (you can use LIMIT 1 in the query to avoid the exception)

Example:
<pre>
$result = $this->getObjectFromDB( "SELECT `player_id` `id`, `player_name` `name`, `player_score` `score` FROM `player` WHERE `player_id` = '$player_id'" );

Result:
[
'id'=>1234, 'name'=>'myuser0', 'score'=>1
]
</pre>

; getNonEmptyObjectFromDB(string $sql) array
: Similar to previous one, but raise an exception if no row is found

; getObjectListFromDB(string $sql, bool $bUniqueValue=false) array
: Return an array of rows for a sql SELECT query.
: The result is the same as "getCollectionFromDB" except that the result is a simple array (and not an associative array).
: The result can be empty.
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.

Example 1:
<pre>
$result = $this->getObjectListFromDB( "SELECT `player_id` `id`, `player_name` `name`, `player_score` `score` FROM `player`" );

Result:
[
[ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
[ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getObjectListFromDB( "SELECT `player_name` `name` FROM `player`", true );

Result:
[
'myuser0',
'myuser1'
]

</pre>

; getDoubleKeyCollectionFromDB(string $sql, bool $bSingleValue=false) array
: Return an associative array of associative array, from a SQL SELECT query.
: First array level correspond to first column specified in SQL query.
: Second array level correspond to second column specified in SQL query.
: If $bSingleValue = true, keep only third column on result

; DbGetLastId()
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).

; DbAffectedRow() int
: Return the number of row affected by the last operation

; escapeStringForDB(string $string) string
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used, '''as long as the SQL statement uses single quotes around the string. This is important!'''
''Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival. This function is only needed if you manage to get an unchecked string, like in the games where user has to enter text as a response.''
''Note: This function does not escape % and _ by default, which are wildcards if used in an SQL "LIKE" statement. The developer must determine if this is desirable behavior.''

Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.

== Use bga globals ==
Sometimes, you want a single global value for your game, and you don't want to create a DB table specifically for it.

You can do this with the BGA framework "globals". Your value will be stored in the "bga_globals" table in the database, and you can access it with simple methods.

The keys are strings, so you might want to store them in constants to avoid mistakes (the key must be at maximum 50 characters long).

The variable can be of any type (number, string, array, object) and will be stored as a JSON (so functions cannot be stored, and circular references on objects will trigger an Exception when storing).

Having a string key and a JSON serialization allows you to debug easily by looking at the bga_globals table content.

''Note: this globals module doesn't use cache, so every call to one of the following methods makes a DB request.''

'''bga->globals->set(string $name, $mixed $obj): void'''

Define the value of a global variable.
<pre>
const FIRST_PLAYER_ID = "firstPlayerId";
$this->bga->globals->set(FIRST_PLAYER_ID, array_keys($players)[0]);
</pre>

'''bga->globals->get(string $name, $mixed $defaultValue = null, ?string $class = null): mixed'''

Get the value of a global variable. Returns `null` if not set, except specified otherwise in the optional `$defaultValue`.
<pre>
$currentFirstPlayerId = $this->bga->globals->get(FIRST_PLAYER_ID);
...
$selectedCardsIds = $this->bga->globals->get(SELECTED_CARDS_IDS, []);
</pre>

You can specify the expected class type, if you save a class and don't want it returned as a stdClass.
<pre>
$undo = new Undo($playerId, $moves);
$this->bga->globals->set(UNDO, $undo);

$undo = $this->bga->globals->get(UNDO); // will return an stdClass
$undo = $this->bga->globals->get(UNDO, class: Undo::class); // will return an Undo class
</pre>
Note: your class should be a plain object with no mandatory constructor params. Example:
<pre>
class Undo {
public function __construct(
public ?int $playerId = null,
public ?array $moves = null,
) {}
}
</pre>

'''bga->globals->getAll(...$names): array'''

Get the value of all global variables, as a key=>value array. You can set a list of names to only get matching variables. In that case, non-existent keys will not be set in the returned array, so if you have a key with null value, it means the key has been set to null previously.
<pre>
$variables = $this->bga->globals->getAll();
...
$diceVariables = $this->bga->globals->getAll(DIE1, DIE2);
</pre>

Use with PHP's [https://www.php.net/extract extract()] function to quickly assign multiple variables:
<pre>
extract($this->bga->globals->getAll('endTime', 'hour', 'vipWelcome'));
// $endTime, $hour, and $vipWelcome (may) now exist

if (!empty($endTime)) {
...
</pre>

'''bga->globals->delete(...$names): void'''

Delete a global variable or a list of global variables stored in database.
<pre>
$this->bga->globals->delete(SELECTED_CARDS_IDS);
...
$this->bga->globals->delete(SELECTED_CARDS_IDS, UNDO, AFTER_DISCARD_RETURN_STATE);
</pre>

'''bga->globals->has(string $name): bool'''

Indicates if a global variable is stored in database.
<pre>
$cardSelectionIsStarted = $this->bga->globals->has(SELECTED_CARDS_IDS);
</pre>

'''bga->globals->inc(string $name, $int $inc): int'''

Increments the value of a global variable, and return the incremented value. Will trigger an exception if the variable is not a numeric value.
<pre>
$this->bga->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->bga->globals->inc(SPENT_COINS_IN_CURRENT_TURN, $cardCost);
</pre>

== Use globals (numbers only / game options) ==

Before the `$this->globals`, you could only store numeric values as globals. Theses "GameStateValues" are stored in the "global" table in the database, and you can access it with simple methods.

All methods below are members of the game class and should be accessed via $this->

'''initGameStateLabels(array $labelsMap): void'''

This method should be located at the beginning of constructor of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.

You can define up to 80 globals, with IDs from 10 to 89 (inclusive, there can be gaps).
Also you must use this method to access value of game options [[Game_options_and_preferences:_gameoptions.inc.php]], in that case, IDs need to be between 100 and 199.
You must '''not''' use globals outside the range defined above, as those values are used by other components of the framework.

<pre>
function __construct() {
parent::__construct();
$this->initGameStateLabels([
"my_first_global_variable" => 10,
"my_second_global_variable" => 11,
"my_game_variant" => 100
]);
// other code ...
}
</pre>

NOTE: The methods below WILL throw an exception if label is not defined using the call above.

'''setGameStateInitialValue( string $label, int $value ): void'''

Initialize global value. This is not required if you ok with default value if 0. This should be called from setupNewGame function.

'''getGameStateValue( string $label, int $default = 0): int'''

Retrieve the value of a global. Returns $default if global is not been initialized (by setGameStateInitialValue).

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->getGameStateValue('my_first_global_variable');
</pre>

'''setGameStateValue( string $label, int $value ): void'''

Set the current value of a global.
<pre>
$this->setGameStateValue('my_first_global_variable', 42);
</pre>

'''incGameStateValue( string $label, int $increment ): int'''

Increment the current value of a global. If increment is negative, decrement the value of the global.

Return the final value of the global. If global was not initialized it will initialize it as 0.

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->incGameStateValue('my_first_global_variable', 1);
</pre>

=== BGA predefined globals ===

BGA already defines some globals in the ''global'' database table. You should not change them directly, nor read them in your game code, but it can be useful to know what they mean when debugging:

{| class="wikitable"
|-
! global_id !! label !! Meaning
|-
| 1 || || Current state
|-
| 2 || || Active player id
|-
| 3 || next_move_id || Next move number
|-
| 4 || || Game id
|-
| 5 || || Table creator id
|-
| 6 || playerturn_nbr || Player turn number
|-
| 7 || gameprogression || Game progression
|-
| 8 || initial_reflexion_time || Initial reflection time
|-
| 9 || additional_reflexion_time || Additional reflection time
|-
| 200 || reflexion_time_profile || Game speed
Real-time games:
* 0 = Real-time • Fast paced
* 1 = Real-time • Normal speed
* 2 = Real-time • Slow speed
* 9 = No time limit • with friends only

Turn-based games:
* 10 = Fast Turn-based • 24 moves per day
* 11 = Fast Turn-based • 12 moves per day
* 12 = Fast Turn-based • 8 moves per day
* 13 = Turn-based • 4 moves per day
* 14 = Turn-based • 3 moves per day
* 15 = Turn-based • 2 moves per day
* 17 = Turn-based • 1 move per day
* 19 = Turn-based • 1 move per 2 days
* 20 = No time limit • with friends only
|-
| 201 || bgaranking_mode || Game mode
* 0 = Normal mode
* 1 = Friendly mode (no ELO)
* 2 = Arena mode
|-
| 207 || game_language ||GAMESTATE_GAME_LANG
|-
| 300 || game_db_version ||GAMESTATE_GAMEVERSION: Current version of the game (when in production)
|-
| 301 || game_result_neutralized ||GAMESTATE_GAME_RESULT_NEUTRALIZED
|-
| 302 || neutralized_player_id ||GAMESTATE_NEUTRALIZED_PLAYER_ID
|-
| 304 || undo_moves_stored ||GAMESTATE_UNDO_MOVES_STORED
|-
| 305 || undo_moves_player ||GAMESTATE_UNDO_MOVES_PLAYER
|-
| 306 || lock_screen_timestamp ||GAMESTATE_LOCK_TIMESTAMP
|}

== Game states and active players ==

=== Activate player handling ===

; $this->activeNextPlayer()
: Make the next player active in the natural player order.
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you must transition to a state in the action triggering this call, so the change of active player is notified to the front.

; $this->getActivePlayerId() string
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be GAME or MULTIPLE_ACTIVE_PLAYER
: Note: avoid using this method in a MULTIPLE_ACTIVE_PLAYER state because it does not mean anything.
: In general, you shouldn't use this method. It is available as a magic param in getArgs / onEnteringState / act functions, and shouldn't be needed anywhere else.

=== Multiple activate player handling ===

; $this->gamestate->setAllPlayersMultiactive()
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a MULTIPLE_ACTIVE_PLAYER state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away MULTIPLE_ACTIVE_PLAYER status immediately afterwards, use setPlayersMultiactive instead.)

Example of usage:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

; $this->stMakeEveryoneActive()
:this method can be used in state machine to make everybody active as "st" method of multiplayeractive state, it just calls $this->gamestate->setAllPlayersMultiactive()

This is to be used in state declaration:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => \clienttranslate('Other player must place ships'),
"descriptionmyturn" => \clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => MULTIPLE_ACTIVE_PLAYER,
'action' => 'stMakeEveryoneActive',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "actionBla" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>

; $this->gamestate->setAllPlayersNonMultiactive( $next_state )
: All playing players are made inactive. Transition to next state, by transition name or State class name.

; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.
: "players" is the array of player id that should be made active. If "players" is not empty the value of "next_state" will be ignored (you can put whatever you want)
: If "bExclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array

: In case "players" is empty, the method trigger the "next_state" transition, by transition name, state id, or State class name, to go to the next game state. It also allow a callable, returning one of the possible listed values.
: returns true if state transition happened, false otherwise

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.
: If this player was the last active player, the method trigger the "next_state" transition, by transition name, state id, or State class name, to go to the next game state. It also allow a callable, returning one of the possible listed values.
: returns true if state transition happened, false otherwise
Example of usage (see state declaration of playerTurnPlace above):
<pre>
function actionBla($args) {
$this->checkAction('actionBla');
// handle the action using $this->getCurrentPlayerId()
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');
}
</pre>

; $this->gamestate->getActivePlayerList()
: With this method you can retrieve the list of the active player at any time.
: During a GAME type gamestate, it will return a void array.
: During a ACTIVE_PLAYER type gamestate, it will return an array with one value (the active player id).
: During a MULTIPLE_ACTIVE_PLAYER type gamestate, it will return an array of the active players id.
: Note: you should only use this method in the latter case.

; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above. Next state param is a transition name, state id, or State class name. It also allow a callable, returning one of the possible listed values.
Example: you have player teams and you want to activate all players in one team
<pre>
$sql = "UPDATE `player` SET `player_is_multiactive` = '0'";
$this->DbQuery( $sql );
$sql = "UPDATE `player` SET `player_is_multiactive` = '1' WHERE `player_id` = '$player_id' AND `player_team` = '$team_no'";
$this->DbQuery( $sql );

$this->gamestate->updateMultiactiveOrNextState( 'error' );
</pre>

; updating database manually
: Use this helper function to change multiactive state without sending notification
<pre>
/**
* Changes values of multiactivity in db, does not sent notifications.
* To send notifications after use updateMultiactiveOrNextState
* @param number $player_id, player id <=0 or null - means ALL
* @param number $value - 1 multiactive, 0 non multiactive
*/
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {
if (! $value)
$value = 0;
else
$value = 1;
$sql = "UPDATE `player` SET `player_is_multiactive` = '$value' WHERE `player_zombie` = 0 and `player_eliminated` = 0";
if ($player_id > 0) {
$sql .= " AND `player_id` = $player_id";
}
$this->DbQuery($sql);
}
</pre>

;$this->gamestate->isPlayerActive($player_id)
:Return true if specified player is active right now.
:This method take into account game state type, ie nobody is active if game state is "game" and several players can be active if game state is "multiplayer"

;$this->bIndependantMultiactiveTable
:This flag can be set to true in constructor of game.php to force creation of second table to handle multiplayer states (normally these are in player table), this is very advanced feature.
:ONLY use it after you deploy you game to production if you receive unusual amount of bug report with dead lock symptoms DURING multiactiveplayer states
function __construct() {
...
$this->bIndependantMultiactiveTable=true;
}

=== States functions ===
; $this->gamestate->nextState( $transition )
: Change current state to a new state. Important: the $transition parameter is the name of the transition (or the state class name), and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.
:''with State classes, you should not need it and you can just return the class name of the next state.''

'''$this->gamestate->jumpToState($stateNum)'''
: Change current state to a new state. Important: the $stateNum parameter is the key of the state. See [[Your game state machine: states.inc.php]] for more information about states.
: Note: this is very advanced method, it should not be used in normal cases. Specific advanced cases include - jumping to specific state from "do_anytime" actions, jumping to dispatcher state or jumping to recovery state from zombie player function
:''with State classes, you should not need it and you can just return the class name of the next state.''

; $this->checkAction( $actionName, $bThrowException=true )
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions that are not using [[Main game logic: yourgamename.game.php#Actions (autowired)|Action autowiring]], in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.
:''With auto-wired actions, you should not need it.''

; $this->gamestate->checkPossibleAction( $action )
: (rarely used)
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.
: '''Note: This does NOT check either spectator or eliminated status, so those checks must be done manually.'''
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.

This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute this on client do not call checkAction on js side for this specific action.

function actUnpass(int $currentPlayerId) {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive([$currentPlayerId], 'error', false);
}

; $this->gamestate->getCurrentMainState()
: Returns the current main state, ignoring private parallel states.
: To get the state as an array, use <code>$this->gamestate->getCurrentMainState()->toArray()</code> and it will get a result similar to $this->gamestate->state()
: To get the state name, use <code>$this->gamestate->getCurrentMainState()->name</code>

; $this->gamestate->getCurrentMainStateClass()
: Returns the current main state class instance, ignoring private parallel states.

; $this->gamestate->getCurrentMainStateId()
: Returns the current main state id, ignoring private parallel states. (previously, it was the state_id() function, that returned the state numer as a string).

; $this->gamestate->getCurrentState(int $playerId)
: Returns the current state for a player. If the player is in private parallel state, it means the current private state for this player.
: To get the state as an array, use <code>$this->gamestate->getCurrentState($playerId)->toArray()</code>
: To get the state name, use <code>$this->gamestate->getCurrentState($playerId)->name</code>

; $this->gamestate->getCurrentStateClass(int $playerId)
: Returns the current state class instance for a player. If the player is in private parallel state, it means the current private state for this player.

; $this->gamestate->getCurrentStateId(int $playerId)
: Returns the current state id for a player. If the player is in private parallel state, it means the current private state for this player.

; $this->gamestate->isMultiactiveState()
: Return true if we are in MULTIPLE_ACTIVE_PLAYER state, false otherwise

=== Private parallel states ===

See the overview of private parallel states [[Your_game_state_machine:_states.inc.php#Private_parallel_states|here]].

; $this->gamestate->initializePrivateStateForAllActivePlayers()
: All active players in a multiactive state are entering a first private state defined in the master state's initialprivate parameter.
: Every time you need to start a private parallel states you need to call this or similar methods below.
: Note: at least one player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating some or all players
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method

$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

// in some cases you can move immediately some or all players to different private states
if ($someCondition) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("some_transition");
}

if ($other condition) {
//move single player to different state
$this->gamestate->nextPrivateState($specificPlayerId, "some_transition");
}
}
</pre>

; $this->gamestate->initializePrivateStateForPlayers($playerIds)
: Players with specified ids are entering a first private state defined in the master state initialprivate parameter.
: Same considerations apply as for the method above.

; $this->gamestate->initializePrivateState($playerId)
: Player with the specified id is entering a first private state defined in the master state initialprivate parameter.
: Everytime you need to start a private parallel states you need to call this or similar methods above
: Note: player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating that player
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function st_ChangeMind() {
// This player finished his move before, but now decides change something while other players are still active
// We activate the player and initialize his private state
$this->gamestate->setPlayersMultiactive([$this->getCurrentPlayerId()], "");
$this->gamestate->initializePrivateState(this->getCurrentPlayerId());

// It is also possible to move the player to some other specific state immediately
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->nextPrivateStateForAllActivePlayers($transition)
: All active players will transition to next private state by specified transition
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are, or be a state class name.
: Note: this method can run action or args methods of the target state
: Note: this is usually used after initializing the private state to move players to specific private state according to the game logic

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method
$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

if ($specificOption) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("some_transition");
}
}
</pre>

; $this->gamestate->nextPrivateStateForPlayers($playerIds, $transition)
: Players with specified ids will transition to next private state specified by provided transition, by transition name or State class name.
: Same considerations apply as for the method above.

; $this->gamestate->nextPrivateState($playerId, $transition)
: Player with specified id will transition to next private state specified by provided transition, by transition name or State class name.
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are.
: Note: this method can run action or args methods of the target state for specified player
: Note: this is usually used after some player actions to move to next private state

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->unsetPrivateStateForAllPlayers()
: All players private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used to clean up after leaving a master state in which private states were used, but can be used in other cases when we want to exit private parallel states and use a regular multiactive state for all players
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private states as they will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state after exiting private parallel states to avoid bugs.

Example of usage:
<pre>
function stNextRound() {
$this->gamestate->unsetPrivateStateForAllPlayers();
}
</pre>

; $this->gamestate->unsetPrivateStateForPlayers($playerIds, $transition)
: For players with specified ids private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used.
: Same considerations apply as for the method above.

; $this->gamestate->unsetPrivateState($playerId)
: For player with specified id private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used when deactivating player to clean up their parallel state
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private state as it will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state when not needed to avoid bugs.

Example of usage:
<pre>
function done() {
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), "newTurn" );
$this->gamestate->unsetPrivateState($this->getCurrentPlayerId());
}
</pre>

; $this->gamestate->setPrivateState($playerId, $newStateId)
: For player with specified id a new private state would be set
: Note: game needs to be in a master state which allows private parallel states
: Note: this should be rarely used as it doesn't check if the transition is allowed (it doesn't even specifies transition). This can be useful in very complex cases when standard state machine is not adequate (i.e. specific cards can lead to some micro action in various states where defining transitions back and forth can become very tedious.) NewStateId can also be a state class name.
: Note: this method can run action or args methods of the target state for specified player

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state

if ($playerHaveSpecificCard)
return $this->gamestate->setPrivateState($this->getCurrentPlayerId(), 35);

$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->getPrivateState($playerId)
: This return the private state or null if not initialized or not in private state

==== State Arguments in Private parallel states ====

The args method called for private states will have the player_id passed to it, allowing you to customise the arguments returned for that player.

Example of usage:
<pre>
function argMyPrivateState($player_id) {
return array(
'my_data' => $this->getPlayerSpecificData($player_id)
);
}
</pre>

==== Inactive Players ====

During Private Parallel State, active players will be managed by the private state that is current assigned to them.

Inactive players will be managed by the master MULTIPLE_ACTIVE_PLAYER state, so your client should respond to that state in order to display any status message advising players that they are waiting for others to have their turn, or to add any buttons that allow players to potentially "break in" and become active.

== Actions (autowired) ==
The action function should be prefixed by "act" and match the names specified in the "possibleactions" field on the state file.

If your actions start with "act", they will be autowired, that means you can declare action functions on the game.php file and call them directly from the front (with bgaPerformAction). You don't need to use action.php file anymore. The query param from the front request will be matched with the PHP variable of the same name, and it needs to be properly typed. This works for basic types: int, bool, float, string.

<pre>
public function actPlayCard(int $cardId) { ... }
</pre>
This function can be called from front-side with
<pre>
this.bgaPerformAction('actPlayCard', {
cardId: this.selectedCardId // the "cardId" param match the PHP variable name
});
</pre>

(Note: if you also declare the function in the action.php, it will be used instead of the autowiring)

Autowired action functions support the following "magic" parameters that will be automatically filled by the framework:

* <code>array $args</code> will be filled by current state's arguments (result of your <code>getArgs()</code> function)
* <code>int $activePlayerId</code> (or <code>int $active_player_id</code>) will be filled by the id of the active player. To be used on ACTIVE_PLAYER states only.
* <code>int $activePlayerNo</code> (or <code>int $active_player_no</code>) will be filled by the no of the active player. To be used on ACTIVE_PLAYER states only.
* <code>int $currentPlayerId</code> (or <code>int $current_player_id</code>) will be filled by the player id of the current player. To be used on MULTIPLE_ACTIVE_PLAYER and PRIVATE states only.
* <code>int $currentPlayerNo</code> (or <code>int $current_player_no</code>) will be filled by the player no of the current player. To be used on MULTIPLE_ACTIVE_PLAYER and PRIVATE states only.
* ''Note: unlike <code>getArgs()</code>, autowired actions do '''NOT''' support magic parameters <code>int $playerId</code>/<code>int $player_id</code> to refer to the current player. This inconsistency is probably a framework bug.''

If you want more complex types like int array or JSON, you'll need to specify it using the Param attributes. Same if the PHP variable name is different from the front query param, or if you want to specify the tests that should be realized on the parameter before calling the function.

=== Possible attributes ===

'''BoolParam(?string $name = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\BoolParam;

...

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raiseBet)

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raise) // NOTE: it's the same as actRaiseBet(bool $raise) if PHP var name and param name are the same
</pre>

'''IntParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntParam;

...

public function actPlayCard(#[IntParam(name: 'id')] int $cardId)

public function actSpendGold(#[IntParam(min: 1)] int $gold) // will trigger an exception if param is < 1

public function actPlaceCardOnSpot(int $cardId, #[IntParam(min: 1, max: 5)] int $spot) // will trigger an exception if spot is not in 1 to 5 range
</pre>

'''FloatParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''

Works the same way as IntParam, import is <code>use \Bga\GameFramework\Actions\Types\FloatParam;</code>

'''StringParam(?string $name = null, public ?bool $alphanum = false, public ?bool $alphanum_dash = false, public ?bool $base64 = false, public ?array $enum)'''
<pre>
use \Bga\GameFramework\Actions\Types\StringParam;

...

public function actSubmitWord(#[StringParam(alphanum: true)] string $word) // will trigger an exception if the word is not alphanum

public function actChooseAction(#[StringParam(enum: ['move', 'attack', 'pass'])] string $action) // will trigger an exception if the parameter doesn't match a value in the enum
</pre>
Note: You should do one of the tests of the attribute, or test it yourself on the function, to ensure the user is not sending forbidden characters to the function.

'''IntArrayParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntArrayParam;

...

public function actDiscardCards(#[IntArrayParam()] array $ids)

public function actDiscardCards(#[IntArrayParam(min: 2, max: 8)] array $ids) // will trigger an exception if the array length is not in the 2 to 8 range. It doesn't check the min/max of the array values!
</pre>

This function can be called from front-side with
<pre>
const selectedCardIds = [8, 12, 25];
this.bgaPerformAction('actDiscardCards', {
ids: selectedCardIds
});
</pre>

Note: if the array can be empty, type it as <code>#[IntArrayParam()] ?array</code> and consider null values as empty arrays.

'''JsonParam(?string $name = null, public ?bool $associative = true, public ?bool $alphanum = true)'''
<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...

public function actPlanComplexStuff(#[JsonParam()] array $answer) {} // force conversion to array during PHP json decode
public function actPlanComplexStuff(#[JsonParam(associative: false)] object $answer) {} // force conversion to object during PHP json decode

public function actPlanComplexStuff(#[JsonParam(associative: null)] mixed $answer) {} // default PHP json decode
</pre>

On client side:

const lala ={a: 2, b: "string", c: [1,2,4]};
this.bgaPerformAction("actPlanComplexStuff", {
answer: JSON.stringify(lala)
});

It's also possible to decode the Json to a PHP class, similar to what is done with $this->globals->get with class parameter.

<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...
class Answer {
public function __construct(
public int $a,
public string $b,
public array $c,
) {}
}
public function actPlanComplexStuff(#[JsonParam(class: Answer::class)] $answer) {} // specifying the class to map the json to
public function actPlanComplexStuff(#[JsonParam] Answer $answer) {} // same result, but the class is detected automatically by the framework thanks to the typed param.

public function actPlanMultipleComplexStuff(#[JsonParam(class: Answer::class)] array $answers) {} // can decode an array of Answer::class
</pre>

=== checkAction ===
The autowiring also triggers the checkAction, so you don't have to call it at the beginning of the function. If you need a function that should not trigger checkAction (an action that can be played during someone else turn), you can disable it this way:
<pre>
use \Bga\GameFramework\Actions\CheckAction;

#[CheckAction(false)]
public function actSetAutopass(bool $autopass) { ... }

#[CheckAction(false)]
public function actCancelChooseAction() {
$this->gamestate->checkPossibleAction('actCancelChooseAction');
...
}

</pre>

If you disable <code>checkAction</code>, you probably need to call <code>$this->gamestate->checkPossibleAction</code> instead at the beginning of your function. You likely also want to disable client checkAction calls implied by bgaPerformAction.

=== act prefix ===
The act prefix needed to activate the autowiring is not just to have some consistency in naming, it's also intended to protect your code. If we let autowired action to any function, a player may do a request to 'setPlayerScore' function, even if you never intended for it to be called front side, and it would allow almost undetectable cheating for anyone reading the code of your game.

== Players turn order ==

When table is created the "natural" player order is assigned to player at random, and stored in "read-only" field "player_no".
If you need to create a custom order you should never change natural order but have a separate data structure.
For example you can alter the players table to add another "custom_order" field, you can use state globals or you can use your natural board database,
to store meeple_color/position_location pair.
BGA currently does not provide any API to create/store custom player order.

'''getNextPlayerTable()'''

Return an associative array which associate each player with the next player around the table.

In addition, key 0 is associated to the first player to play.

Example: if three player with ID 1000, 2000 and 3000 are around the table, in this order, the method returns:
<pre>
array(
1000 => 2000,
2000 => 3000,
3000 => 1000,
0 => 1000
);
</pre>

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table. However there no 0 index here.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database
and have custom function to access it.

'''createNextPlayerTable( $players, $bLoop=true )'''

Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here.
If parmeter $bLoop is set to true then last player will points to first (creaing a loop), false otherwise.
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.

Note: This function '''DOES NOT''' change the order in database, it only creates a map using key/values as descibed.

Example of usage:
<pre>
function getNextPlayerTableCustom() {
$starting = $this->getStartingPlayer(); // custom function to get starting player
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player
return $this->createNextPlayerTable($player_ids, false); // create next player table in custom order
}
</pre>

<pre>
$table = $this->createNextPlayerTable([3000,2000,1000], false);

will return:
[
3000 => 2000,
2000 => 1000,
1000 => null,
0 => 3000
]
</pre>

== Notifications ==

To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.

'''IMPORTANT'''

Notifications are crutial part of BGA framework. Everything which players see, including all changes which happen on frontend (including setup), are done via notfications.

Some notifications are built into the framework, and others are custom, game specific notifications. Generally, you should not send or handle framework notifications, except exposed APIs.

Example of framework notifications:
* game setup (first time client connects to game)
* game state change
* active player change
Example of custom notifications:
* game piece moved
* player scored points

Notifications are queued, i.e. sent at the very end of the action, when it ends normally. It means that if you throw an exception for any reason (i.e: move is not allowed), no notifications will be sent to players.

Notification can be sent from the following functions (and transive calls):

* action handler (act* in State classes or Game.php). It is a MUST actually. At least one notification must be sent (but it includes state transition which sends it)
* game state transition (onEnteringState in State classes)
* setupNewGame (after player tables setup is finished)

Notification cannot be sent from the following:
* .view.php
* .action.php
* material.inc.php
* constructor of .game.php
* arg* methods of .game.php

There are conceptually two types of notification:
* public - sent to all clients who are listening - that includes all players in the table as well as spectators
* private - sent only to a single player

The bundle of notifications sent at the end of an action is considered a single "move" and the table's move counter increases.
If you are ONLY sending private notifications during action handling, they will not have an associated <code>move_id</code> (to avoid this, add simple public notification with empty message).
In the rare case that you want to change this behavior, you can apply some hackery described in [[BGA_Studio_Cookbook]]

Note: the total notification size is now limited to 128K. It seems a lot, but don't forget that notification are bundled and only send at the end of an action which also INCLUDES all game state transitions that follow.

The notifications are handled on JS side by subscribing to notifications (only do it for custom notifications!). See [Game_interface_logic:_yourgamename.js#Notifications]

Do not put HTML in the notifications. If you want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

=== Notify ===

'''bga->notify->all(string $notification_type,string | NotificationMessage $message,array $notification_args )'''

Send a notification to all players of the game and spectators (public).

* notification_type: A string that defines the type of your notification.

Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).

* message: A string that defines what is to be displayed in the game log.

You can use an empty string here (''). In this case, nothing is displayed in the game log.

Unless its empty, use "\clienttranslate" method to make sure string is translated.

You can use arguments in your $notification_log string, that refers to values defines in the "$notification_args" argument (see below).
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.

* notification_args: The arguments of your notifications, as an associative array.

This array will be transmitted to the game interface logic, in order the game interface can be updated.

Complete notify all example (from "Reversi"):

<pre>
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );
</pre>

You can see in the example above the use of the "\clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.

'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notify->player below.

'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.

'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments (except i18n, player_id and all arguments referenced in the message), are removed from these history notifications. If you need additional arguments in history notifications you can add special field <b>preserve</b> to notification arguments, like this:

<pre>
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y,
'preserve' => [ 'x', 'y' ]
) );
</pre>
In this example, fields x and y will be preserved when replaying history notification at the game load.

NOTE: The ONLY reason 'preserve' is useful if you have custom method to render notifications in game log which changes some text arguments into html (i.e. to insert the images instead of plain text). Do not use preserve "just in case" - it will only bloat the logs and make game load VERY slow.

'''Important''': If both public and private notifications are sent to the same player in the same action (AJAX call), they will initially appear in the log in the order in which they were called, but they are placed into the game log in the following order: All private notifications first, then all public notifications. This means that when the page is refreshed, or when a player loads an asynchronous game, if you have called any public notifications ''before'' the last private notification, they will appear out of order in the log.

==== Recursive Notifications ====

If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but
an array itself, which contains 'log' and 'args', i.e.

$this->bga->notify->all('message', clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec' => ['log' => '${token_name} #${token_number}',
'args'=> ['token_name' => \clienttranslate('Boo'), 'token_number' => $number, 'i18n' => ['token_name'] ]
]
]);

==== Sending private data to some players ====

Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X will get a private notification "You draw the Ace of Spades", so you want them to see a different message and get some private data.

You can use the <code>_private</code> arg to send private data to designated players, in a similar fashion of the onEnteringState <code>_private</code> flag. <code>_private</code> is an array that have the player id to send private information to, and the value if the different notification using NotificationMessage to send both the replacing log and the args that will be accessible on front side in args._private.

Example:
<pre>
use Bga\GameFramework\NotificationMessage;

(...)

$this->bga->notify->all('cardPicked', clienttranslate('${player_name} takes a secret card from the deck'), [
'playerId' => $playerId,
'player_name' => $this->getPlayerNameById($playerId),
'_private' => [
$playerId => new NotificationMessage(clienttranslate('You take ${_private.card_name} from the deck'), [
'card' => $card,
'card_name' => $this->getCardName($card),
'i18n' => ['card_name']
]),
],
]);
</pre>
Note that the message uses <code>${_private.card_name}</code> to access the data in the private args.

If you don't need to change the log, but only send private args, you can send an array of args instead of the NotificationMessage object.

If you add <code>_merge_private => true</code> next to <code>_private</code>, the private informations will be accessible in `args` instead of `args._private`.

If you want all your <code>_private</code> objects to be merged (state args and notif args), call <code>$this->bga->notify->alwaysMergePrivate();</code> in your Game constructor instead of adding the <code>_merge_private</code> flag on each arg.

==== Using player names ====

The variable for player name must be ${player_name} in order to be highlighted with the player color in the game log, it has to have matching 'player_id' argument in $notification_args. If you want a second player name in the log, name the variable ${player_name2} and $player_id2, etc. For the multiple player case, usage of player_id and player_name is not mandatory i.e. skipping to player_id1 and player_name1 is fine.

Special handling of arguments:
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.
* ${player_name1}, ${player_name2}, ${player_name3}, etc. work the same as above
In order for this to work you must pass corresponding player_idX AND player_nameX in args i.e.

$this->bga->notify->all(
'buyAndPassCard',
clienttranslate('${player_name} buys ${card_name} and passes it to ${player_name2}'),
[
'player_id' => $player1['id'],
'player_name' => $player1['name'],
'player_id2' => $player2['id'],
'player_name2' => $player2['name'],
...
]
);

Note: player_name is not translatable, never add it to i18n array

=== NotifyPlayer ===

'''bga->notify->player(int $player_id, string $notification_type, string | NotificationMessage $message, $notification_args )'''

Same as above, except that the notification is sent to one player only. The player must be the player at the game table.

This method should be used only if you send some private information to a player, NOT wanting to send a public notification at the same time for the same reason. See paragraph '''Sending private data to some players''' that should cover most of your need to send a private notif.

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. Since its a private notification it may be more appropriate to use "you" insted

$this->bga->notify->player($player_id,'message', clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->bga->notify->player($player_id,'message', clienttranslate('${player_name} draws ${card_name}'), [ 'player_name' => $this->getPlayerNameById($player_id), ... ]);

Note: Spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notify->all() for any notification that spectators should get.

=== Notification decorators ===

'''bga->notify->addDecorator(callable $fn)'''

Add a decorator function that will be called on notification args before each call of notify->all and notify->player. ''Note: it won't work with deprecated functions notifyAllPlayers and notifyPlayer.''

To avoid duplicating the code in your notification args, you can register decorators in your Game __construct function.
// in construct :
$this->bga->notify->addDecorator(fn(string $message, array $args) => $this->decoratePlayerNameNotifArg($message, $args));
// could also be written this (ugly) way : $this->bga->notify->addDecorator([$this, 'decoratePlayerNameNotifArg']);

// with the Utils functions
public function decoratePlayerNameNotifArg(string $message, array $args): array {
// if the notif message contains ${player_name} but it isn't set in the args, add it on args from $args['player_id']
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}
return $args;
}
With this example, you can call <code>$this->bga->notify->all("pass", clienttranslate('${player_name} passes'), [ "player_id" => $player_id ]);</code> and the front will receive the player_name arg along the player_id one.

You can also declare it as an inline function :
// in construct :
this->bga->notify->addDecorator(function(string $message, array $args) {
// if the notif message contains ${card_name} but it isn't set in the args, add it on args from $args['card']
// also set it up for translations by adding it to the i18n array
if (isset($args['card']) && !isset($args['card_name']) && str_contains($message, '${card_name}')) {
$args['card_name'] = $args['card']->name;
$args['i18n'][] = ['card_name'];
}
return $args;
});
With this example, you can call <code>$this->bga->notify->all("playCard", clienttranslate('${player_name} plays ${card_name}'), [ "player_id" => $player_id, card => $card ]);</code> and the front will receive the card_name arg with the flag to translate it.

=== Use player no in notifications ===

If you rely on player no in your game code, you can configure the notify object to handle player no instead of player id.

In that case, put this in your Game constructor:
'''bga->notify->useNo(true)'''

It means all calls to notify->player expect a player no as first parameter, and notify->all _private keys should also be player no. '''It must be done for all references in the Game, you cannot mix player id and player no in different calls.''' You can still send any data in the notification args, including player id and/or player no, the framework doesn't read them.

== Randomization ==

A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.

Here's are a list of techniques you should use in these situations, from the best to the worst.

=== Dice and bga_rand ===

'''\bga_rand( min, max )'''
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.

This is the preferred function you should use, because we are updating it when a better method is introduced.

As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.

In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).

Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".

=== Arrays ===

PHP's [https://www.php.net/array_rand array_rand()] and [https://www.php.net/shuffle shuffle()] functions are not cryptographically secure. Instead, the following code based on PHP's [https://www.php.net/random_int random_int()] provides a better method to choose a random key, value, or slice of an array. (the slice preserves keys)

<pre>
private function getRandomKey(array $array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomKey(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $key;
}
}

private function getRandomValue(array $array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomValue(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $value;
}
}

private function getRandomSlice(array $array, int $count)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomSlice(): Array is empty", E_USER_WARNING);
return null;
}
if ($count < 1 || $count > $size) {
trigger_error("getRandomSlice(): Invalid count $count for array with size $size", E_USER_WARNING);
return null;
}
$slice = [];
$randUnique = [];
while (count($randUnique) < $count) {
$rand = random_int(0, $size - 1);
if (array_key_exists($rand, $randUnique)) {
continue;
}
$randUnique[$rand] = true;
$slice += array_slice($array, $rand, 1, true);
}
return $slice;
}
</pre>

=== shuffle and cards shuffling ===

To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.

As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even if not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").

=== Other methods ===

Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.

== Game statistics ==

There are 2 types of statistics:
* a "player" statistic is a statistic associated to a player
* a "table" statistic is a statistic not associated to a player (global statistic for this game).

See [[Game statistics: stats.json]] to see how you define statistics for your game.

'''bga->tableStats->init(string|array $nameOrNames, int|float|bool $value)'''

'''bga->playerStats->init(string|array $nameOrNames, int|float|bool $value, bool $updateTableStat = false)'''

<i>previously : initStat( $table_or_player, $name, $value)</i>

Create a statistic entry with a default value.

This method must be called for each statistic of your game, in your setupNewGame method.
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using xxxStats->set or xxxStats->inc, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.

'$nameOrNames' is the name of your statistic, as it has been defined in your stats.inc.php file, or an array of those names.

'$value' is the initial value of the statistic.

'updateTableStat' for playerStats initiates the tableStats of the same name, so if you store for example 'playedTurns' in both 'table' and 'player' call only <code>bga->playerStats->init('playedTurns', 0, true)</code> and it will init for both 'table' and 'player'.

'''bga->tableStats->set(string $name, int|float|bool $value)'''

'''bga->playerStats->set(string $name, int|float|bool $value, int $player_id)'''

'''bga->playerStats->setAll(string $name, int|float|bool $value)''' (same as set, but for all players at once)

<i>previously : setStat( $value, $name, $player_id = null )</i>

Set a statistic $name to $value.

'''bga->tableStats->inc(string $name, int|float $delta)'''

'''bga->playerStats->inc(string $name, int|float $delta, int $player_id, bool $updateTableStat = false)'''

'''bga->playerStats->incAll(string $name, int|float $delta)''' (same as inc, but for all players at once)

<i>previously : incStat( $delta, $name, $player_id = null )</i>

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function, except you cannot increment boolean values. 'updateTableStat' will also inc the tableStats of the same name.

'''bga->tableStats->get(string $name): int|float|bool'''

'''bga->playerStats->get(string $name, int $player_id): int|float|bool'''

<i>previously : getStat( $name, $player_id = null )</i>

Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.

'''bga->playerStats->getAll(string $name): array'''

Returns the values for all players, as an associative array $player_id => $value

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...

During the game, you update player's score using $this->bga->playerScore. bga->playerScore is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

Examples:
<pre>

// +2 points to active player
$this->bga->playerScore->inc($activePlayerId, 2);

// Set score of active player to 5
$this->bga->playerScore->set($activePlayerId, 5);

</pre>

=== Tie breaker ===

Tie breaker is used when two players get the same score at the end of a game.

Tie breaker is using $this->bga->playerScoreAux. It is updated exactly like $this->bga->playerScore. bga->playerScoreAux is a [[PlayerCounter and TableCounter|PlayerCounter]], so it has the same methods.

Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.

When you are using "playerScoreAux" functionality, you must describe the formula to use in your gameinfos.jsonc file like this:

<pre>
"tie_breaker_description": "Describe here your tie breaker formula",
</pre>

This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.

Note: if you need to need you score_aux to be reverse (lowest value wins), please contact Studio support to get a solution.

See also [https://en.doc.boardgamearena.com/Game_meta-information:_gameinfos.jsonc#Multiple_tie_breaker_management Multiple Tie Breaker Management].

=== Reverse scoring and reverse tie-breaker ===

If your game has a reverse scoring (lowest value wins) or reverse tie-breaker (lowest tie-breaker wins), you need to set-up a GameResult object to tell BGA this specificity.

On your last state (usually EndScore.php), instead of returning 99 to go the end game, return a GameResult. returning a GameResult object in a State class will then go the end game.
<pre>
use Bga\GameFramework\GameResult\GameResult;
use Bga\GameFramework\GameResult\Player;

...

public function onEnteringState() {
...

$playersDb = $this->game->getCollectionFromDb("SELECT * FROM `player`");
$players = Player::fromPlayersDb($playersDb);
return GameResult::individualRanking($players, reverseScore: true);
}
</pre>
For reverse tie-breaker, it will be `reverseScoreAux: true`.

If your game has running tables with negative scores to handle reverse scoring and you want to use the reverse scoring, add this just before the return line:
<pre>
if ($this->bga->playerScore->getMin() < 0) {
foreach ($players as &$player) {
$player->score = -$player->score;
}
}
</pre>
So game started before the change will reverse the score (negative to positive) before creating the GameResult object.
And anywhere you change the score, you must continue the way it was started :
<pre>
$addedPoints = 3;
if ($this->bga->playerScore->getMin() < 0) {
$addedPoints = -$addedPoints;
}
$this->bga->playerScore->inc($playerId, $addedPoints);
</pre>
If there are negative score, the game will continue with negative scores, else it will continue with positive scores.

If your game always have the player score stored in the way it should be displayed, it's not necessary to send the players object, you can just use
<pre>
return GameResult::individualRanking(reverseScore: true);
</pre>

=== Result neutralization ===

when a player quits a running table, the results of the game will be neutralized (everyone has score set to 1, except the first quitter that will be at 0 and will be ranked last in addition to reputation drop). We cannot keep the ranking among the remaining players, as the quitter being replaced by a zombie might unbalance the rest of the game interaction, for example the player playing just after can get advantages with the situation.

For some games where there is almost no interaction between player, like some roll & write games, there is no real reason to neutralize the game results when a player quits. In that case, you can ask the Studio Support to activate the "Keep ranking on player quit" flag for your game. The zombie mode must be fully functional to allow the game to continue with leavers. Note that the BGA team might refuse to activate it, if it is considered the zombie player will unbalance the results of the remaining players.

When this flag is activated, a player quitting a game will still be penalized, but the ranking you set at the end of the game will stay, and the eliminated player(s) will have their score set to -1. It also means if a second player quits the game, he will also be penalized, because he has no reason to quit and can continue the game. If the game ends with 2 remaining players, it's now possible for one of them to concede.

To request this mode, click on "Contact us / Support" at the bottom of the page in Studio and then work through to a "My problem has not been solved" and then enter your request. The flag can be set independently in Studio and Production, so make sure to request it for both (unless you just want to experiment in Studio).

Note: the flag will fully work for games started AFTER activation. It may display incorrect messages for games started before the activation but players left after. For this reason, it's best to request it when going to alpha, else accept some strange bug reports about this situation, that will solve itself when all existing tables are started after the activation.

=== Co-operative game ===

To make everyone win/lose together in a full-coop game:

Add the following in gameinfos.jsonc :
"is_coop": 1, // full cooperative

Assign a score of zero to everyone if it's a loss.
Assign the same score > 0 to everyone if it's a win.

If your want to consider some positive scores as defeat, you need to set-up a GameResult object to tell BGA this specificity.

On your last state (usually EndScore.php), instead of returning 99 to go the end game, return a GameResult. returning a GameResult object in a State class will then go the end game.
<pre>
use Bga\GameFramework\GameResult\GameResult;
use Bga\GameFramework\GameResult\Player;

...

public function onEnteringState() {
...

// TODO fetch $playerScore
return GameResult::coop(score: $playerScore, win: $playerScore >= 10);
}
</pre>

=== Semi-coop ===

If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.

=== Only "winners" and "losers" ===

For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

In this case:
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.
* Add the following lines to gameinfos.jsonc:

<pre>
// 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": true,
</pre>

Werewolves and Coup are implemented like this, as you can see here:
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults

Adding this has the following effects:
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.

Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).

=== Solo ===

If game supports solo variant, a negative or zero score means defeat, a positive score means victory.

If your want to consider some positive scores as defeat, you need to set-up a GameResult object to tell BGA this specificity.

On your last state (usually EndScore.php), instead of returning 99 to go the end game, return a GameResult. returning a GameResult object in a State class will then go the end game.
<pre>
use Bga\GameFramework\GameResult\GameResult;
use Bga\GameFramework\GameResult\Player;

...

public function onEnteringState() {
...

// TODO fetch $playerScore and $automataScore
return GameResult::solo(score: $playerScore, win: $playerScore > $automataScore);
}
</pre>

=== Player elimination ===

In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.

This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").

Usage:

* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* Player to eliminate should NOT be active anymore at the end of the action that triggers the eliminatePlayer function.
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.

'''Important:''' this should not be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules), except if in the course of the game, the zombie player is eliminated according to the rules.

'''Important:''' If you eliminate the last player, make sure the action will end by going to the end game state. If it doesn't, BGA will jump straight to it, without calling your end score state or anything similar.

=== Player concede ===

It should be rarely needed, but if you absolutely need to run some code when a player concedes, you can create a function called onConcede in the Game class like this :
<pre>
function onConcede() {
$this->bga->notify->all('test', 'Something to do when the player concedes');
}
</pre>
If you want to get the conceder id:
<pre>
function onConcede($concederTeam) {
$this->bga->notify->all('test', 'Something to do when the player concedes '.$concederTeam->players[0]->id);
}
</pre>

Never change state on this function. It should be limited to computing stats or similar small stuff.

To not break the game end, any exception triggered by this function will be catched and simply logged, so make sure your code stay simple and never trigger an exception and it will be hard to detect!

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player in real time game. It does not affect turn based games.
: Standard extra time (when you don't pass $specific_time) depends on the speed of the game (small with "slow" game option, bigger with other options).
: You can also specify an exact time to add, in seconds, with the "specific_time" argument (rarely used). Using $specific_time is not recommended as this does not adjust for the game speed.
: Important Note: the total reflection time cannot be more than time allowed for the turn. So you can never make it 10 minutes if turn max is 3 min (the max is determined by game speed). As a consequence there is no point adding this at the begging of the turn of in game setup, it only matters after the action which does not lead to turn end (which is when this player becomes inactive).
: Note: standard extra time is automatically doubled for begginer

function actionBla($args) {
$this->checkAction('actionBla');
$playerId = (int)$this->getActivePlayerId();
$this->giveExtraTime($player_id);
// do some inter-turn action
$this->notifyAll(...);
// no state transition as this player did an action but stayed active
}

; '''$this->bga->tableOptions->isTurnBased(): bool'''
: Returns true if game is turn based
:
; '''$this->bga->tableOptions->isRealTime(): bool'''
: Returns true if game is in real time

== Undo moves ==

Please read our [[BGA Undo policy]] before.

'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:
'db_undo_support' => true

Note: if you deploy undo support after game is in production this will take into effect for new games only, old games will give user an error if user choses Undo action, but otherwise it should not affect them.

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matters if you transition to game state not to user state after), this may affect what you end up saving.

; function undoRestorePoint()
: Restore the situation previously saved as an "Undo save point".
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).

function actUndo() {
$this->undoRestorePoint();
return PlayTurn::class; // transition to single player state (i.e. beginning of player actions for this turn)
}

'''Important note''': if you are reading game state variable right after restore (without changing state first) it won't work properly as the global table cache is not automatically refreshed after undoRestorePoint(). So you should either change state immediately to refresh game state values, or use $this->gamestate->reloadState() to refresh the state. If you choose to do the latest, be aware that this will bring the state machine back to the state during which the save point snapshot has been taken using undoSavepoint().

=== Manually remove game logs ===
<strong style="color: red;">Only use it if you have custom undo and you fully understand how logs and replay works!</strong>

; $this->bga->logs->getCurrentMoveId()
: Returns the current move id, when doing an action, that should be stored along informations to undo.

; $this->bga->logs->remove(int $startMoveId)
: Remove all logs from a move id that was stored during an action using `getCurrentMoveId()`. <strong>The game should be in the exact same point as it was before the stored action!</strong>

Example:
<pre>
// in the action code, do all the action code, notify it, and store the custom undo
$this->bga->globals->set(UNDO_ACTION, new Undo(
movedTiles: $tiles,
moveId: $this->bga->logs->getCurrentMoveId(),
));

return ConfirmAction::class;
</pre>
<pre>
$undo = $this->bga->globals->get(UNDO_ACTION);
// in the undo action code, do all the revert action code, notify it, then remove the logs
$this->bga->logs->remove($undo->moveId);
// don't do any action/notif after removing the logs
return PlayAction::class;
</pre>

== Managing errors and exceptions ==

Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.

; throw new UserException(string|NotificationMessage $message)
: Base class to notify a user error
: You must throw this exception when a player wants to do something that they are not allowed to do.
: The error message will be shown to the player as a "red message".
: The error will be displayed to the player, as it's a UserException, the error message should be translated (with clientranslate(), and if there are args wrap them into a NotificationMessage)
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Note: if your IDE doesn't do it for you, you'll need to add <code>use Bga\GameFramework\UserException;</code> at the top of your file.

Example from Gomoku:
<pre>
throw new UserException(clienttranslate("There is already a stone on this intersection, you can't play there"));
</pre>
Example with translated UserException using args :
<pre>
throw new UserException(new NotificationMessage(clienttranslate('You must play a card bigger than ${min}'), ['min' => $minCardValue]));
</pre>

; throw new SystemException (string|NotificationMessage $message)
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.

; throw new VisibleSystemException (string|NotificationMessage $message)
: You must throw this exception when you detect something that is not supposed to happened in your code.
: The error message is shown to the user as an "Unexpected error", in order that he can report it.
: The error message is logged in BGA error logs.
: it should not be translated, as it's just to bring debug details to you when the player reports the issue.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". You must implement a Zombie that will handle the role of the leaver player

Read [[Zombie Mode|Zombie mode]] to get all details of the expected code.

== User preferences ==
'''$this->bga->userPreferences->get(int $playerId, int $prefId): ?int'''

Return the value of a user preference for a player. It will return the value currently selected in the select combo box, in the top-right menu.

== Player color preferences ==

BGA premium users may choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

''To test it, you can set your preferred color on your BGA Studio account.''

Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:

On your gameinfos.jsonc file, add the following lines :

// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.
"favorite_colors_support": true,

Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.

$gameinfos = $this->getGameinfos();
...
if ($gameinfos['favorite_colors_support'])
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()
$this->reloadPlayersBasicInfos();

The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.

Note that you must update the colors to indicate the colors available for your game.

Some important remarks:
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.

=== Custom color assignments ===
Some colors don't play nicely with BGA's color difference algorithm. If you receive feedback that colors are not well chosen, you can bypass the BGA algorithm by specifying a map from user preference colors to game colors.

For example, you may wish to assign BGA's blue to your game's baby blue: <code>"0000ff" /* Blue */ => "89CFF0",</code> whereas otherwise, a deep purple might be chosen instead. Just be sure that the assigned colors are also present in the <code>player_colors</code> array passed to <code>reattributeColorsBasedOnPreferences</code>, otherwise the assignment will be ignored.

To do this, implement this method in your <code>X.game.php</code> class.

Note: the user preference colors (the keys in the returned array) should not be modified, or the code may not work as expected. These are the colors players can choose between in their profile.
/**
* Returns an array of user preference colors to game colors.
* Game colors must be among those which are passed to reattributeColorsBasedOnPreferences()
* Each game color can be an array of suitable colors, or a single color:
* [
* // The first available color chosen:
* 'ff0000' => ['990000', 'aa1122'],
* // This color is chosen, if available
* '0000ff' => '000099',
* ]
* If no color can be matched from this array, then the default implementation is used.
*/
function getSpecificColorPairings(): array {
return array(
"ff0000" /* Red */ => null,
"008000" /* Green */ => null,
"0000ff" /* Blue */ => null,
"ffa500" /* Yellow */ => null,
"000000" /* Black */ => null,
"ffffff" /* White */ => null,
"e94190" /* Pink */ => null,
"982fff" /* Purple */ => null,
"72c3b1" /* Cyan */ => null,
"f07f16" /* Orange */ => null,
"bdd002" /* Khaki green */ => null,
"7b7b7b" /* Gray */ => null,
);
}

== Legacy games API ==

For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.

This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:
* keeping a player preference/settings (=> player preferences and game options should be used instead)
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.

You should use it for:
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.

Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:

try
{
$this->bga->legacy->setTeam( $my_data );
}
catch( \feException $e ) // \feException is a base class of \BgaSystemException and others...
{
if( $e->getCode() == FEX_legacy_size_exceeded )
{
// Do something here to free some space in Legacy data (ex: by removing some variables)
}
else
throw $e;
}

The keys may only contain letters and numbers, underscore seems not to be allowed.

; $this->'''bga->'''legacy->set(string $key, int $playerId, mixed $value, int $ttl = 365)
: ( deprecated alias: $this->storeLegacyData($player_id, $key, $data, $ttl = 365) )
: Store some data associated with $key for the given user / current game
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used
: in a future table with the same game.
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games.
: TTL is a time-to-live: the maximum, and default, is 365 days.
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)
: NOTICE: You can store some persistant data across all tables from your game using the specific player_id 0 which is unused. In such case, it's even more important to manage correctly the size of your data to avoid any exception or issue while storing updated data (ie. you can use this for some kind of leaderbord for solo game or contest)
: Note: This function cannot be called during game setup (will throw an error).

; $this->'''bga->'''legacy->get(string $key, int $playerId, mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData($player_id, $key) ⚠️ this alias was returning a JSON-encoded value, while the get function returns the real value )
: Get data associated with $key for the current game
: This data is common to ALL tables from the same game for this player, and persist from one table to another.
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible
: Note: you can use '%' in $key to retrieve all keys matching the given patterns

; $this->'''bga->'''legacy->delete(string $key, int $playerId)
: ( deprecated alias: $this->removeLegacyData($player_id, $key) )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; $this->'''bga->'''legacy->setTeam(mixed $value, int $ttl = 365)
: ( deprecated alias: storeLegacyTeamData( $data, $ttl = 365 ) )
: Same as storeLegacyData, except that it stores some data for the whole team within the current table and does not use a key
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.
: This is useful for games which are intended to be played several time by the same team.
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens

; $this->'''bga->'''legacy->getTeam(mixed $defaultValue = null)
: ( deprecated alias: $this->retrieveLegacyData() ⚠️ this alias was returning a JSON-encoded value, while the getTeam function returns the real value )
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; $this->'''bga->'''legacy->deleteTeam()
: ( deprecated alias: $this->removeLegacyTeamData() )
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

== Players text input and moderation ==
This section concerns only games where the players have to write some words to play: games based on words, like "Just one" or "Codenames".

Some players will use your game to write insults or profanities. As this is part of the game and not in the game chat, these words cannot be reported by players and moderated.

If you met the following situation:

* You are asking a player to type a text (word(s) or sentence)
* The player can enter any text (this is not a pre-selection or anything you can control)
* This text is visible by at least one other player

Then, you must use the following method:

'''function logTextForModeration( $player_id, $text )'''

player_id = player who write the text

text = text that has been written

This function will have no visible consequence for your game, but will allow players to report the text to moderators if something happens.

== Tournament API (🚧 Beta) ==

The Tournament API is meant only for tournament encounters. It lets you persist per‑player data within a tournament and access deterministic seeds shared by all encounters of a tournament step.

Do not use this for preferences or long‑term progression: if a table is not linked to a tournament, these requests will fail, and all tournament data is wiped when the tournament ends anyway.

You can use it for:
* enforcing tournament‑wide constraints (ex: keep the same deck across all rounds)
* deterministic setup shared across a tournament step (ex: generate the same map layout for all encounters in a step)
; $this->'''bga->'''tournament->isTournament()
: Returns true if this table is a tournament encounter.
: Use this to guard tournament‑only logic.
'''$this->bga->tournament->getInfo()'''

: Returns an associative array containing the tournament informations.
: Keys:
:* <code>id:</code> ID of the tournament
:* <code>name</code>: Name of the tournament
:* <code>championship_name</code>: Championship name if any
:* <code>tournament_parent_id</code> : ID of the parent tournament if any
:* <code>tournament_group</code> : BGA group associated to the tournament
:* <code>oot_options</code>: Out of Time players options (<code>no_kick</code>, <code>auto_kick</code>)
:* <code>avatar</code>: avatar ID

; $this->'''bga->'''tournament->getSeedInfo()
: Returns an associative array containing deterministic seeds for tournament encounters.
: Keys:
:* <code>tournament_seed</code>: stable across the whole tournament.
:* <code>step_seed</code>: stable across a tournament step (same for all encounters in that step).
:* <code>parent_tournament_seed</code>: stable across the parent tournament (the reference tournament for sub-tournaments of Groups Stage tournament mode).
:
: Note: This call is already guarded internally, no external call is made unless the table is a tournament encounter.

; $this->'''bga->'''tournament->storePlayerGameData(int $playerId, string $key, mixed $data)
: Store per‑player game data for the current tournament.
: Data is JSON‑encoded automatically.
: The cumulative size of all data stored for a player in a tournament (even over multiple keys) is limited to 64 KiB.
: Keys must be 1–16 characters and letters/numbers only.

; $this->'''bga->'''tournament->retrievePlayerGameData(int $playerId, string $key)
: Retrieve per‑player game data for the current tournament.
: If `$key` contains '%', returns an array of key => value pairs (or [] if no match).
: Otherwise, returns a single value (or null if no match).
: Returned values are JSON‑decoded automatically.

; $this->'''bga->'''tournament->removePlayerGameData(int $playerId, string $key)
: Remove per‑player game data for the current tournament.
: You can use '%' in `$key` to remove multiple entries at once.
: All tournament data is removed automatically when the tournament is finished.

== Language dependent games API ==

This API is used for games that are heavily language dependent. Two most common use cases are:
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)

If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages they speak.

There is a new property language_dependency in gameinfos.jsonc which can be set like this:
"language_dependency": false, //or if the property is missing, the game is not language dependent
"language_dependency": true, //all players at the table must speak the same language
"language_dependency": { "1": "en", "2": "fr", "3": "it" }, //1-based list of supported languages

In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.
; function getGameLanguage()
: Returns an index of the selected language as defined in gameinfos.jsonc.

Languages currently available on BGA are:
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)

== Debugging and Tracing ==

To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.

$this->debug("Ahh!");
$this->dump('my_var',$my_var);

See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.

'''static getBgaEnvironment(): string'''
:Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.

; '''$this->bga->tableOptions->getGameVersion(): int'''
: Returns the current game version

== Creating other classes ==

You can create other classes in the <code>modules/php</code> dir, next to your <code>Game.php</code> file.

If they are names following the PSR-4, they will be autoloaded by BGA (no require_once needed). This doesn't work for the "legacy way" (=<code>YourGameName.game.php</code> at the game root dir).

For example, writing <code>new ScoreManager()</code> in your Game file will try to load the class <code>ScoreManager</code> of namespace <code>Bga\Games\YourGameName</code> in <code>modules/php/ScoreManager.php</code>

Don't forget to add namespace <code>Bga\Games\YourGameName;</code> at the beginning of your module.

You can even put these classes in sublevels : the class <code>Bga\Games\YourGameName\Cards\StandardCard</code> will be automatically loaded if it is stored in <code>modules/php/Cards/StandardCard.php</code>

[[Category:Studio]]

BGA Code Sharing

2026-09-16T22:10:50Z

Nalka: /* Projects */

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW ; https://codepen.io/VictoriaLa/pen/JjZNezr
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode ; https://codepen.io/VictoriaLa/pen/QWBBbwz
|
|-
| Die: 8 sided
| https://codepen.io/VictoriaLa/pen/YzMPeGq
| code pen
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP <nowiki/> https://codepen.io/hoursgoby/pen/GRwQzxo
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout, zoom and navigation for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout just by using css
|-
! colspan="3" | Algorithms
|-
|Hex grid
|tapestry,Tumbleweed,gaia project,Gold West
|
|-
|Shortest path on hex grid
|memoir 44
| Dijkstra
|-
|Largest area on hex grid
|tapestry, ...
|
|-
|Largest area on square grid
|king domino, ...
|
|-
|Tetris pieces
|patchwork, ...
|Matrix manupations to rotate, flip and fit tetris pieces
|-
|Line of sights on hex grid
|memoir 44
|Find intersecting hexes on a line between two cells
|-
! colspan="3" | Alternative implementations of BGA modules
''Reminder: these are not official BGA components''
|-
|Scrollmap with zoom
|https://github.com/yansnow78/bga_scrollmap
|you can find it in cacao, ginkgopilis, sagani, bigmonster,dominoes, Carcassonne hunters and gatherers and many others. <nowiki>#</nowiki> improvements compare to scrollmap:
- add zoom capabilities

- add possibility to adjust pan delta to tile size when clicking on arrows

- allow zoom with scroll wheel. only allow zoom with wheel if alt or ctrl or shift are pressed by default. add possibility to select which key need to be pressed when zooming with wheel

- allow pan/scroll and pinch zoom on smartphone. only allow 2 fingers to start scrolling by default, one finger is for page scrolling

- make clickable area of buttons a bit bigger on smartphone

- improve animation between game board and player bards thanks to an animation_div

- add support to long click on buttons (continuous scroll or zoom or enlarge/reduce until button released)
|-
|Scrollmap Plus
|patchwork
|Implementation with some bugs fixed, improved drag support and ability to use only one direction (i.e. only horizontal like carousel). Found in modules/extscrollmap.js
|-
! colspan="3" | Assorted stuff
|-
|Help
|[https://github.com/thoun/bga-help/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-help/demo/index.html Demo] (visible on Knarr)
|Add floating help buttons at the bottom left corner of the screen

|}

== Projects ==

Add the game name, a link to repository and nickname of the developer on bga (same as used for dev forum), and short description. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] topic on github.

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
! COMMENT
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
| Examples of various game components and PHP stubs of framework code to make IDE happy
|-
| Vanilla Typescipt template (not a game)
| https://github.com/elaskavaia/bga-dojoless
| Victoria_La
| Project template for typescript and using minimal dojo, good for vscode - type checking, auto-complete, navigation
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
|BGA-boilerplate
|https://github.com/bga-devs/tisaac-boilerplate/
|Tisaac (and Vincentt ?)
|Main boilerplate with extended "basic" function and code structure
|-
|BGA Type Safe Template
|https://github.com/NevinAF/bga-ts-template
|NevinAF
|Full typing of all BGA Framework components.
|-
|Undo functionality
|https://github.com/Ginso/UndoFunctions
|Ginso
|Code for adding undo functionality that also allows undoing single actions and not just the whole turn.
Also contains a class that wraps DB functions and adds a parsing functionality for numbers, bools and json
|-
|bga-descriptors
|https://github.com/nalka0/bga-descriptors
|nalka
|Open source community's enhancements to BGA's description files (bga-framework.d.ts, each lib's .d.ts and _ide_helper.php)
|-
! GAME
! CODE LINK
! DEVELOPER
! COMMENT
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Abandon All Artichokes
| https://github.com/0-wiz-0/bga-abandonallartichokes
| __wiz__, rojomojo
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
|Big Monster
|https://github.com/nmatton/bigmonster
|nicotacotac
|-
| Bonsai
| https://github.com/PhilipDavis/BGA-Bonsai
| Philip Davis (pdw3)
| Action stack for client-side undo system; generator functions to model complex turn workflows; infinite hex grid with auto resizing; all data in a single JSON blob; animated scorepad
|-
| Canosa
| https://codeberg.org/halibut/Canosa
| junibegood
|-
|Cóatl
|https://github.com/AbelTiborToth/bga-coatl
|Doctor Neo Cortex
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
|Copenhagen
|https://github.com/JoeProgram/bga-copenhagen
|JoeProgram
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
|Deep Regrets
|https://github.com/JamesGames7/bga-deepRegrets
|JamesGames7
|-
|Dice Hospital : Emergency Roll
|https://github.com/firgon/dicehospitaler
|firgon
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Fled
| https://github.com/PhilipDavis/BGA-Fled
| Philip Davis (pdw3)
| All data in a single JSON blob
|-
|Flip Freighters
|https://github.com/joesimpson/bga-flipfreighters
|joesimpson (Jonathan2004)
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| For-Ex
| https://github.com/Fnordistan/forex
| AmadanNaBriona
|
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|
|-
|Gangsta!
|https://github.com/joesimpson/bga-gangsta
|joesimpson (Jonathan2004)
|git history only since V2 when I became maintainer
|-
|Goa
|https://github.com/joesimpson/bga-goa
|joesimpson (Jonathan2004)
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| In the Year of the Dragon (10th Anniversary Edition)
| https://github.com/Fnordistan/ityotd
| AmadanNaBriona
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| The Lady and the Tiger (Doors)
| https://github.com/Fnordistan/ladyandthetiger
| AmadanNaBriona
|-
|Linkage
|https://github.com/ShaPhi7/linkage
|ShaPhi7
|
|-
|Love Letter
|https://github.com/ShaPhi7/loveletter
|ShaPhi7
|
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|
|-
| Monster Lands
| https://github.com/JamesGames7/bga-monsterlands
| James_Games
|
|-
|Mythicals The Boardgame
|https://github.com/joesimpson/bga-mythicals
|joesimpson (Jonathan2004)
|
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
|Ninjan
|https://github.com/dorukkicikoglu/bga-ninjan
|fenadoruk
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
|Now Boarding
|https://github.com/quietmint/bga-nowboarding
|quietmint
|-
|Odin
|https://github.com/dorukkicikoglu/bga-odin
|fenadoruk
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| Perikles
| https://github.com/Fnordistan/perikles
| AmadanNaBriona
|
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|
|-
|Stigméria
|https://github.com/joesimpson/bga-stigmeria
|joesimpson (Jonathan2004)
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Tic Tac Match
| https://github.com/leocaseiro/bga-tictacmatch
| Leo Caseiro
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|
|-
|Winter
|https://github.com/joesimpson/bga-winter
|joesimpson (Jonathan2004)
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).

If it is not visible: a) it is private b) it is already published (use radio button to switch) c) it is an old game not developed on studio d) it is an old game which code should not be copied.

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

[[Category:Studio]]

BgaScoreSheet

2026-08-29T13:35:39Z

Nalka: Fix typo in playerPanel score update snippet

{{Studio_Framework_Navigation}}

== Overview ==
'''bga-score-sheet''' is a javascript component to help you display an animated score sheet at the end of the game.

To see how its work and access examples of source code (via browser dev tools) see
'''[https://x.boardgamearena.net/data/game-libs/bga-score-sheet/1.x/demo/index.html Demo]'''

For comprehensive API docs see
'''[https://x.boardgamearena.net/data/game-libs/bga-score-sheet/1.x/docs/index.html Doc]'''

== Usage ==
Load the lib:
<pre>
const BgaScoreSheet = await importEsmLib('bga-score-sheet', '1.x');
</pre>
This line should be placed on top of the JS file, before any class declaration.

Legacy way:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-score-sheet', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaScoreSheet) { // note that the index of `BgaScoreSheet` must match the index of the define array
</pre>

At the end of your game setup:
<pre>
this.scoreSheet = new BgaScoreSheet.ScoreSheet(
document.getElementById(`my-score-sheet`), // an empty div on your template to place the score sheet on
{
animationsActive: () => this.bga.gameui.bgaAnimationsActive(), // so the animation doesn't trigger on replay fast mode
playerNameWidth: 80,
playerNameHeight: 30,
entryLabelWidth: 120,
entryLabelHeight: 20,
classes: 'score-sheet-background',
players: gamedatas.players,
entries: [
{
property: 'conquest-cards',
label: _('Conquest cards'),
labelClasses: 'entries-label',
},
{
property: 'politics-cards',
label: _('Politics cards'),
labelClasses: 'entries-label',
},
{
property: 'diplomacy-cards',
label: _('Diplomacy cards'),
labelClasses: 'entries-label',
},
{
property: 'total',
label: _('Total'),
labelClasses: 'entries-label',
scoresClasses: 'total',
width: 80,
height: 40,
},
],
scores: gamedatas.endScores, // to defined if the game state is 99, else null, so the score displays directly on reload when the game is ended. If unset, the score sheet will be hidden by default.
onScoreDisplayed: (property, playerId, score) => { // if you want to do something when a score is revealed
if (property === 'total') {
this.bga.playerPanels.getScoreCounter(playerId).setValue(Number(score));
}
},
}
);
</pre>

On the notification sending the end score details (supposing you use bgaSetupPromiseNotifications for async notifs) :
<pre>
async notif_endScores(args: NotifEndScoresArgs) {
// setting scores will make the score sheet visible if it isn't already
await this.scoreSheet.setScores(args.endScores, {
startBy: this.bga.players.getCurrentPlayerId()
});
}
</pre>

The endScores object sent on the notification should look like this :
<pre>
function getEndScores(): array {
// this would be filled dynamically on your game, but should have the shape of this static example
$endScores = [
156463 => [ // key is player id
'conquest-cards' => 18, // the score code must match the entry name
'politics-cards' => 4,
'diplomacy-cards' => 12,
'total' => 34
],
278971 => [
'conquest-cards' => 31,
'politics-cards' => 7,
'diplomacy-cards' => 5,
'total'=> 41
],
];
return $endScores;
}

// on your end score state
function stEndScore(): void {
$this->bga->notify->all('endScores', '', [ 'endScores' => $this->getEndScores() ]);
}

// to display the end scores on refresh, when the game is already over
function getAllDatas(): array {
// all your setup here

$isEndScore = intval($this->gamestate->state_id()) >= ST_END_SCORE;
$result['endScores'] = $isEndScore ? $this->getEndScores() : null;
}
</pre>

== Versioning ==
The lib is using semver, so you can require 1.x to be sure to have the last fixes without risking a breaking change. Any breaking change will be noted on the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this lib, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-score-sheet/1.x/dist/bga-score-sheet.d.ts d.ts]''' file to put in on your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

== Changelog ==
'''1.0.0''': Initial version

[[Category:Studio]]

BgaCards

2026-08-25T15:26:27Z

Nalka: Adapt paragraph to removal of outdated incompatibility with deck

{{Studio_Framework_Navigation}}

== Overview ==
'''bga-cards''' is a javascript component to display cards.

The library will handle associated animations (moving between stocks, flipping or rotating the cards).

The game Frenchtarot is an example of usage (with JS), or Verso (with TypeScript).

Also https://en.doc.boardgamearena.com/Tutorial_hearts is now using bga-cards for tutorial game implementation.

To see how its work and access examples of source code (via browser dev tools) see
'''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/demo/index.html Demo]'''

For comprehensive API docs see
'''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/docs/index.html Doc]'''

== Usage ==
Load the library:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x'); // the library uses bga-animations so this is required!
const BgaCards = await importEsmLib('bga-cards', '1.x');
</pre>
This line should be placed on top of the JS file, before any class declaration.

Legacy way;
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-animations', '1.x'), // the library uses bga-animations so this is required!
getLibUrl('bga-cards', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaAnimations, BgaCards) { // note that the index of `BgaAnimations` must match the index of the define array
</pre>

In your game setup:
<pre>
// create the animation manager, and bind it to the `gameui.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});

// create the card manager
this.cardsManager = new BgaCards.Manager({
animationManager: this.animationManager,
type: 'mygame-card',
getId: (card) => card.id,
setupFrontDiv: (card, div) => {
div.style.background = 'blue';
this.bga.gameui.addTooltipHtml(div.id, `tooltip of ${card.type}`);
},
});
</pre>
Only set up an animation manager if you don't already have one, otherwise re-use the same one.

Example of usage:
<pre>
setup: function (gamedatas) {
// ...

// create the stock, in the game setup
this.cardStock = new BgaCards.LineStock(this.cardsManager, document.getElementById('card-stock'));
this.cardStock.addCards(gamedatas.cards); // cards should be something like [{ id: 1, type: 3, type_arg: 2, location: 'table', location_arg: 0 }]

}
notif_revealNewCards: async function(args) {
await this.cardStock.addCards(args.newCards); // similar form as above
}

</pre>

Look at the demo page and the demo source code for a list of all possibilities!

To see the source code with all the examples - use browser developer tools - source tab (from demo link).

== Random Observations ==

=== Sprite Markup ===
If you use the stock component, the card images won't work out of the box, you have to add sprite markup manually, it can be done easily in the card manager constructor:
setupFrontDiv: (card, div) => {
// ...
div.style.backgroundPositionX = `calc(100% / 14 * (${card.type_arg} - 2))`; // 14 is the number of columns in stock image minus 1
div.style.backgroundPositionY = `calc(100% / 3 * (${card.type} - 1))`; // 3 is the number of rows in stock image minus 1

If you prefer to use your own CSS, you can mark it up with data attributes instead (and do the positioning using CSS):
setupFrontDiv: (card, div) => {
div.dataset.type = card.type; // suit 1..4
div.dataset.typeArg = card.type_arg; // value 2..14

=== Card faces ===
This component supports two-faced cards, so you can do flip animations (mostly). To take advantage of that you have to define the card back also using setupBackDiv in the manager.
Beware that the function that defines what face is up is actually called isCardVisible (which is not confusing at all), and you redefine it to return a function which determines the side dynamically.
By default this function is defined as:
isCardVisible: (card) => card.type
which is also super non-intuitive. I suggest always defining a custom function for this (which will likely just be isCardVisible: () => true), except for something like BgaCards.Deck.

=== Void Stock ===
As of 1.0.7 VoidStock still lacks some animations such as shrink and fadeOut, however the same can be achieved without VoidStock by just providing animation settings in removeCards methods, i.e.:
await this.lineStock.removeCards(cards, {
fadeOut: true,
slideTo: $(`otherhand_${playerId}`),
});

=== Type casting from PHP Deck ===
You would think you can just use the database method to get cards from Deck and send this to the UI and use it in bga-cards? No, it's not that easy.

Some of the bga-cards methods, most notably BgaCards.sort, assume fields (such as 'type') are integers, but if sent by PHP, they are strings (even worse, sometimes strings and sometimes integers).
If this is the ONLY problem (i.e. sort) you can get away by making your own sort function, otherwise you would have to make an object converter and apply it to all objects sent from notifications and getAllDatas.
See the hearts tutorial for helper method examples (i.e. find the method remapToBgaCard).
=== Asynchronicity ===
It's not immediately obvious but many functions that add or remove cards are async (i.e. return Promise), that means not only do you have to wait (or chain) them if running one after another, you also have
to be aware of residual effects of promises when using these methods in setup(), onEnteringState() and so on.
For example addCards is async while setSelectableCards is not. So if you add cards to your "hand" in the setup method, and try to set what is selectable in onEnteringState - that won't work properly,
unless you also promisify the call to setSelectableCards using setTimeout.

== Versioning ==
The library is using semver, so you can require 1.x to be sure to have the latest fixes without risking a breaking change. Any breaking change will be noted in the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this library, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/dist/bga-cards.d.ts d.ts]''' file to put in your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

If your game class is not declared on the define callback, you will need to modify it with this trick (to avoid a "ReferenceError: BgaAnimations is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
getLibUrl('bga-animations', '1.x'),
getLibUrl('bga-cards', '1.x'),
],
function (dojo, declare, gamegui, BgaAnimations, BgaCards) {
(window as any).BgaAnimations = BgaAnimations; //trick
(window as any).BgaCards = BgaCards;
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.14''': more logs for card element not matching a card / accept keyed objects in addition to arrays on inputs

'''1.0.13''': fix all visible deck remove card

'''1.0.12''': fix duplication when adding a card to another slot of the same stock

'''1.0.11''': fix lastPlayedCardStyle that was not fully applied

'''1.0.10''': remove wrong required settings from GridStockSettings / demo of moving a card inside a slot stock with addCard / prevent selecting multiple times the same card programmatically / fix getLastPlayedCardStyle reading settings?.selectedCardStyle

'''1.0.9''': fix VoidStock.addCards signature

'''1.0.8''': fix slot & card selection override

'''1.0.7''': fix HandStock blinking for loose width container / fix wrong deck number on constructor / fix removeCard.fadeOut without slideTo

'''1.0.6''': fix autoPlace with VoidStock

'''1.0.5''': fix selection of parent card if it contains a child card

'''1.0.4''': fix error on emptyHandMessage not defined

'''1.0.3''': fix emptyHandMessage conflicting with sort

'''1.0.2''': fix selection style override

'''1.0.1''': Fix documentation

'''1.0.0''': Initial version

[[Category:Studio]]

BgaCards

2026-08-25T15:24:17Z

Nalka: bga-cards supports non-array input since 1.0.14

{{Studio_Framework_Navigation}}

== Overview ==
'''bga-cards''' is a javascript component to display cards.

The library will handle associated animations (moving between stocks, flipping or rotating the cards).

The game Frenchtarot is an example of usage (with JS), or Verso (with TypeScript).

Also https://en.doc.boardgamearena.com/Tutorial_hearts is now using bga-cards for tutorial game implementation.

To see how its work and access examples of source code (via browser dev tools) see
'''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/demo/index.html Demo]'''

For comprehensive API docs see
'''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/docs/index.html Doc]'''

== Usage ==
Load the library:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x'); // the library uses bga-animations so this is required!
const BgaCards = await importEsmLib('bga-cards', '1.x');
</pre>
This line should be placed on top of the JS file, before any class declaration.

Legacy way;
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-animations', '1.x'), // the library uses bga-animations so this is required!
getLibUrl('bga-cards', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaAnimations, BgaCards) { // note that the index of `BgaAnimations` must match the index of the define array
</pre>

In your game setup:
<pre>
// create the animation manager, and bind it to the `gameui.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});

// create the card manager
this.cardsManager = new BgaCards.Manager({
animationManager: this.animationManager,
type: 'mygame-card',
getId: (card) => card.id,
setupFrontDiv: (card, div) => {
div.style.background = 'blue';
this.bga.gameui.addTooltipHtml(div.id, `tooltip of ${card.type}`);
},
});
</pre>
Only set up an animation manager if you don't already have one, otherwise re-use the same one.

Example of usage:
<pre>
setup: function (gamedatas) {
// ...

// create the stock, in the game setup
this.cardStock = new BgaCards.LineStock(this.cardsManager, document.getElementById('card-stock'));
this.cardStock.addCards(gamedatas.cards); // cards should be something like [{ id: 1, type: 3, type_arg: 2, location: 'table', location_arg: 0 }]

}
notif_revealNewCards: async function(args) {
await this.cardStock.addCards(args.newCards); // similar form as above
}

</pre>

Look at the demo page and the demo source code for a list of all possibilities!

To see the source code with all the examples - use browser developer tools - source tab (from demo link).

== Random Observations ==

=== Sprite Markup ===
If you use the stock component, the card images won't work out of the box, you have to add sprite markup manually, it can be done easily in the card manager constructor:
setupFrontDiv: (card, div) => {
// ...
div.style.backgroundPositionX = `calc(100% / 14 * (${card.type_arg} - 2))`; // 14 is the number of columns in stock image minus 1
div.style.backgroundPositionY = `calc(100% / 3 * (${card.type} - 1))`; // 3 is the number of rows in stock image minus 1

If you prefer to use your own CSS, you can mark it up with data attributes instead (and do the positioning using CSS):
setupFrontDiv: (card, div) => {
div.dataset.type = card.type; // suit 1..4
div.dataset.typeArg = card.type_arg; // value 2..14

=== Card faces ===
This component supports two-faced cards, so you can do flip animations (mostly). To take advantage of that you have to define the card back also using setupBackDiv in the manager.
Beware that the function that defines what face is up is actually called isCardVisible (which is not confusing at all), and you redefine it to return a function which determines the side dynamically.
By default this function is defined as:
isCardVisible: (card) => card.type
which is also super non-intuitive. I suggest always defining a custom function for this (which will likely just be isCardVisible: () => true), except for something like BgaCards.Deck.

=== Void Stock ===
As of 1.0.7 VoidStock still lacks some animations such as shrink and fadeOut, however the same can be achieved without VoidStock by just providing animation settings in removeCards methods, i.e.:
await this.lineStock.removeCards(cards, {
fadeOut: true,
slideTo: $(`otherhand_${playerId}`),
});

=== Type casting from PHP Deck ===
You would think you can just use the database method to get cards from Deck and send this to the UI and use it in bga-cards? No, it's not that easy.

Two problems:

1) Some of the bga-cards methods, most notably BgaCards.sort, assume fields (such as 'type') are integers, but if sent by PHP, like in the example above, they are strings (even worse, sometimes strings and sometimes integers).
If this is the ONLY problem (i.e. sort) you can get away by making your own sort function, otherwise you would have to make an object converter and apply it to all objects sent from notifications and getAllDatas.
See the hearts tutorial for helper method examples (i.e. find the method remapToBgaCard).
=== Asynchronicity ===
It's not immediately obvious but many functions that add or remove cards are async (i.e. return Promise), that means not only do you have to wait (or chain) them if running one after another, you also have
to be aware of residual effects of promises when using these methods in setup(), onEnteringState() and so on.
For example addCards is async while setSelectableCards is not. So if you add cards to your "hand" in the setup method, and try to set what is selectable in onEnteringState - that won't work properly,
unless you also promisify the call to setSelectableCards using setTimeout.

== Versioning ==
The library is using semver, so you can require 1.x to be sure to have the latest fixes without risking a breaking change. Any breaking change will be noted in the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this library, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/dist/bga-cards.d.ts d.ts]''' file to put in your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

If your game class is not declared on the define callback, you will need to modify it with this trick (to avoid a "ReferenceError: BgaAnimations is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
getLibUrl('bga-animations', '1.x'),
getLibUrl('bga-cards', '1.x'),
],
function (dojo, declare, gamegui, BgaAnimations, BgaCards) {
(window as any).BgaAnimations = BgaAnimations; //trick
(window as any).BgaCards = BgaCards;
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.14''': more logs for card element not matching a card / accept keyed objects in addition to arrays on inputs

'''1.0.13''': fix all visible deck remove card

'''1.0.12''': fix duplication when adding a card to another slot of the same stock

'''1.0.11''': fix lastPlayedCardStyle that was not fully applied

'''1.0.10''': remove wrong required settings from GridStockSettings / demo of moving a card inside a slot stock with addCard / prevent selecting multiple times the same card programmatically / fix getLastPlayedCardStyle reading settings?.selectedCardStyle

'''1.0.9''': fix VoidStock.addCards signature

'''1.0.8''': fix slot & card selection override

'''1.0.7''': fix HandStock blinking for loose width container / fix wrong deck number on constructor / fix removeCard.fadeOut without slideTo

'''1.0.6''': fix autoPlace with VoidStock

'''1.0.5''': fix selection of parent card if it contains a child card

'''1.0.4''': fix error on emptyHandMessage not defined

'''1.0.3''': fix emptyHandMessage conflicting with sort

'''1.0.2''': fix selection style override

'''1.0.1''': Fix documentation

'''1.0.0''': Initial version

[[Category:Studio]]

Game interface stylesheet: yourgamename.css

2026-08-23T15:30:29Z

Nalka: Dark mode is now live + fix typos

{{Studio_Framework_Navigation}}

__TOC__

This is the CSS stylesheet of your game User Interface.

Styles defined on this file will be applied to the HTML elements you define in your HTML template (yourgame_yourgame.tpl), and to HTML elements you create dynamically with Javascript.

Usually, you are using CSS to:

1°) define the overall layout of your game
(ex: place the board on the top left, place player's hand beside, place the deck on the right, ...).

2°) create your CSS-sprites:
All images of your games should be gathered into a small number of image files. Then, using background-image and background-position CSS properties, you create HTML blocks that can display these images correctly.

Example:
<pre>
Example of CSS sprites (a black token and a white token, 20x20px each, embedded in the same "tokens.png" 40x20px image):

.white_token {
background-image: url('img/tokens.png');
background-position: 0px 0px;
}
.black_token {
background-image: url('img/tokens.png');
background-position: -20px 0px;
}
.token {
width: 20px;
height: 20px;
background-repeat: none;
}
</pre>

3°) ... anything else:

It is really easy to add and remove CSS classes dynamically from your Javascript with dojo.addClass and dojo.removeClass. It is also easy to check if an element has a class (dojo.hasClass) or to get all elements with a specific class (dojo.query).

This is why, very often, using CSS classes for the logic of your user interface allow you to do complex things easily.

Note: on the production platform, this file will be compressed and comments will be removed. Consequently, don't hesitate to put as many comments as necessary.

Important: ALL the CSS directives for your game must be included in this CSS file. You can't create additional CSS files and import them.

== Warning: using percentage in background-position ==

In the example above, you will see "background-position: -20px 0px;" is used for the black token. You could also write this as "background-position: -100% 0%;" which displays the image at the same offset, because it is relative to the size of the .token bounding box, and this means the size of your image file doesn't need to precisely match the size of objects on the screen (this can be easier to write, and you can also substitute different image files without having to rewrite all the css.) However, it is strongly recommended that if you do this, you also specify <code>background-size</code> as a percentage as well.

This is because, if the size of the div on screen after any further scaling - which is done for you by the framework to fit games into small windows - is not a whole integer number of pixels, then rounding must occur at some points in the calculation; if the background-size and background-position are calculated in different ways, the difference in rounding can result int the final image offsets being incorrect. This is most significant on Safari (on MacOS, iPhone and iPad) where the discrepancy can be substantial enough to make a game ''illegible''; but other browsers can be off by a few pixels as well. [https://jsfiddle.net/shadowphiar/yLq36mzt/ (external demo)]. To avoid this issue, either:

* choose one unit (pixels, em, percentages etc) and specify '''all''' the background-size and background-position offsets of a div in the same unit.
* adjust the size of your div so that, after any global scaling (this.gameinterface_zoomFactor), it will occupy an integer number of pixels on the screen.

== Warning: using Z-index ==

You may use z-index CSS property in your game interface, but you should pay attention to the following: BGA dialogs are displayed with a z-index of 950. If you want to use z-index safely, you should use value '''lower than 900'''.

About z-index: don't forget that if you are using a z-index, your element will be displayed above all elements that do not have a z-index. So it's no use to have big z-index values: 1 is enough most of the time :)

== Warning: using drop-shadow ==

Drop shadows can look nice, but they currently cause big performance issues on Safari, especially if you have more than 1 on the page at once. To ensure you don't cause issues on this browser, you have some alternatives.

* Use box-shadow instead. This only works for square drop-shadows.
* Bake the shadow into the image. That is, the png contains the shadow, and no shadow is needed on the css side. This only works when the shadow doesn't need to be dynamic.
* Disable drop-shadow in Safari:, using the <code>dj_safari</code> class which is automatically added to the <code>html</code> tag.

.game-element {
filter: drop-shadow(3px 3px 4px rgba(0,0,0,0.7));
}

html.dj_safari .game-element {
filter: none;
}

== Tip: how to make your cards looks beautiful :) ==

This piece of CSS (to adapt to your needs) is adding rounded corners + a shadow to your card.

<pre>
border-radius: 10px;
border: 1px black solid;
box-shadow: 5px 5px 5px 0px rgba(0,0,0,0.4);
</pre>

== spectatorMode ==

When a spectator (= a player that is not part of the game) is viewing a game, the BGA framework add the CSS class "spectatorMode" to the wrapping HTML tag of your game.

This way, if you want to apply a special style to some elements of your game for spectators, you can do this in your CSS:

<pre>
.spectatorMode #your_element_id {
/* your special style */
}
</pre>

The most common usage of this is to hide some elements to spectators. For example, to hide "my hand" elements:

<pre>
.spectatorMode #my_hand {
display: none;
}
</pre>

== Support of the Dark mode ==
BGA supports Dark mode natively, it can toggled available by clicking on your avatar before starting a game or the hamburger menu (top-right corner) during a game. It adds a <code>[data-theme="dark"]</code> to the html tag if the dark mode is enabled. So if you want to support the dark mode, you can use this to override the default light style when the user wants dark mode.
<pre>
html {
background: url('img/light-background.jpg'), #f2f2f2;
}
html[data-theme="dark"] {
background: url('img/dark-background.jpg'), #1d1d1d;
}
/* Example to change the player panel color, for light mode only */
html[data-theme="light"] .player-board {
--game-bga-player-panel-background: white;
}
</pre>

It is better to use this instead of using <code>@media (prefers-color-scheme: dark) {</code> because the media query would always rely on the browser settings, ignoring the BGA toggle.

If you don't have a specific image for the dark mode, you can try this:
<pre>
html[data-theme="dark"] {
background-blend-mode: color-burn;
}
</pre>
Using the DevTool, try the different values of this property to find the one that would work best with your base image.

=== Migrating ===

Most games work in dark mode out of the box. The usual problem is if the game sets a fixed (light) background color for an element without setting the text color: it works great in light mode, but in dark mode it will have a light text color on a light background. Adding <code>color: black;</code> on the elements you put a fixed light background will fix it on dark mode while still work in light mode.

=== Using the work of the extension to migrate ===
For those using the [https://en.doc.boardgamearena.com/ChromeExtension BGA extension] , it already overrides the [data-theme] based on the user choice in the extension.

If you wish to manage your game's dark mode, you can look at the source code of the extension https://github.com/FlavienBusseuil/bga-chrome-extension/tree/main/src/css/games to obtain the css currently applied to your game by the extension, so you can integrate it on your game code to make it available to any player even without the extension. This will make your game compatible with the dark mode, even if they don't have the extension.

=== Example of a background option compatible with dark mode ===
If you have a light and a dark background, and you want an automatic setting to be based on the dark mode, you can add this as a user preference :
<pre>
"103": {
"name": "Background",
"values": {
"0": {
"name": "Automatic"
},
"1": {
"name": "Light"
},
"2": {
"name": "Dark"
}
},
"default": 0
}
</pre>

Then in the CSS:
<pre>
html[data-background="0"][data-theme="light"], html[data-background="1"] {
background: url('img/background-light.jpg');
}
html[data-background="0"][data-theme="dark"], html[data-background="2"] {
background: url('img/background-dark.jpg');
}
</pre>

If you have <code>this.bga.userPreferences.onChange = (prefId, prefValue) => this.onUserPreferenceChanged(prefId, prefValue);</code> or something similar in the setup, you can add this extract to the callback (remove the typing in the function signature if you're not using TS), so the html[data-background] updates as soon as the user preference changes:
<pre>
public onUserPreferenceChanged(prefId: number, prefValue: number) {
switch (prefId) {
case 103:
document.documentElement.dataset.background = `${prefValue}`;
break;
}
}
</pre>

[[Category:Studio]]

BgaDice

2026-07-30T10:55:52Z

Nalka: Fix typo Demo VS Doc

{{Studio_Framework_Navigation}}

== Overview ==
'''bga-dice''' is a javascript component to display dice.

The lib will handle associated animations (roll animation, moving between stocks).

To see how its work and access examples of source code (via browser dev tools) see
'''[https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/docs/index.html Demo]'''

For comprehensive API docs see
'''[https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/demo/index.html Doc]'''

== Usage ==
Load the lib:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x'); // the library uses bga-animations so this is required!
const BgaDice = await importEsmLib('bga-dice', '1.x');
</pre>
This line should be placed on top of the JS file, before any class declaration.

Legacy way;
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-animations', '1.x'), // the lib uses bga-animations so this is required!
getLibUrl('bga-dice', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaAnimations, BgaDice) { // note that the index of `BgaAnimations` must match the index of the define array
</pre>

In your game setup:
<pre>
// create the animation manager, and bind it to the `gameui.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});

// create the dice manager
this.diceManager = new BgaDice.Manager({
animationManager: this.animationManager,
type: 'my-game-die',
});
</pre>
Only setup an animation manager if you don't already have one, else re-use the same one.

Example of usage:
<pre>

// create the stock, in the game setup
this.dieStock = new BgaDice.LineStock(this.diceManager, document.getElementById('dice-stock'));
this.dieStock.addDice(gamedatas.dice); // dice should be something like [{ id: 1, face: 5, location: 'table' }]

async notif_rollDice(args) {
await this.dieStock.rollDice(args.rolledDice); // similar form as above, but with a different face value.
}

</pre>

Look at the demo page and the demo source code for a list of all possibilities!

== Versioning ==
The lib is using semver, so you can require 1.x to be sure to have the last fixes without risking a breaking change. Any breaking change will be noted on the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this lib, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/dist/bga-dice.d.ts d.ts]''' file to put in on your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

If your game class is not declared on the define callback, you will need to modify it with this trick (to avoid a "ReferenceError: BgaAnimations is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock",
getLibUrl('bga-animations', '1.x'),
],
function (dojo, declare, gamegui, counter, stock, BgaAnimations) {
(window as any).BgaAnimations = BgaAnimations; //trick
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.2''': more logs for dice element not matching a card / accept keyed objects in addition to arrays on inputs

'''1.0.1''': Fix documentation

'''1.0.0''': Initial version

[[Category:Studio]]

BgaCards

2026-01-05T18:46:43Z

Nalka: Fix typo (extra dot) in setup snippet

{{Studio_Framework_Navigation}}

== Overview ==
'''bga-cards''' is a javascript component to display cards.

The library will handle associated animations (moving between stocks, flipping or rotating the cards).

The game Frenchtarot is an example of usage (with JS), or Verso (with TypeScript).

Also https://en.doc.boardgamearena.com/Tutorial_hearts is now using bga-cards for tutorial game implementation.

To see how its work and access examples of source code (via browser dev tools) see
'''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/demo/index.html Demo]'''

For comprehensive API docs see
'''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/docs/index.html Doc]'''

== Usage ==
Load the library:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x'); // the library uses bga-animations so this is required!
const BgaCards = await importEsmLib('bga-cards', '1.x');
</pre>

Legacy way;
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-animations', '1.x'), // the library uses bga-animations so this is required!
getLibUrl('bga-cards', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaAnimations, BgaCards) { // note that the index of `BgaAnimations` must match the index of the define array
</pre>

In your game setup:
<pre>
// create the animation manager, and bind it to the `gameui.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});

// create the card manager
this.cardsManager = new BgaCards.Manager({
animationManager: this.animationManager,
type: 'mygame-card',
getId: (card) => card.id,
setupFrontDiv: (card, div) => {
div.style.background = 'blue';
this.bga.gameui.addTooltipHtml(div.id, `tooltip of ${card.type}`);
},
});
</pre>
Only set up an animation manager if you don't already have one, otherwise re-use the same one.

Example of usage:
<pre>
setup: function (gamedatas) {
// ...

// create the stock, in the game setup
this.cardStock = new BgaCards.LineStock(this.cardsManager, document.getElementById('card-stock'));
this.cardStock.addCards(gamedatas.cards); // cards should be something like [{ id: 1, type: 3, type_arg: 2, location: 'table', location_arg: 0 }]

}
notif_revealNewCards: async function(args) {
await this.cardStock.addCards(args.newCards); // similar form as above
}

</pre>

Look at the demo page and the demo source code for a list of all possibilities!

To see the source code with all the examples - use browser developer tools - source tab (from demo link).

== Random Observations ==

=== Sprite Markup ===
If you use the stock component, the card images won't work out of the box, you have to add sprite markup manually, it can be done easily in the card manager constructor:
setupFrontDiv: (card, div) => {
// ...
div.style.backgroundPositionX = `calc(100% / 14 * (${card.type_arg} - 2))`; // 14 is the number of columns in stock image minus 1
div.style.backgroundPositionY = `calc(100% / 3 * (${card.type} - 1))`; // 3 is the number of rows in stock image minus 1

If you prefer to use your own CSS, you can mark it up with data attributes instead (and do the positioning using CSS):
setupFrontDiv: (card, div) => {
div.dataset.type = card.type; // suit 1..4
div.dataset.typeArg = card.type_arg; // value 2..14

=== Card faces ===
This component supports two-faced cards, so you can do flip animations (mostly). To take advantage of that you have to define the card back also using setupBackDiv in the manager.
Beware that the function that defines what face is up is actually called isCardVisible (which is not confusing at all), and you redefine it to return a function which determines the side dynamically.
By default this function is defined as:
isCardVisible: (card) => card.type
which is also super non-intuitive. I suggest always defining a custom function for this (which will likely just be isCardVisible: () => true), except for something like BgaCards.Deck.

=== Void Stock ===
As of 1.0.7 VoidStock still lacks some animations such as shrink and fadeOut, however the same can be achieved without VoidStock by just providing animation settings in removeCards methods, i.e.:
await this.lineStock.removeCards(cards, {
fadeOut: true,
slideTo: $(`otherhand_${playerId}`),
});

=== Type casting from PHP Deck ===
You would think you can just use the database method to get cards from Deck and send this to the UI and use it in bga-cards? No, it's not that easy.
Two problems:
1) The default db accessor creates a map rather than an array, let's say you do this in getAllDatas in PHP:
// Cards in player hand
$result['hand'] = $this->cards->getCardsInLocation('hand', $current_player_id);
In .js you have to convert this to an array (or in PHP), i.e.:
this.handStock.addCards(Object.values(this.gamedatas.hand));
OR the same in PHP (don't need both):
$result['hand'] = array_values($this->cards->getCardsInLocation('hand', $current_player_id));

2) Some of the bga-cards methods, most notably BgaCards.sort, assume fields (such as 'type') are integers, but if sent by PHP like in the example above they are strings (even worse, some APIs return strings and some integers).
If this is the ONLY problem (i.e. sort) you can get away with making your own sort function, otherwise you would have to make an object converter and apply it to all objects sent from notifications and getAllDatas that need to go in bga-cards APIs.
See the hearts tutorial for helper method examples (i.e. find the method remapToBgaCard).

=== Asynchronicity ===
It's not immediately obvious but many functions that add or remove cards are async (i.e. return Promise), that means not only do you have to wait (or chain) them if running one after another, you also have
to be aware of residual effects of promises when using these methods in setup(), onEnteringState() and so on.
For example addCards is async while setSelectableCards is not. So if you add cards to your "hand" in the setup method, and try to set what is selectable in onEnteringState - that won't work properly,
unless you also promisify the call to setSelectableCards using setTimeout.

== Versioning ==
The library is using semver, so you can require 1.x to be sure to have the latest fixes without risking a breaking change. Any breaking change will be noted in the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this library, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/dist/bga-cards.d.ts d.ts]''' file to put in your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

If your game class is not declared on the define callback, you will need to modify it with this trick (to avoid a "ReferenceError: BgaAnimations is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
getLibUrl('bga-animations', '1.x'),
getLibUrl('bga-cards', '1.x'),
],
function (dojo, declare, gamegui, BgaAnimations, BgaCards) {
(window as any).BgaAnimations = BgaAnimations; //trick
(window as any).BgaCards = BgaCards;
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.10''': remove wrong required settings from GridStockSettings / demo of moving a card inside a slot stock with addCard / prevent selecting multiple times the same card programmatically / fix getLastPlayedCardStyle reading settings?.selectedCardStyle

'''1.0.9''': fix VoidStock.addCards signature

'''1.0.8''': fix slot & card selection override

'''1.0.7''': fix HandStock blinking for loose width container / fix wrong deck number on constructor / fix removeCard.fadeOut without slideTo

'''1.0.6''': fix autoPlace with VoidStock

'''1.0.5''': fix selection of parent card if it contains a child card

'''1.0.4''': fix error on emptyHandMessage not defined

'''1.0.3''': fix emptyHandMessage conflicting with sort

'''1.0.2''': fix selection style override

'''1.0.1''': Fix documentation

'''1.0.0''': Initial version

[[Category:Studio]]

BgaDice

2025-12-20T23:19:09Z

Nalka: Fix typo

{{Studio_Framework_Navigation}}

'''<big>[https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/demo/index.html Demo] [https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/docs/index.html Doc]</big>'''

== Overview ==
'''bga-dice''' is a javascript component to display dice.

The lib will handle associated animations (roll animation, moving between stocks).

The API documentation is here: [https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/docs/index.html Doc]

The Demo site is here: [https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/demo/index.html Demo]

== Usage ==
Load the lib:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x'); // the library uses bga-animations so this is required!
const BgaDice = await importEsmLib('bga-dice', '1.x');
</pre>

Legacy way;
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-animations', '1.x'), // the lib uses bga-animations so this is required!
getLibUrl('bga-dice', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaAnimations, BgaDice) { // note that the index of `BgaAnimations` must match the index of the define array
</pre>

In your game setup:
<pre>
// create the animation manager, and bind it to the `gameui.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});

// create the dice manager
this.diceManager = new BgaDice.Manager({
animationManager: this.animationManager,
type: 'my-game-die',
});
</pre>
Only setup an animation manager if you don't already have one, else re-use the same one.

Example of usage:
<pre>

// create the stock, in the game setup
this.dieStock = new BgaDice.LineStock(this.diceManager, document.getElementById('dice-stock'));
this.dieStock.addDice(gamedatas.dice); // dice should be something like [{ id: 1, face: 5, location: 'table' }]

async notif_rollDice(args) {
await this.dieStock.rollDice(args.rolledDice); // similar form as above, but with a different face value.
}

</pre>

Look at the demo page and the demo source code for a list of all possibilities!

== Versioning ==
The lib is using semver, so you can require 1.x to be sure to have the last fixes without risking a breaking change. Any breaking change will be noted on the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this lib, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-dice/1.x/dist/bga-dice.d.ts d.ts]''' file to put in on your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

If your game class is not declared on the define callback, you will need to modify it with this trick (to avoid a "ReferenceError: BgaAnimations is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock",
getLibUrl('bga-animations', '1.x'),
],
function (dojo, declare, gamegui, counter, stock, BgaAnimations) {
(window as any).BgaAnimations = BgaAnimations; //trick
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.1''': Fix documentation

'''1.0.0''': Initial version

[[Category:Studio]]

Gamehelpexhibitiontwentiethcentury

2025-08-27T10:10:31Z

Nalka: You can't get 0 fp for antiquity (outside of solo mode)

== CONTENT ==

*100 SUBJECT cards, with a year (1900-1999) and a continent + Albert Einstein card.
*10 SECRET DECADE variant cards (one per decade)

== TURNS ==

Each turn consists of 4 phases in this order:

#Take card
#Move vehicle
#Refill empty spot
#Place card

=== 1. TAKE CARD ===

Take 1 of the 3 SUBJECT cards at the continent where your VEHICLE stands
''Exception: if your VEHICLE stands at a continent without any card, move to another continent and take a card there.''

=== 2. MOVE VEHICLE ===

Move your VEHICLE to the continent (color) of your new SUBJECT card.
''Exception: if you took a white card (1945 or Einstein), you freely choose the continent to move to.''

=== 3. REFILL EMPTY SPOT ===

Refill the emptied spot with the top SUBJECT card of the stock.
''Arrange the 3 open cards in ascending year order again.''
''Exception: Skip this if the stock is empty.''

=== 4. PLACE CARD ===

Place your obtained SUBJECT card:
*In an empty spot in one of the 5 showcases of your EXHIBITION HALL. ''16 empty spots to choose from in your first turn.''
*OR in your DEPOT (maximum 3).

After the start player the turn progresses clockwise.

== REQUIREMENTS IN YOUR EXHIBITION ==

'''ASCENDING YEARS'''

Each card must show a year that is higher than each of its left-side cards and lower than each of its right-side cards in the same showcase.

'''DIFFERENT CONTINENTS'''

Each continent (card color) in a showcase must be unique. Except for the ONE CONTINENT showcase.

'''Showcase ONE CONTINENT'''

Here all cards must have the same continent. And it must be a continent that no other player has in their ONE CONTINENT showcase!

'''Showcase ONE ERA'''

Neighboring cards cannot have more than 10 years difference. With 1 spot between 2 cards the gap can be 20 years maximum, with 2 spots free between the gap can be 30 years maximum.

== SPECIAL CARDS (1945 and Einstein) ==

To fit the REQUIREMENTS you can choose to which continent, and to which year (only for 'Einstein' card), the card belongs. But the chosen 'year'/'continent' doesn't count for any fame points!

== FINAL EXHIBITIONS ==

Your game ends if:
*All your (16) EXHIBITION HALL spots are filled, or:
*You cannot place a call in your EXHIBITION HALL, and cannot or don't want to place one in your DEPOT.

Others may keep playing turns.

== FAME SCORE ==

Cards in your DEPOT don't count for calculating game points!.

=== FAME POINTS WHILE BUILDING YOUR EXHIBITION ===

'''ALL 6 CONTINENTS'''

The first player with at least 1 card of each of the 6 continents anywhere in their EXHIBITION HALL, gets 5 fame points(fp), the 2nd player 4, the 3rd player 3, the 4th player 2, and the 5th player 1. All players who reach this goal in the same round, get the same fp. A round lasts until all players, after the first player (who has the score sheet) had their turn.
''So if 3 players got their 6th continent in their 11th turn, and no one reached that yet, they all get 5fp.''

When players get the same fp, the next player(s) with 6 continents gets the next lower fp.
''So in above example the 4th player, in for example round 13, gets 4fp, and the 5th player in a later round gets 3fp.''

=== FAME POINTS AFTER ALL EXHIBITIONS ARE FINAL ===

'''SHOWCASE: YEARS GAP'''

The player with the biggest gap between the 2 years in this showcase, gets 5fp, the 2nd biggest gap brings 4fp, the 3rd-biggest 3fp, 4th 2fp and for the 5th player 1 fp. In case of equal gaps, the equal players get the same fp. The next payer(s) get the next lower fp. ''Same as with '6 continents' goal (see above).'' Players with an empty spot or the 'Einstein' card in this showcase, score 0fp.

'''CONTINENT FOCUS'''

You get fp equal to the number of cards of your most frequent continent. ''The 1945 and 'Einstein' cards do not count''

'''NUMBER OF DECADES'''

1 fp per decade you have 1 or more cards of. ''So 10fp (10 decades) maximum. Decades are 1900-1909, 1910-1919, 1920-1929, etc. The 'Einstein' card does not count.

'''CHAIN OF YEARS'''

1fp per card in your longest series of consecutive years. These cards don't have to be adjacent to each other in your exhibition! ''1fp is the minimum score. The 'Einstein' card does not count.''

=== PENALTY POINTS ===

'''EMPTY SPOTS'''

Subtract 1fp per empty spot in your EXHIBITION HALL.

'''DEPOT'''
Subtract 1fp per DEPOT card.

=== TIEBREAKER ===

'''1950'''

With an equal number of fame points, the equal player with their card in the 1-spot MID CENTURY showcase closest to 1950 wins. If that's equal too, these players tie.

== SECRET DECADE VARIANT ==

Shuffle these 10 cards and deal 1 to each player. Keep your card secret from other players until the end of game. Players will score 1fp per SUBJECT card whose year matches their secret decade card.

== VARIATION SHOWCASES ==

You can add 1 or more VARIATION SHOWCASES to your EXHIBITION HALL by laying them on top of the base game showcases.

Each player uses the same set of showcases.

The 2 special (white) cards can't be placed in VARIATION SHOWCASES.

The general rules (ascending years and different continents) apply to the VARIATION SHOWCASES as well.

=== Showcase SPREAD THE YEARS ===

Requirement: '''The difference between neighboring cards must be 20 years or more. With 1 free spot between cards 2 cards the gap must be at least 40 years, with 2 free spots it must be 60 years minimum.'''

=== Showcase LINKS ===

Requirement: '''Each 2 neighboring cards must have the same continent OR maximum of 5 years difference (or both).'''

=== Showcase SHORT ERA ===
For 5/4/3/2/1fp (see comparable YEARS GAP showcase)

''' Who has the smallest difference in years between the left and right side spots?'''

=== Showcase ONE DECADE ===
Requirement: '''All cards in this showcase must have the same decade.'''

=== Showcase ANTIQUITY ===

For 5/4/3/2/1fp (see comparable YEARS GAP showcase)

'''Who has the oldest year in the right-side spot?'''

=== Showcase UNIQUE DECADES ===

Requirement: '''Each decade must differ from earlier placed decades of all players (including yourself) in this showcase. With 4 players only the 10s, 20s, 30s, 40s, 50s, 60s, 70s, and 80s are allowed. With 3 players only the 20s, 30s, 40s, 50s, 60s, 70s, and with 2 players only the 30s, 40s, 50s, and 60s.
== SOLO MODE ==

Your final score will be multiplied by 100 compared to a "normal" game. (BGA doesn't support what would be a decimal score because of Mid century)

Most rules are the same, except that:

* All 6 continents is worth only 1 FP
* Mid century gives you 1 FP minus 0.02 FP per year between 1950 and your card's year
* Years gap: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being lower than the left card or higher than the right one. No negative FP.
* Short era: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being within your era (higher than the left card and lower than the right one). No negative FP.
* Antiquity: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being lower than the right one. No negative FP.

Try to get a score from the future (> 2025) !

Gamehelpexhibitiontwentiethcentury

2025-08-21T13:22:05Z

Nalka: There's no 0fp outside of solo mode

== CONTENT ==

*100 SUBJECT cards, with a year (1900-1999) and a continent + Albert Einstein card.
*10 SECRET DECADE variant cards (one per decade)

== TURNS ==

Each turn consists of 4 phases in this order:

#Take card
#Move vehicle
#Refill empty spot
#Place card

=== 1. TAKE CARD ===

Take 1 of the 3 SUBJECT cards at the continent where your VEHICLE stands
''Exception: if your VEHICLE stands at a continent without any card, move to another continent and take a card there.''

=== 2. MOVE VEHICLE ===

Move your VEHICLE to the continent (color) of your new SUBJECT card.
''Exception: if you took a white card (1945 or Einstein), you freely choose the continent to move to.''

=== 3. REFILL EMPTY SPOT ===

Refill the emptied spot with the top SUBJECT card of the stock.
''Arrange the 3 open cards in ascending year order again.''
''Exception: Skip this if the stock is empty.''

=== 4. PLACE CARD ===

Place your obtained SUBJECT card:
*In an empty spot in one of the 5 showcases of your EXHIBITION HALL. ''16 empty spots to choose from in your first turn.''
*OR in your DEPOT (maximum 3).

After the start player the turn progresses clockwise.

== REQUIREMENTS IN YOUR EXHIBITION ==

'''ASCENDING YEARS'''

Each card must show a year that is higher than each of its left-side cards and lower than each of its right-side cards in the same showcase.

'''DIFFERENT CONTINENTS'''

Each continent (card color) in a showcase must be unique. Except for the ONE CONTINENT showcase.

'''Showcase ONE CONTINENT'''

Here all cards must have the same continent. And it must be a continent that no other player has in their ONE CONTINENT showcase!

'''Showcase ONE ERA'''

Neighboring cards cannot have more than 10 years difference. With 1 spot between 2 cards the gap can be 20 years maximum, with 2 spots free between the gap can be 30 years maximum.

== SPECIAL CARDS (1945 and Einstein) ==

To fit the REQUIREMENTS you can choose to which continent, and to which year (only for 'Einstein' card), the card belongs. But the chosen 'year'/'continent' doesn't count for any fame points!

== FINAL EXHIBITIONS ==

Your game ends if:
*All your (16) EXHIBITION HALL spots are filled, or:
*You cannot place a call in your EXHIBITION HALL, and cannot or don't want to place one in your DEPOT.

Others may keep playing turns.

== FAME SCORE ==

Cards in your DEPOT don't count for calculating game points!.

=== FAME POINTS WHILE BUILDING YOUR EXHIBITION ===

'''ALL 6 CONTINENTS'''

The first player with at least 1 card of each of the 6 continents anywhere in their EXHIBITION HALL, gets 5 fame points(fp), the 2nd player 4, the 3rd player 3, the 4th player 2, and the 5th player 1. All players who reach this goal in the same round, get the same fp. A round lasts until all players, after the first player (who has the score sheet) had their turn.
''So if 3 players got their 6th continent in their 11th turn, and no one reached that yet, they all get 5fp.''

When players get the same fp, the next player(s) with 6 continents gets the next lower fp.
''So in above example the 4th player, in for example round 13, gets 4fp, and the 5th player in a later round gets 3fp.''

=== FAME POINTS AFTER ALL EXHIBITIONS ARE FINAL ===

'''SHOWCASE: YEARS GAP'''

The player with the biggest gap between the 2 years in this showcase, gets 5fp, the 2nd biggest gap brings 4fp, the 3rd-biggest 3fp, 4th 2fp and for the 5th player 1 fp. In case of equal gaps, the equal players get the same fp. The next payer(s) get the next lower fp. ''Same as with '6 continents' goal (see above).'' Players with an empty spot or the 'Einstein' card in this showcase, score 0fp.

'''CONTINENT FOCUS'''

You get fp equal to the number of cards of your most frequent continent. ''The 1945 and 'Einstein' cards do not count''

'''NUMBER OF DECADES'''

1 fp per decade you have 1 or more cards of. ''So 10fp (10 decades) maximum. Decades are 1900-1909, 1910-1919, 1920-1929, etc. The 'Einstein' card does not count.

'''CHAIN OF YEARS'''

1fp per card in your longest series of consecutive years. These cards don't have to be adjacent to each other in your exhibition! ''1fp is the minimum score. The 'Einstein' card does not count.''

=== PENALTY POINTS ===

'''EMPTY SPOTS'''

Subtract 1fp per empty spot in your EXHIBITION HALL.

'''DEPOT'''
Subtract 1fp per DEPOT card.

=== TIEBREAKER ===

'''1950'''

With an equal number of fame points, the equal player with their card in the 1-spot MID CENTURY showcase closest to 1950 wins. If that's equal too, these players tie.

== SECRET DECADE VARIANT ==

Shuffle these 10 cards and deal 1 to each player. Keep your card secret from other players until the end of game. Players will score 1fp per SUBJECT card whose year matches their secret decade card.

== VARIATION SHOWCASES ==

You can add 1 or more VARIATION SHOWCASES to your EXHIBITION HALL by laying them on top of the base game showcases.

Each player uses the same set of showcases.

The 2 special (white) cards can't be placed in VARIATION SHOWCASES.

The general rules (ascending years and different continents) apply to the VARIATION SHOWCASES as well.

=== Showcase SPREAD THE YEARS ===

Requirement: '''The difference between neighboring cards must be 20 years or more. With 1 free spot between cards 2 cards the gap must be at least 40 years, with 2 free spots it must be 60 years minimum.'''

=== Showcase LINKS ===

Requirement: '''Each 2 neighboring cards must have the same continent OR maximum of 5 years difference (or both).'''

=== Showcase SHORT ERA ===
For 5/4/3/2/1fp (see comparable YEARS GAP showcase)

''' Who has the smallest difference in years between the left and right side spots?'''

=== Showcase ONE DECADE ===
Requirement: '''All cards in this showcase must have the same decade.'''

=== Showcase ANTIQUITY ===

For 5/4/3/2/1(0)fp (see comparable YEARS GAP showcase)

'''Who has the oldest year in the right-side spot?'''

=== Showcase UNIQUE DECADES ===

Requirement: '''Each decade must differ from earlier placed decades of all players (including yourself) in this showcase. With 4 players only the 10s, 20s, 30s, 40s, 50s, 60s, 70s, and 80s are allowed. With 3 players only the 20s, 30s, 40s, 50s, 60s, 70s, and with 2 players only the 30s, 40s, 50s, and 60s.
== SOLO MODE ==

Your final score will be multiplied by 100 compared to a "normal" game. (BGA doesn't support what would be a decimal score because of Mid century)

Most rules are the same, except that:

* All 6 continents is worth only 1 FP
* Mid century gives you 1 FP minus 0.02 FP per year between 1950 and your card's year
* Years gap: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being lower than the left card or higher than the right one. No negative FP.
* Short era: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being within your era (higher than the left card and lower than the right one). No negative FP.
* Antiquity: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being lower than the right one. No negative FP.

Try to get a score from the future (> 2025) !

Game interface logic: Game.js

2025-07-16T00:50:28Z

Nalka:

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a MULTIPLE_ACTIVE_PLAYER state, it will be called when another player has become inactive.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for MULTIPLE_ACTIVE_PLAYER states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic ACTIVE_PLAYER state this method is called before the onEnteringState state.
In MULTIPLE_ACTIVE_PLAYER state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''this.player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''this.isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''this.gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''this.isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) ...

'''this.getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an ACTIVE_PLAYER type state.
if (this.player_id == this.getActivePlayerId()) ...

'''this.getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

'''this.getFormattedPlayerName(playerId): string'''
Get the HTML code to display the player name, in bold, with color (and color_back if needed)

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but it is longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''this.addStyleToClass(cssClassName: string, styleName: string, styleValue: any):''' '''void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanilla JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanilla JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanilla JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanilla JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''

This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''

This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==
'''bgaAnimationsActive()'''

Function to know if animations should be played. Animations should not be played in instantaneousMode (fast-replay mode), or if the tab is not displayed in the browser.
Returns a boolean saying if animations should be played.

<pre>
if (this.bgaAnimationsActive()) {
// play an animation
} else {
// just apply the end situation of the animation
}
</pre>

Note: if you use framework animation functions listed above, they already handle this check so you don't need it. It's useful if you write custom animations.

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

Note: slideTemporaryObject triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.slideTemporaryObject(...).promise</code>.

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

Note: slideToObjectAndDestroy triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.slideToObjectAndDestroy(...).promise</code>.

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''Animation'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

Note: fadeOutAndDestroy triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.fadeOutAndDestroy(...).promise</code>.

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): Animation'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

Note: rotateTo triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.rotateTo(...).promise</code>.

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

'''bgaPlayDojoAnimation(anim)'''
* anim - the dojo animation
Play a dojo animation and returns a promise resolved when it ends.

Examples:
<pre>
const anim = this.slideToObject(`disc_${x}${y}`, `square${x}_${y}`);
await this.bgaPlayDojoAnimation(anim);
</pre>
<pre>
const anim = dojo.fx.chain([
dojo.fadeOut( { node: discDiv } ),
dojo.fadeIn( { node: discDiv } ),
]);
await this.bgaPlayDojoAnimation(anim);
</pre>

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but based on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.connectClass('pet', 'onclick', 'onPet');
'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: { lock: boolean, checkAction: boolean}): Promise<void>'''

Triggers an asynchronous action call in the php backend. Check more of what actions and arguments are possible in [[Main_game_logic:_Game.php#Actions_(autowired)]] docs.

This method must be used to send a player's input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

Parameters:

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action, can be undefined/omitted if action has no parameters.
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.
** lock: (true by default) locks the user interface before any other action can be executed, that prevents user clicking on more buttons while this action is in progress. Set to false if you want to handle locking by yourself.
** checkAction: (true by default) check that action specified by "action" parameter in list of possible actions and user is active, only set to false in rare cases when some special out of turn actions are allowed.

Important: this is asynchronous action, this means you should not be doing anything after this line of code except returning; If you want to do something after the call is resolved, use promise handlers - catch and then, see examples below.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false, checkPossibleActions: true });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

Technical note:
* This is a combination of checkAction and ajaxcall, returning a Promise which resolves when ajaxcall ends.
* The function return void promise - the php callback cannot return any result, any results must be handled via the notification mechanism if needed
* In case there is an error - error message itself handled by framework, you can use error in catch(e) but you should not be showing it - this is done already

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list of possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list of possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if the interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

'''bgaSetupPromiseNotifications(params = undefined)'''
* params - the call parameters, by default { prefix: 'notif_', minDuration: 500, minDurationNoText: 1, logger: null, ignoreNotifications: [], onStart: undefined, onEnd: undefined, }.
Auto-detect all notifications declared on the game object (functions starting with `notif_`) and register them with dojo.subscribe.

Registered notifications will be synchronous and will have a minimum duration (if animations are active, by default 500ms with text and 1ms without).

If the notification function returns a Promise, the notification will end when the promise AND the minimum durations are over.
If the notification function does not return a promise, it is considered as already resolved as soon as the minimum durations are over.

In case of a notification function returning a Promise, the dev is responsible to make it resolve instantaneously if animations are not active.

See `bgaAnimationsActive` to know if animations are active : https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Animations

See `bgaPlayDojoAnimation` to handle dojo animations with promises : https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Animation_Callbacks

<pre>
setupNotifications: function() {
this.bgaSetupPromiseNotifications();
},
notif_playedCard: async function(args) {
await this.getPlayerTable(args.playerId).playCard(args.card);
}
</pre>

Example of setting custom values for all params :
<pre>
setupNotifications: function() {
this.bgaSetupPromiseNotifications({
prefix: 'notif_', // default is 'notif_'
minDuration: 1200, // for longer animations (500 by default)
minDurationNoText: 1,
handlers: [this.notificationsManager], // if you write your notif function in a subclass instead of this (default this)
logger: console.log, // show notif debug informations on console. Could be console.warn or any custom debug function (default null = no logs)
ignoreNotifications: ['updateAutoPlay'], // the notif_updateAutoPlay function will be ignored by bgaSetupPromiseNotifications. You'll need to subscribe to it manually
onStart: (notifName, msg, args) => $('pagemaintitletext').innerHTML = `${_('Animation for:')} ${msg}`,
onEnd: (notifName, msg, args) => $('pagemaintitletext').innerHTML = '',
});
}
</pre>

'''wait(delay)'''
* delay - the time to wait, in milliseconds
Return a Promise that resolves at the end of a given number of ms. If animations are not active, resolve instantaneously.

<pre>
await this.wait(500); // wait 500ms before continuing in an async function
</pre>

=== Subscribe to notifications manually ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notify->all" or "notify->player" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notify->all( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|Notify->all]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notify->all("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notify->player($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notify->player and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''

This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Handle manually synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
$this->notify->all( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
$this->notify->all( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notify->all( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notify->all( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side

Note: any traslatable string have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

'''this.getPlayerPanelElement(player_id: number): HTMLElement'''

Returns the div in the player panel you can put your counters & other indicators in.

'''Example'''

At first, create a new "JS template" string in your JS file (example based on Gomoku project) :
<pre>
const jstpl_player_board = (id, color) => `<div class="cp_board">
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>
</div>`;
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
this.getPlayerPanelElement(player_id).innerHTML = jstpl_player_board(player.id, player.color);
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Please use the "ebg/counter" library, documented at [[Counter]].

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

'''''Deprecated, use t[https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar his.statusBar.addActionButton] instead'''''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
*id: an element ID that should be unique in your HTML DOM document.
*label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class="brick"></div>", see example below on how to make image action buttons.
*method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
*destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
*blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
*color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), () => this.onGiveCards() );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), () => this.onConfirm(), null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

===Image Button===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

===Disabling Button===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), () => this.playFunctionButton());
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

===Custom Buttons===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

===Button outside of action bar===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(), 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

==Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

==Sounds ==

'''this.sounds.load(id: string, label: string, fileName: string = undefined): void'''

Load a sound and register its id. Filename is without the extension. If fileName is unset, it will use the same as the id.

In any case, the sound should be placed on your img folder and exist bothe with the mp3 and ogg format/extension.

Examples :
<pre>
this.sounds.load('play'); // will load play.ogg / play.mp3 in the img dir, and will be playable with id `play`
this.sounds.load('claw', 'smash'); // will load smash.ogg / smash.mp3 in the img dir, and will be playable with id `claw`
</pre>

'''this.sounds.play(id: string): void'''
Play a sound by its id, loaded in the setup with ''this.sounds.load''

Examples :
<pre>
this.sounds.play('play');
this.sounds.play('claw');
</pre>

'''this.disableNextMoveSound(): void'''
Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

==Title bar and states ==

===Client states===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

To add custom string interpolation for the state title, you can add them by using the args object like so:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location for card {$card_number}"),
args: { card_number: 5 },
});
'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

===Title bar===
;'''this.statusBar.setTitle(title: string, args?: object)'''
Update the page title (aka status bar prompt). Can handle ${you} and ${actplayer} and any other var you would pass as args.
<pre>
if (args.mandatory_card_name) {
const mandatoryCardTitle = this.isCurrentPlayerActive() ? _('${you} must take ${mandatory_card_name}') : _('${actplayer} must take ${mandatory_card_name}');
this.statusBar.setTitle(mandatoryCardTitle, args);
}
</pre>
As opposed to <code>updatePageTitle</code>, it doesn't trigger the call <code>onUpdateActionButtons</code>.

;'''this.statusBar.addActionButton(label: string, callback: Function, params?: object): HTMLButtonElement'''

Parameters:
*label: the label to be shown, can be html. If label if used pass traslated string, i.e. _('Yes')
*callback: function to call on click, cannot be method name it has to be function
*params: object optionally containing one of more of the following:
**color: string - can be <code>primary</code> (default) (blue), <code>secondary</code> (gray), <code>alert</code> (red)
**id: string - is the dom element id to set. If null/undefined, the button will not have an id, but you can still manipulate it by storing the reference to the DOM Element returned by the function
**classes: string|string[] - i.e <code>'disabled blinking'</code> or <code>['disabled', 'blinking']</code>.
**destination: ElementOrId - the DOM Element to add the button to. If not specified, will add it to the status bar.
**title: string - plain text description of the label. Should be set when the button label is an icon, for accessibility.
**disabled: boolean - makes the button disabled. Will prevent the callback to be executed
**tooltip: string - the tooltip of the button
**confirm: string | Function - the confirm message to display before triggering the callback, if set (or function handler, see example below).

Example of a standard call without params:
this.statusBar.addActionButton(_('Pass'), () => this.bgaPerformAction('actPass'));

Example of a standard call with params:
this.statusBar.addActionButton(_('Pass'), () => this.bgaPerformAction('actPass'), {
id: 'my_button',
color: 'secondary',
classes: 'my-outline-class'
disabled: true,
tooltip: _('You cannot pass'),
confirm: _('Are you sure to pass?'),
});

Note: the confirm parameter can be a string or a function that returns a string or null

Example of a standard call with params:
this.statusBar.addActionButton(_('Discard Selected Cards'), () => this.bgaPerformAction('actDiscard', { cardIds: this.getSelectedCardIds().join(',') }), {
confirm: () => {
if (this.getSelectedCardIds().length === 0) { // no card is selected, show the warning
return _('Are you sure you don't want to discard any cards?');
} else { // cards are selected, do not show the warning
return null;
}
}
});

;'''this.statusBar.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

==User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

==Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

;this.bRealtime
:Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

;g_replayFrom
:Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

;g_archive_mode
:Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

;this.instantaneousMode
:Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
:Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

;g_tutorialwritten
:Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
:Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Gamehelpexhibitiontwentiethcentury

2025-07-07T10:08:11Z

Nalka: Solo mode rules, remove irrelevant content

== CONTENT ==

*100 SUBJECT cards, with a year (1900-1999) and a continent + Albert Einstein card.
*10 SECRET DECADE variant cards (one per decade)

== TURNS ==

Each turn consists of 4 phases in this order:

#Take card
#Move vehicle
#Refill empty spot
#Place card

=== 1. TAKE CARD ===

Take 1 of the 3 SUBJECT cards at the continent where your VEHICLE stands
''Exception: if your VEHICLE stands at a continent without any card, move to another continent and take a card there.''

=== 2. MOVE VEHICLE ===

Move your VEHICLE to the continent (color) of your new SUBJECT card.
''Exception: if you took a white card (1945 or Einstein), you freely choose the continent to move to.''

=== 3. REFILL EMPTY SPOT ===

Refill the emptied spot with the top SUBJECT card of the stock.
''Arrange the 3 open cards in ascending year order again.''
''Exception: Skip this if the stock is empty.''

=== 4. PLACE CARD ===

Place your obtained SUBJECT card:
*In an empty spot in one of the 5 showcases of your EXHIBITION HALL. ''16 empty spots to choose from in your first turn.''
*OR in your DEPOT (maximum 3).

After the start player the turn progresses clockwise.

== REQUIREMENTS IN YOUR EXHIBITION ==

'''ASCENDING YEARS'''

Each card must show a year that is higher than each of its left-side cards and lower than each of its right-side cards in the same showcase.

'''DIFFERENT CONTINENTS'''

Each continent (card color) in a showcase must be unique. Except for the ONE CONTINENT showcase.

'''Showcase ONE CONTINENT'''

Here all cards must have the same continent. And it must be a continent that no other player has in their ONE CONTINENT showcase!

'''Showcase ONE ERA'''

Neighboring cards cannot have more than 10 years difference. With 1 spot between 2 cards the gap can be 20 years maximum, with 2 spots free between the gap can be 30 years maximum.

== SPECIAL CARDS (1945 and Einstein) ==

To fit the REQUIREMENTS you can choose to which continent, and to which year (only for 'Einstein' card), the card belongs. But the chosen 'year'/'continent' doesn't count for any fame points!

== FINAL EXHIBITIONS ==

Your game ends if:
*All your (16) EXHIBITION HALL spots are filled, or:
*You cannot place a call in your EXHIBITION HALL, and cannot or don't want to place one in your DEPOT.

Others may keep playing turns.

== FAME SCORE ==

Cards in your DEPOT don't count for calculating game points!.

=== FAME POINTS WHILE BUILDING YOUR EXHIBITION ===

'''ALL 6 CONTINENTS'''

The first player with at least 1 card of each of the 6 continents anywhere in their EXHIBITION HALL, gets 5 fame points(fp), the 2nd player 4, the 3rd player 3, the 4th player 2, and the 5th player 1. All players who reach this goal in the same round, get the same fp. A round lasts until all players, after the first player (who has the score sheet) had their turn.
''So if 3 players got their 6th continent in their 11th turn, and no one reached that yet, they all get 5fp.''

When players get the same fp, the next player(s) with 6 continents gets the next lower fp.
''So in above example the 4th player, in for example round 13, gets 4fp, and the 5th player in a later round gets 3fp.''

=== FAME POINTS AFTER ALL EXHIBITIONS ARE FINAL ===

'''SHOWCASE: YEARS GAP'''

The player with the biggest gap between the 2 years in this showcase, gets 5fp, the 2nd biggest gap brings 4fp, the 3rd-biggest 3fp, 4th 2fp and for the 5th player 1 fp. In case of equal gaps, the equal players get the same fp. The next payer(s) get the next lower fp. ''Same as with '6 continents' goal (see above).'' Players with an empty spot or the 'Einstein' card in this showcase, score 0fp.

'''CONTINENT FOCUS'''

You get fp equal to the number of cards of your most frequent continent. ''The 1945 and 'Einstein' cards do not count''

'''NUMBER OF DECADES'''

1 fp per decade you have 1 or more cards of. ''So 10fp (10 decades) maximum. Decades are 1900-1909, 1910-1919, 1920-1929, etc. The 'Einstein' card does not count.

'''CHAIN OF YEARS'''

1fp per card in your longest series of consecutive years. These cards don't have to be adjacent to each other in your exhibition! ''1fp is the minimum score. The 'Einstein' card does not count.''

=== PENALTY POINTS ===

'''EMPTY SPOTS'''

Subtract 1fp per empty spot in your EXHIBITION HALL.

'''DEPOT'''
Subtract 1fp per DEPOT card.

=== TIEBREAKER ===

'''1950'''

With an equal number of fame points, the equal player with their card in the 1-spot MID CENTURY showcase closest to 1950 wins. If that's equal too, these players tie.

== SECRET DECADE VARIANT ==

Shuffle these 10 cards and deal 1 to each player. Keep your card secret from other players until the end of game. Players will score 1fp per SUBJECT card whose year matches their secret decade card.

== VARIATION SHOWCASES ==

You can add 1 or more VARIATION SHOWCASES to your EXHIBITION HALL by laying them on top of the base game showcases.

Each player uses the same set of showcases.

The 2 special (white) cards can't be placed in VARIATION SHOWCASES.

The general rules (ascending years and different continents) apply to the VARIATION SHOWCASES as well.

=== Showcase SPREAD THE YEARS ===

Requirement: '''The difference between neighboring cards must be 20 years or more. With 1 free spot between cards 2 cards the gap must be at least 40 years, with 2 free spots it must be 60 years minimum.'''

=== Showcase LINKS ===

Requirement: '''Each 2 neighboring cards must have the same continent OR maximum of 5 years difference (or both).'''

=== Showcase SHORT ERA ===
For 5/4/3/2/1(0)fp (see comparable YEARS GAP showcase)

''' Who has the smallest difference in years between the left and right side spots?'''

=== Showcase ONE DECADE ===
Requirement: '''All cards in this showcase must have the same decade.'''

=== Showcase ANTIQUITY ===

For 5/4/3/2/1(0)fp (see comparable YEARS GAP showcase)

'''Who has the oldest year in the right-side spot?'''

=== Showcase UNIQUE DECADES ===

Requirement: '''Each decade must differ from earlier placed decades of all players (including yourself) in this showcase. With 4 players only the 10s, 20s, 30s, 40s, 50s, 60s, 70s, and 80s are allowed. With 3 players only the 20s, 30s, 40s, 50s, 60s, 70s, and with 2 players only the 30s, 40s, 50s, and 60s.
== SOLO MODE ==

Your final score will be multiplied by 100 compared to a "normal" game. (BGA doesn't support what would be a decimal score because of Mid century)

Most rules are the same, except that:

* All 6 continents is worth only 1 FP
* Mid century gives you 1 FP minus 0.02 FP per year between 1950 and your card's year
* Years gap: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being lower than the left card or higher than the right one. No negative FP.
* Short era: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being within your era (higher than the left card and lower than the right one). No negative FP.
* Antiquity: if full and without Einstein, score 5 FP minus 1 FP per available card (below the continents) being lower than the right one. No negative FP.

Try to get a score from the future (> 2025) !

Gamehelpexhibitiontwentiethcentury

2025-07-07T09:53:08Z

Nalka:

== CONTENT ==

*1 CONTINENTS tile (OCEANIA, SOUTH AMERICA, AFRICA, ASIA, EUROPE, NORTH AMERICA)
*101 SUBJECT cards, with a year (1900-1999) and a continent
*10 SECRET DECADE variant cards
*5 PLAYER BOARDS, each showing an EXHIBITION HALL and a DEPOT
*5 VEHICLES (Zeppelin / Ford / Titanic / DC-3 / Space Shuttle)
*1 SCORE SHEET pad

== TURNS ==

Each turn consists of 4 phases in this order:

#Take card
#Move vehicle
#Refill empty spot
#Place card

=== 1. TAKE CARD ===

Take 1 of the 3 SUBJECT cards at the continent where your VEHICLE stands
''Exception: if your VEHICLE stands at a continent without any card, move to another continent and take a card there.''

=== 2. MOVE VEHICLE ===

Move your VEHICLE to the continent (color) of your new SUBJECT card.
''Exception: if you took a white card (1945 or Einstein), you freely choose the continent to move to.''

=== 3. REFILL EMPTY SPOT ===

Refill the emptied spot with the top SUBJECT card of the stock.
''Arrange the 3 open cards in ascending year order again.''
''Exception: Skip this if the stock is empty.''

=== 4. PLACE CARD ===

Place your obtained SUBJECT card:
*In an empty spot in one of the 5 showcases of your EXHIBITION HALL. ''16 empty spots to choose from in your first turn.''
*OR in your DEPOT (maximum 3).

After the start player the turn progresses clockwise.

== REQUIREMENTS IN YOUR EXHIBITION ==

'''ASCENDING YEARS'''

Each card must show a year that is higher than each of its left-side cards and lower than each of its right-side cards in the same showcase.

'''DIFFERENT CONTINENTS'''

Each continent (card color) in a showcase must be unique. Except for the ONE CONTINENT showcase.

'''Showcase ONE CONTINENT'''

Here all cards must have the same continent. And it must be a continent that no other player has in their ONE CONTINENT showcase!

'''Showcase ONE ERA'''

Neighboring cards cannot have more than 10 years difference. With 1 spot between 2 cards the gap can be 20 years maximum, with 2 spots free between the gap can be 30 years maximum.

== SPECIAL CARDS (1945 and Einstein) ==

To fit the REQUIREMENTS you can choose to which continent, and to which year (only for 'Einstein' card), the card belongs. But the chosen 'year'/'continent' doesn't count for any fame points!

== FINAL EXHIBITIONS ==

Your game ends if:
*All your (16) EXHIBITION HALL spots are filled, or:
*You cannot place a call in your EXHIBITION HALL, and cannot or don't want to place one in your DEPOT.

Others may keep playing turns.

== FAME SCORE ==

Cards in your DEPOT don't count for calculating game points!.

=== FAME POINTS WHILE BUILDING YOUR EXHIBITION ===

'''ALL 6 CONTINENTS'''

The first player with at least 1 card of each of the 6 continents anywhere in their EXHIBITION HALL, gets 5 fame points(fp), the 2nd player 4, the 3rd player 3, the 4th player 2, and the 5th player 1. All players who reach this goal in the same round, get the same fp. A round lasts until all players, after the first player (who has the score sheet) had their turn.
''So if 3 players got their 6th continent in their 11th turn, and no one reached that yet, they all get 5fp.''

When players get the same fp, the next player(s) with 6 continents gets the next lower fp.
''So in above example the 4th player, in for example round 13, gets 4fp, and the 5th player in a later round gets 3fp.''

=== FAME POINTS AFTER ALL EXHIBITIONS ARE FINAL ===

'''SHOWCASE: YEARS GAP'''

The player with the biggest gap between the 2 years in this showcase, gets 5fp, the 2nd biggest gap brings 4fp, the 3rd-biggest 3fp, 4th 2fp and for the 5th player 1 fp. In case of equal gaps, the equal players get the same fp. The next payer(s) get the next lower fp. ''Same as with '6 continents' goal (see above).'' Players with an empty spot or the 'Einstein' card in this showcase, score 0fp.

'''CONTINENT FOCUS'''

You get fp equal to the number of cards of your most frequent continent. ''The 1945 and 'Einstein' cards do not count''

'''NUMBER OF DECADES'''

1 fp per decade you have 1 or more cards of. ''So 10fp (10 decades) maximum. Decades are 1900-1909, 1910-1919, 1920-1929, etc. The 'Einstein' card does not count.

'''CHAIN OF YEARS'''

1fp per card in your longest series of consecutive years. These cards don't have to be adjacent to each other in your exhibition! ''1fp is the minimum score. The 'Einstein' card does not count.''

=== PENALTY POINTS ===

'''EMPTY SPOTS'''

Subtract 1fp per empty spot in your EXHIBITION HALL.

'''DEPOT'''
Subtract 1fp per DEPOT card.

=== TIEBREAKER ===

'''1950'''

With an equal number of fame points, the equal player with their card in the 1-spot MID CENTURY showcase closest to 1950 wins. If that's equal too, these players tie.

== SECRET DECADE VARIANT ==

Shuffle these 10 cards and deal 1 to each player. Keep your card secret from other players until the end of game. Players will score 1fp per SUBJECT card whose year matches their secret decade card.

== VARIATION SHOWCASES ==

You can add 1 or more VARIATION SHOWCASES to your EXHIBITION HALL by laying them on top of the base game showcases.

Each player uses the same set of showcases.

The 2 special (white) cards can't be placed in VARIATION SHOWCASES.

The general rules (ascending years and different continents) apply to the VARIATION SHOWCASES as well.

=== Showcase SPREAD THE YEARS ===

Requirement: '''The difference between neighboring cards must be 20 years or more. With 1 free spot between cards 2 cards the gap must be at least 40 years, with 2 free spots it must be 60 years minimum.'''

=== Showcase LINKS ===

Requirement: '''Each 2 neighboring cards must have the same continent OR maximum of 5 years difference (or both).'''

=== Showcase SHORT ERA ===
For 5/4/3/2/1(0)fp (see comparable YEARS GAP showcase)

''' Who has the smallest difference in years between the left and right side spots?'''

=== Showcase ONE DECADE ===
Requirement: '''All cards in this showcase must have the same decade.'''

=== Showcase ANTIQUITY ===

For 5/4/3/2/1(0)fp (see comparable YEARS GAP showcase)

'''Who has the oldest year in the right-side spot?'''

=== Showcase UNIQUE DECADES ===

Requirement: '''Each decade must differ from earlier placed decades of all players (including yourself) in this showcase. With 4 players only the 10s, 20s, 30s, 40s, 50s, 60s, 70s, and 80s are allowed. With 3 players only the 20s, 30s, 40s, 50s, 60s, 70s, and with 2 players only the 30s, 40s, 50s, and 60s.

Main game logic: Game.php

2025-06-02T20:42:05Z

Nalka:

{{Studio_Framework_Navigation}}

This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.

This is the main class that implements the "server" callbacks. As it is a server it cannot initiate any data communicate with the game client (running in browser) and only can respond to client using notifications.

Your php class instance won't be in memory between two callbacks, every time client send a request a new class will be created, constructor will be called and eventually your callback function.

'''Note:''' this file is now named Game.php, located in the modules/php directory. If you see it named yourgamename.game.php in the root dir, it's the legacy usage. In the legacy usage, the namepaces don't exists.

== File Structure ==

The details of how the file is structured are described directly with comments in the code skeleton provided to you.

Here is the basic structure:

* '''__construct''': the game constructor, where you define global variables and initiaze class members.
* '''setupNewGame''': initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.
* '''getAllDatas''': where you retrieve all game data during a complete reload of the game. Return value must be associative array. Value of 'players' is reserved for returning players data from players table, if you set it it must follow certain rules
$result ['players'] = $this->getCollectionFromDb("SELECT `player_id` `id`, `player_score` `score`, `player_no` `no`, `player_color` `color` FROM `player`");
// Returned value must include ['players'][$player_id]]['score'] for scores to populate when F5 is pressed.
* '''getGameProgression''': where you compute the game progression indicator. Returns a number indicating percent of progression (0-100). Used to calculate ELO changes of remaining players when a player quits, or as a conceding requirement (in non-tournament 2 player games, a player may concede if the progression is at least 50%).
* Utility functions: your utility functions.
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]).
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* '''initTable''': (not part of template) - this function is called for every php callback by the framework and it can be implement by the game (empty by default). You can use it in rare cases where you need to read database and manipulate some data before any ANY php entry functions are called (such as getAllDatas,action*,st*, etc). Note: it is not called before arg* methods
* '''zombieTurn''': what to do it's the turn of a zombie player.
* '''upgradeTableDb''': function to migrate database if you change it after release on production.
* '''getGameName''': returns the game name. This will be setup when you create the project. If you are copying files in from another project, make sure you keep this function intact. It must return the right game name, or lots of things will be broken.

== Accessing player information ==

'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!

; getPlayersNumber()
: Returns the number of players playing at the table
: Note: doesn't work in the beggining of setupNewGame (use count($players) instead). It will work after initialization of player table.

; getActivePlayerId()
: Get the "active_player", whatever what is the current state type.
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getActivePlayerName()
: Get the "active_player" name
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getPlayerNameById($player_id)
: Get the name by id

; getPlayerColorById($player_id)
: Get the color by id

; getPlayerNoById($player_id)
: Get 'player_no' (number) by id

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.
: The content of each value is:
: * player_name - the name of the player
: * player_color (ex: ff0000) - the color code of the player (as string)
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3

<pre>
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $info) {
$player_color = $info['player_color'];
...
}
</pre>
Note: if you want array of player ids only you can do this:
$player_ids = array_keys($this->loadPlayersBasicInfos());

; getCurrentPlayerId(bool $bReturnNullIfNotLogged = false) int
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).
: '''Be careful''': This is not necessarily the active player!
: In general, you shouldn't use this method, unless you are in "multiplayer" state.
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(),
: otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).

; getCurrentPlayerName(bool $bReturnEmptyIfNotLogged = false) string
: Get the "current_player" name.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above).

; getCurrentPlayerColor()
: Get the "current_player" color.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above).

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.
: Note: this will throw an exception if current player is not at the table, i.e. spectator

; isSpectator()
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).

; getActivePlayerColor()
: This function does not seems to exist in API, if you need it here is implementation
function getActivePlayerColor() {
$player_id = $this->getActivePlayerId();
$players = $this->loadPlayersBasicInfos();
if (isset($players[$player_id]))
return $players[$player_id]['player_color'];
else
return null;
}
; isPlayerZombie($player_id)
: This method does not exists, but if you need it it looks like this
protected function isPlayerZombie($player_id) {
$players = $this->loadPlayersBasicInfos();
if (! isset($players[$player_id]))
throw new \BgaSystemException("Player $player_id is not playing here");

return ($players[$player_id]['player_zombie'] == 1);
}

== Accessing the database ==

The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.

'''IMPORTANT'''

BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.

However there are sets of database operation that will do implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).

All methods below are part of game class (and view class) and can be accessed using $this->

; DbQuery( string $sql )
: This is the generic method to access the database.
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database. Returns result of the query.
: For SELECT queries, the specialized methods below are much better.
: Do not use method for TRUNCATE, DROP and other table altering operations. See disclamer above about implicit commits. If you really need TRUNCATE use DELETE FROM xxx instead.

; getUniqueValueFromDB( string $sql )
: Returns a unique value from DB or null if no value is found.
: $sql must be a SELECT query.
: Raise an exception if more than 1 row is returned.

; getCollectionFromDB( string $sql, bool $bSingleValue=false ) array
: Returns an associative array of rows for a sql SELECT query.
: The key of the resulting associative array is the first field specified in the SELECT query.
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.
: First column must be a primary or alternate key (semantically, it does not actually have to declared in sql as such).
: The resulting collection can be empty (it won't be null).
: If you specified $bSingleValue=true and if your SQL query requests 2 fields A and B, the method returns an associative array "A=>B", otherwise its A=>[A,B]
: Note: The name a bit misleading, it really return associative array, i.e. map and NOT a collection. You cannot use it to get list of values which may have duplicates (hence primary key requirement on first column). If you need simple array use getObjectListFromDB() method.

Example 1:
<pre>
$result = $this->getCollectionFromDB( "SELECT `player_id` `id`, `player_name` `name`, `player_score` `score` FROM `player`" );

Result:
[
1234 => [ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
1235 => [ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getCollectionFromDB( "SELECT `player_id` `id`, `player_name` `name` FROM `player`", true );

Result:
[
1234 => 'myuser0',
1235 => 'myuser1'
]

</pre>

; getNonEmptyCollectionFromDB(string $sql) array
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.

; getObjectFromDB(string $sql) array
: Returns one row for the sql SELECT query as an associative array or null if there is no result (where fields are keys mapped to values)
: Raise an exception if the query return more than one row (you can use LIMIT 1 in the query to avoid the exception)

Example:
<pre>
$result = $this->getObjectFromDB( "SELECT `player_id` `id`, `player_name` `name`, `player_score` `score` FROM `player` WHERE `player_id` = '$player_id'" );

Result:
[
'id'=>1234, 'name'=>'myuser0', 'score'=>1
]
</pre>

; getNonEmptyObjectFromDB(string $sql) array
: Similar to previous one, but raise an exception if no row is found

; getObjectListFromDB(string $sql, bool $bUniqueValue=false) array
: Return an array of rows for a sql SELECT query.
: The result is the same as "getCollectionFromDB" except that the result is a simple array (and not an associative array).
: The result can be empty.
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.

Example 1:
<pre>
$result = $this->getObjectListFromDB( "SELECT `player_id` `id`, `player_name` `name`, `player_score` `score` FROM `player`" );

Result:
[
[ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
[ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getObjectListFromDB( "SELECT `player_name` `name` FROM `player`", true );

Result:
[
'myuser0',
'myuser1'
]

</pre>

; getDoubleKeyCollectionFromDB(string $sql, bool $bSingleValue=false) array
: Return an associative array of associative array, from a SQL SELECT query.
: First array level correspond to first column specified in SQL query.
: Second array level correspond to second column specified in SQL query.
: If $bSingleValue = true, keep only third column on result

; DbGetLastId()
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).

; DbAffectedRow() int
: Return the number of row affected by the last operation

; escapeStringForDB(string $string) string
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.

<pre>

</pre>

Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.

== Use globals ==
Sometimes, you want a single global value for your game, and you don't want to create a DB table specifically for it.

You can do this with the BGA framework "globals". Your value will be stored in the "bga_globals" table in the database, and you can access it with simple methods.

The keys are strings, so you might want to store them in constants to avoid mistakes (the key must be at maximum 50 characters long).

The variable can be of any type (number, string, array, object) and will be stored as a JSON (so functions cannot be stored, and circular references on objects will trigger an Exception when storing).

Having a string key and a JSON serialization allows you to debug easily by looking at the bga_globals table content.

''Note: this globals module doesn't use cache, so every call to one of the following methods makes a DB request.''

'''globals->set(string $name, $mixed $obj): void'''

Define the value of a global variable.
<pre>
const FIRST_PLAYER_ID = "firstPlayerId";
$this->globals->set(FIRST_PLAYER_ID, array_keys($players)[0]);
</pre>

'''globals->get(string $name, $mixed $defaultValue = null): mixed'''

Get the value of a global variable. Returns `null` if not set, except specified otherwise in the optional `$defaultValue`.
<pre>
$currentFirstPlayerId = $this->globals->get(FIRST_PLAYER_ID);
...
$selectedCardsIds = $this->globals->get(SELECTED_CARDS_IDS, []);
</pre>

'''globals->getAll(...$names): array'''

Get the value of all global variables, as a key=>value array. You can set a list of names to only get matching variables. In that case, non-existent keys will not be set in the returned array, so if you have a key with null value, it means the key has been set to null previously.
<pre>
$variables = $this->globals->getAll();
...
$diceVariables = $this->globals->getAll(DIE1, DIE2);
</pre>

Use with PHP's [https://www.php.net/extract extract()] function to quickly assign multiple variables:
<pre>
extract($this->globals->getAll('endTime', 'hour', 'vipWelcome'));
// $endTime, $hour, and $vipWelcome (may) now exist

if (!empty($endTime)) {
...
</pre>

'''globals->delete(...$names): void'''

Delete a global variable or a list of global variables stored in database.
<pre>
$this->globals->delete(SELECTED_CARDS_IDS);
...
$this->globals->delete(SELECTED_CARDS_IDS, UNDO, AFTER_DISCARD_RETURN_STATE);
</pre>

'''globals->has(string $name): bool'''

Indicates if a global variable is stored in database.
<pre>
$cardSelectionIsStarted = $this->globals->has(SELECTED_CARDS_IDS);
</pre>

'''globals->inc(string $name, $int $inc): int'''

Increments the value of a global variable, and return the incremented value. Will trigger an exception if the variable is not a numeric value.
<pre>
$this->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->globals->inc(SPENT_COINS_IN_CURRENT_TURN, $cardCost);
</pre>

== Use globals (numbers only / game options) ==

Before the `$this->globals`, you could only store numeric values as globals. Theses "GameStateValues" are stored in the "global" table in the database, and you can access it with simple methods.

All methods below are members of the game class and should be accessed via $this->

'''initGameStateLabels(array $labelsMap): void'''

This method should be located at the beginning of constructor of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.

You can define up to 80 globals, with IDs from 10 to 89 (inclusive, there can be gaps).
Also you must use this method to access value of game options [[Game_options_and_preferences:_gameoptions.inc.php]], in that case, IDs need to be between 100 and 199.
You must '''not''' use globals outside the range defined above, as those values are used by other components of the framework.

<pre>
function __construct() {
parent::__construct();
$this->initGameStateLabels([
"my_first_global_variable" => 10,
"my_second_global_variable" => 11,
"my_game_variant" => 100
]);
// other code ...
}
</pre>

NOTE: The methods below WILL throw an exception if label is not defined using the call above.

'''setGameStateInitialValue( string $label, int $value ): void'''

Initialize global value. This is not required if you ok with default value if 0. This should be called from setupNewGame function.

'''getGameStateValue( string $label, int $default = 0): int'''

Retrieve the value of a global. Returns $default if global is not been initialized (by setGameStateInitialValue).

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->getGameStateValue('my_first_global_variable');
</pre>

For debugging purposes, you can have labels and value pairs send to client side by inserting that code in your "getAllDatas":

<pre>
$labels = array_keys($this->mygamestatelabels);
$result['myglobals'] = array_combine($labels, array_map([$this,'getGameStateValue'],$labels));
</pre>

That assumes you stored your label mapping in $this->mygamestatelabels in constructor
<pre>
$this->mygamestatelabels=["my_first_global_variable" => 10, ...];
$this->initGameStateLabels($this->mygamestatelabels);
</pre>

'''setGameStateValue( string $label, int $value ): void'''

Set the current value of a global.
<pre>
$this->setGameStateValue('my_first_global_variable', 42);
</pre>

'''incGameStateValue( string $label, int $increment ): int'''

Increment the current value of a global. If increment is negative, decrement the value of the global.

Return the final value of the global. If global was not initialized it will initialize it as 0.

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->incGameStateValue('my_first_global_variable', 1);
</pre>

=== BGA predefined globals ===

BGA already defines some globals in the ''global'' database table. You should not change them directly but it can be useful to know what they mean when debugging:

{| class="wikitable"
|-
! global_id !! label !! Meaning
|-
| 1 || || Current state
|-
| 2 || || Active player id
|-
| 3 || next_move_id || Next move number
|-
| 4 || || Game id
|-
| 5 || || Table creator id
|-
| 6 || playerturn_nbr || Player turn number
|-
| 7 || gameprogression || Game progression
|-
| 8 || initial_reflexion_time || Initial reflection time
|-
| 9 || additional_reflexion_time || Additional reflection time
|-
| 200 || reflexion_time_profile || Game speed
Real-time games:
* 0 = Real-time • Fast paced
* 1 = Real-time • Normal speed
* 2 = Real-time • Slow speed
* 9 = No time limit • with friends only

Turn-based games:
* 10 = Fast Turn-based • 24 moves per day
* 11 = Fast Turn-based • 12 moves per day
* 12 = Fast Turn-based • 8 moves per day
* 13 = Turn-based • 4 moves per day
* 14 = Turn-based • 3 moves per day
* 15 = Turn-based • 2 moves per day
* 17 = Turn-based • 1 move per day
* 19 = Turn-based • 1 move per 2 days
* 20 = No time limit • with friends only
|-
| 201 || bgaranking_mode || Game mode
* 0 = Normal mode
* 1 = Friendly mode (no ELO)
* 2 = Arena mode
|-
| 207 || game_language ||GAMESTATE_GAME_LANG
|-
| 300 || game_db_version ||GAMESTATE_GAMEVERSION: Current version of the game (when in production)
|-
| 301 || game_result_neutralized ||GAMESTATE_GAME_RESULT_NEUTRALIZED
|-
| 302 || neutralized_player_id ||GAMESTATE_NEUTRALIZED_PLAYER_ID
|-
| 304 || undo_moves_stored ||GAMESTATE_UNDO_MOVES_STORED
|-
| 305 || undo_moves_player ||GAMESTATE_UNDO_MOVES_PLAYER
|-
| 306 || lock_screen_timestamp ||GAMESTATE_LOCK_TIMESTAMP
|}

== Game states and active players ==

=== Activate player handling ===

; $this->activeNextPlayer()
: Make the next player active in the natural player order.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->getActivePlayerId()
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.

=== Multiple activate player handling ===

; $this->gamestate->setAllPlayersMultiactive()
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)

Example of usage:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

; $this->stMakeEveryoneActive()
:this method can be used in state machine to make everybody active as "st" method of multiplayeractive state, it just calls $this->gamestate->setAllPlayersMultiactive()

This is to be used in state declaration:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => \clienttranslate('Other player must place ships'),
"descriptionmyturn" => \clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'stMakeEveryoneActive',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "actionBla" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>

; $this->gamestate->setAllPlayersNonMultiactive( $next_state )
: All playing players are made inactive. Transition to next state

; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.
: "players" is the array of player id that should be made active. If "players" is not empty the value of "next_state" will be ignored (you can put whatever you want)
: If "bExclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array

: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise
Example of usage (see state declaration of playerTurnPlace above):
<pre>
function actionBla($args) {
$this->checkAction('actionBla');
// handle the action using $this->getCurrentPlayerId()
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');
}
</pre>

; $this->gamestate->getActivePlayerList()
: With this method you can retrieve the list of the active player at any time.
: During a "game" type gamestate, it will return a void array.
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.
: Note: you should only use this method in the latter case.

; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.
Example: you have player teams and you want to activate all players in one team
<pre>
$sql = "UPDATE `player` SET `player_is_multiactive` = '0'";
$this->DbQuery( $sql );
$sql = "UPDATE `player` SET `player_is_multiactive` = '1' WHERE `player_id` = '$player_id' AND `player_team` = '$team_no'";
$this->DbQuery( $sql );

$this->gamestate->updateMultiactiveOrNextState( 'error' );
</pre>

; updating database manually
: Use this helper function to change multiactive state without sending notification
<pre>
/**
* Changes values of multiactivity in db, does not sent notifications.
* To send notifications after use updateMultiactiveOrNextState
* @param number $player_id, player id <=0 or null - means ALL
* @param number $value - 1 multiactive, 0 non multiactive
*/
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {
if (! $value)
$value = 0;
else
$value = 1;
$sql = "UPDATE `player` SET `player_is_multiactive` = '$value' WHERE `player_zombie` = 0 and `player_eliminated` = 0";
if ($player_id > 0) {
$sql .= " AND `player_id` = $player_id";
}
$this->DbQuery($sql);
}
</pre>

;$this->gamestate->isPlayerActive($player_id)
:Return true if specified player is active right now.
:This method take into account game state type, ie nobody is active if game state is "game" and several players can be active if game state is "multiplayer"

;$this->bIndependantMultiactiveTable
:This flag can be set to true in constructor of game.php to force creation of second table to handle multiplayer states (normally these are in player table), this is very advanced feature.
:ONLY use it after you deploy you game to production if you receive unusual amount of bug report with dead lock symptoms DURING multiactiveplayer states
function __construct() {
...
$this->bIndependantMultiactiveTable=true;
}

=== States functions ===
; $this->gamestate->nextState( $transition )
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.

'''$this->gamestate->jumpToState($stateNum)'''
: Change current state to a new state. Important: the $stateNum parameter is the key of the state. See [[Your game state machine: states.inc.php]] for more information about states.
: Note: this is very advanced method, it should not be used in normal cases. Specific advanced cases include - jumping to specific state from "do_anytime" actions, jumping to dispatcher state or jumping to recovery state from zombie player function

; $this->checkAction( $actionName, $bThrowException=true )
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions that are not using [[Main game logic: yourgamename.game.php#Actions (autowired)|Action autowiring]], in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.

; $this->gamestate->checkPossibleAction( $action )
: (rarely used)
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.
: '''Note: This does NOT check either spectator or eliminated status, so those checks must be done manually.'''
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.

This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute this on client do not call checkAction on js side for this specific action.

function actionUnpass() {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

; $this->gamestate->state()
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.

$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}

I suggest to define and use this function in your php class to access state name:

public function getStateName() {
$state = $this->gamestate->state();
return $state['name'];
}

; $this->gamestate->state_id()
: Get the id of the current game state (rarely useful, its best to use name, unless you use constants for state ids)

; $this->gamestate->isMutiactiveState()
: Return true if we are in multipleactiveplayer state, false otherwise

=== Private parallel states ===

See the overview of private parallel states [[Your_game_state_machine:_states.inc.php#Private_parallel_states|here]].

; $this->gamestate->initializePrivateStateForAllActivePlayers()
: All active players in a multiactive state are entering a first private state defined in the master state's initialprivate parameter.
: Every time you need to start a private parallel states you need to call this or similar methods below.
: Note: at least one player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating some or all players
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method

$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

// in some cases you can move immediately some or all players to different private states
if ($someCondition) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("some_transition");
}

if ($other condition) {
//move single player to different state
$this->gamestate->nextPrivateState($specificPlayerId, "some_transition");
}
}
</pre>

; $this->gamestate->initializePrivateStateForPlayers($playerIds)
: Players with specified ids are entering a first private state defined in the master state initialprivate parameter.
: Same considerations apply as for the method above.

; $this->gamestate->initializePrivateState($playerId)
: Player with the specified id is entering a first private state defined in the master state initialprivate parameter.
: Everytime you need to start a private parallel states you need to call this or similar methods above
: Note: player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating that player
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function st_ChangeMind() {
// This player finished his move before, but now decides change something while other players are still active
// We activate the player and initialize his private state
$this->gamestate->setPlayersMultiactive([$this->getCurrentPlayerId()], "");
$this->gamestate->initializePrivateState(this->getCurrentPlayerId());

// It is also possible to move the player to some other specific state immediately
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->nextPrivateStateForAllActivePlayers($transition)
: All active players will transition to next private state by specified transition
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are.
: Note: this method can run action or args methods of the target state
: Note: this is usually used after initializing the private state to move players to specific private state according to the game logic

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method
$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

if ($specificOption) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("some_transition");
}
}
</pre>

; $this->gamestate->nextPrivateStateForPlayers($playerIds, $transition)
: Players with specified ids will transition to next private state specified by provided transition.
: Same considerations apply as for the method above.

; $this->gamestate->nextPrivateState($playerId, $transition)
: Player with specified id will transition to next private state specified by provided transition
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are.
: Note: this method can run action or args methods of the target state for specified player
: Note: this is usually used after some player actions to move to next private state

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->unsetPrivateStateForAllPlayers()
: All players private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used to clean up after leaving a master state in which private states were used, but can be used in other cases when we want to exit private parallel states and use a regular multiactive state for all players
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private states as they will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state after exiting private parallel states to avoid bugs.

Example of usage:
<pre>
function stNextRound() {
$this->gamestate->unsetPrivateStateForAllPlayers();
}
</pre>

; $this->gamestate->unsetPrivateStateForPlayers($playerIds, $transition)
: For players with specified ids private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used.
: Same considerations apply as for the method above.

; $this->gamestate->unsetPrivateState($playerId)
: For player with specified id private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used when deactivating player to clean up their parallel state
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private state as it will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state when not needed to avoid bugs.

Example of usage:
<pre>
function done() {
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), "newTurn" );
$this->gamestate->unsetPrivateState($this->getCurrentPlayerId());
}
</pre>

; $this->gamestate->setPrivateState($playerId, $newStateId)
: For player with specified id a new private state would be set
: Note: game needs to be in a master state which allows private parallel states
: Note: this should be rarely used as it doesn't check if the transition is allowed (it doesn't even specifies transition). This can be useful in very complex cases when standard state machine is not adequate (i.e. specific cards can lead to some micro action in various states where defining transitions back and forth can become very tedious.)
: Note: this method can run action or args methods of the target state for specified player

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state

if ($playerHaveSpecificCard)
return $this->gamestate->setPrivateState($this->getCurrentPlayerId(), 35);

$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->getPrivateState($playerId)
: This return the private state or null if not initialized or not in private state

==== State Arguments in Private parallel states ====

The args method called for private states will have the player_id passed to it, allowing you to customise the arguments returned for that player.

Example of usage:
<pre>
function argMyPrivateState($player_id) {
return array(
'my_data' => $this->getPlayerSpecificData($player_id)
);
}
</pre>

==== Inactive Players ====

During Private Parallel State, active players will be managed by the private state that is current assigned to them.

Inactive players will be managed by the master multipleactiveplayer state, so your client should respond to that state in order to display any status message advising players that they are waiting for others to have their turn, or to add any buttons that allow players to potentially "break in" and become active.

== Actions (autowired) ==
The action function should be prefixed by "act" and match the names specified in the "possibleactions" field on the state file.

If your actions start with "act", they will be autowired, that means you can declare action functions on the game.php file and call them directly from the front (with bgaPerformAction). You don't need to use action.php file anymore. The query param from the front request will be matched with the PHP variable of the same name, and it needs to be properly typed. This works for basic types: int, bool, float, string.

<pre>
public function actPlayCard(int $cardId) { ... }
</pre>
This function can be called from front-side with
<pre>
this.bgaPerformAction('actPlayCard', {
cardId: this.selectedCardId // the "cardId" param match the PHP variable name
});
</pre>

(Note: if you also declare the function in the action.php, it will be used instead of the autowiring)

If you want more complex types like int array or JSON, you'll need to specify it using the Param attributes. Same if the PHP variable name is different from the front query param, or if you want to specify the tests that should be realized on the parameter before calling the function.

=== Possible attributes ===

'''BoolParam(?string $name = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\BoolParam;

...

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raiseBet)

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raise) // NOTE: it's the same as actRaiseBet(bool $raise) if PHP var name and param name are the same
</pre>

'''IntParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntParam;

...

public function actPlayCard(#[IntParam(name: 'id')] int $cardId)

public function actSpendGold(#[IntParam(min: 1)] int $gold) // will trigger an exception if param is < 1

public function actPlaceCardOnSpot(int $cardId, #[IntParam(min: 1, max: 5)] int $spot) // will trigger an exception if spot is not in 1 to 5 range
</pre>

'''FloatParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''

Works the same way as IntParam, import is <code>use \Bga\GameFramework\Actions\Types\FloatParam;</code>

'''StringParam(?string $name = null, public ?bool $alphanum = false, public ?bool $alphanum_dash = false, public ?bool $base64 = false, public ?array $enum)'''
<pre>
use \Bga\GameFramework\Actions\Types\StringParam;

...

public function actSubmitWord(#[StringParam(alphanum: true)] string $word) // will trigger an exception if the word is not alphanum

public function actChooseAction(#[StringParam(enum: ['move', 'attack', 'pass'])] string $action) // will trigger an exception if the parameter doesn't match a value in the enum
</pre>
Note: You should do one of the tests of the attribute, or test it yourself on the function, to ensure the user is not sending forbidden characters to the function.

'''IntArrayParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntArrayParam;

...

public function actDiscardCards(#[IntArrayParam()] array $ids)

public function actDiscardCards(#[IntArrayParam(min: 2, max: 8)] array $ids) // will trigger an exception if the array length is not in the 2 to 8 range. It doesn't check the min/max of the array values!
</pre>

This function can be called from front-side with
<pre>
const selectedCardIds = [8, 12, 25];
this.bgaPerformAction('actDiscardCards', {
ids: selectedCardIds.join(',')
});
</pre>

'''JsonParam(?string $name = null, public ?bool $associative = true, public ?bool $alphanum = true)'''
<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...

public function actPlanComplexStuff(#[JsonParam()] array $answer) {} // force conversion to array during PHP json decode
public function actPlanComplexStuff(#[JsonParam(associative: false)] object $answer) {} // force conversion to object during PHP json decode

public function actPlanComplexStuff(#[JsonParam(associative: null)] mixed $answer) {} // default PHP json decode
</pre>

On client side:

const lala ={a: 2, b: "string", c: [1,2,4]};
this.bgaPerformAction("actPlanComplexStuff", {
answer: JSON.stringify(lala)
});

=== checkAction ===
The autowiring also triggers the checkAction, so you don't have to call it at the beginning of the function. If you need a function that should not trigger checkAction (an action that can be played during someone else turn), you can disable it this way:
<pre>
use \Bga\GameFramework\Actions\CheckAction;

...

#[CheckAction(false)]
public function actSetAutopass(bool $autopass)
...

#[CheckAction(false)]
public function actCancelChooseAction() {
$this->gamestate->checkPossibleAction('actCancelChooseAction');

</pre>

If you disable <code>checkAction</code>, you probably need to call <code>$this->gamestate->checkPossibleAction</code> instead at the beginning of your function. You likely also want to disable client checkAction calls implied by bgaPerformAction.

=== act prefix ===
The act prefix needed to activate the autowiring is not just to have some consistency in naming, it's also intended to protect your code. If we let autowired action to any function, a player may do a request to 'setPlayerScore' function, even if you never intended for it to be called front side, and it would allow almost undetectable cheating for anyone reading the code of your game.

== Players turn order ==

When table is created the "natural" player order is assigned to player at random, and stored in "read-only" field "player_no".
If you need to create a custom order you should never change natural order but have a separate data structure.
For example you can alter the players table to add another "custom_order" field, you can use state globals or you can use your natural board database,
to store meeple_color/position_location pair.
BGA currently does not provide any API to create/store custom player order.

'''getNextPlayerTable()'''

Return an associative array which associate each player with the next player around the table.

In addition, key 0 is associated to the first player to play.

Example: if three player with ID 1000, 2000 and 3000 are around the table, in this order, the method returns:
<pre>
array(
1000 => 2000,
2000 => 3000,
3000 => 1000,
0 => 1000
);
</pre>

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table. However there no 0 index here.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database
and have custom function to access it.

'''createNextPlayerTable( $players, $bLoop=true )'''

Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here.
If parmeter $bLoop is set to true then last player will points to first (creaing a loop), false otherwise.
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.

Note: This function '''DOES NOT''' change the order in database, it only creates a map using key/values as descibed.

Example of usage:
<pre>
function getNextPlayerTableCustom() {
$starting = $this->getStartingPlayer(); // custom function to get starting player
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player
return $this->createNextPlayerTable($player_ids, false); // create next player table in custom order
}
</pre>

<pre>
$table = $this->createNextPlayerTable([3000,2000,1000], false);

will return:
[
3000 => 2000,
2000 => 1000,
1000 => null,
0 => 3000
]
</pre>

== Notifications ==

To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.

'''IMPORTANT'''

Notifications are crutial part of BGA framework. Everything which players see, including all changes which happen on frontend (including setup), are done via notfications.

Some notifications are built into the framework, and others are custom, game specific notifications. Generally, you should not send or handle framework notifications, except exposed APIs.

Example of framework notifications:
* game setup (first time client connects to game)
* game state change
* active player change
Example of custom notifications:
* game piece moved
* player scored points

Notifications are queued, i.e. sent at the very end of the action, when it ends normally. It means that if you throw an exception for any reason (i.e: move is not allowed), no notifications will be sent to players.

Notification can be sent from the following functions (and transive calls):

* action handler (action* in game.php). It is a MUST actually. At least one notificaton must be sent (but it includes state transition which sends it)
* game state transition (st* in game.php)
* setupNewGame (after player tables setup is finished)

Notification cannot be sent from the following:
* .view.php
* .action.php
* material.inc.php
* constructor of .game.php
* arg* methods of .game.php

There are conceptually two types of notification:
* public - sent to all clients who are listening - that includes all players in the table as well as spectators
* private - sent only to a single player

The bundle of notifications sent at the end of an action is considered a single "move" and the table's move counter increases.
If you are ONLY sending private notifications during action handling, they will not have an associated <code>move_id</code> (to avoid this, add simple public notification with empty message).
In the rare case that you want to change this behavior, you can apply some hackery described in [[BGA_Studio_Cookbook]]

Note: the total notification size is now limited to 128K. It seems a lot, but don't forget that notification are bundled and only send at the end of an action which also INCLUDES all game state transitions that follow.

The notifications are handled on JS side by subscribing to notifications (only do it for custom notifications!). See [Game_interface_logic:_yourgamename.js#Notifications]

=== Notify ===

'''notify->all(string $notification_type,string $message,array $notification_args )'''

Send a notification to all players of the game and spectators (public).

* notification_type: A string that defines the type of your notification.

Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).

* message: A string that defines what is to be displayed in the game log.

You can use an empty string here (''). In this case, nothing is displayed in the game log.

Unless its empty, use "\clienttranslate" method to make sure string is translated.

You can use arguments in your $notification_log string, that refers to values defines in the "$notification_args" argument (see below).
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.

* notification_args: The arguments of your notifications, as an associative array.

This array will be transmitted to the game interface logic, in order the game interface can be updated.

Complete notify all example (from "Reversi"):

<pre>
$this->notify->all( "playDisc", \clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );
</pre>

You can see in the example above the use of the "\clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.

'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notify->player below.

'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.

'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments (except i18n, player_id and all arguments referenced in the message), are removed from these history notifications. If you need additional arguments in history notifications you can add special field <b>preserve</b> to notification arguments, like this:

<pre>
$this->notify->all( "playDisc", \clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y,
'preserve' => [ 'x', 'y' ]
) );
</pre>
In this example, fields x and y will be preserved when replaying history notification at the game load.

NOTE: The ONLY reason 'preserve' is useful if you have custom method to render notifications in game log which changes some text arguments into html (i.e. to insert the images instead of plain text). Do not use preserve "just in case" - it will only bloat the logs and make game load VERY slow.

'''Important''': If both public and private notifications are sent to the same player in the same action (AJAX call), they will initially appear in the log in the order in which they were called, but they are placed into the game log in the following order: All private notifications first, then all public notifications. This means that when the page is refreshed, or when a player loads an asynchronous game, if you have called any public notifications ''before'' the last private notification, they will appear out of order in the log.

==== HTML in Notifications ====

You CAN use some HTML inside your notification log, however it not recommended for many reasons:
* Its bad architecture, ui elements leak into server now you have to manage ui in many places
* If you decided to change something in ui in a future version, old games replay and tutorials may not work, since they use stored notifications (for example if the change occured during the game and later this game is used for tutorial)
* When you read log preview for old games its unreadable (this is log before you enter the game replay, useful for troubleshooting or game analysis)
* Its more data to transfer and store in db
* Its nightmare for translators, at least don't put HTML tags inside the "\clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.

If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

==== Recursive Notifications ====

If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but
an array itself, which contains 'log' and 'args', i.e.

$this->notify->all('message', \clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec' => ['log' => '${token_name} #${token_number}',
'args'=> ['token_name' => \clienttranslate('Boo'), 'token_number' => $number, 'i18n' => ['token_name'] ]
]
]);

==== Excluding some players ====

Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X will get a private notification "You draw the Ace of Spades", so you want them not to see the public one).

To send a notification to all players but have some clients ignore it, send it as normal from the server, but implement '''setIgnoreNotificationCheck''' on the client to ignore the message under given conditions. See the [[Game_interface_logic:_yourgamename.js#Ignoring_notifications]] documentation for more details. Note: do not sent private info with such notification, hiding something on client side is not a hacker safe.

==== Using player names ====

The variable for player name must be ${player_name} in order to be highlighted with the player color in the game log, it has to have matching 'player_id' argument in $notification_args. If you want a second player name in the log, name the variable ${player_name2} and $player_id2, etc. For the multiple player case, usage of player_id and player_name is not mandatory i.e. skipping to player_id1 and player_name1 is fine.

Special handling of arguments:
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.
* ${player_name1}, ${player_name2}, ${player_name3}, etc. work the same as above
In order for this to work you must pass corresponding player_idX AND player_nameX in args i.e.

$this->notify->all(
'buyAndPassCard',
\clienttranslate('${player_name} buys ${card_name} and passes it to ${player_name2}'),
[
'player_id' => $player1['id'],
'player_name' => $player1['name'],
'player_id2' => $player2['id'],
'player_name2' => $player2['name'],
...
]
);

Note: player_name is not translatable, never add it to i18n array

=== NotifyPlayer ===

'''notify->player(int $player_id, string $notification_type, string $message, $notification_args )'''

Same as above, except that the notification is sent to one player only. The player must be the player at the game table.

This method must be used each time some private information must be transmitted to a player.

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. Since its a private notification it may be more appropriate to use "you" insted

$this->notify->player($player_id,'message',\clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->notify->player($player_id,'message',\clienttranslate('${player_name} draws ${card_name}'), [ 'player_name' => $this->getPlayerNameById($player_id), ... ]);

Note: Spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notify->all() for any notification that spectators should get.

=== Notification decorators ===

'''notify->addDecorator(callable $fn)'''

Add a decorator function that will be called on notification args before each call of notify->all and notify->player. ''Note: it won't work with deprecated functions notifyAllPlayers and notifyPlayer.''

To avoid duplicating the code in your notification args, you can register decorators in your Game __construct function.
// in construct :
$this->notify->addDecorator(fn(string $message, array $args) => $this->decoratePlayerNameNotifArg($message, $args));
// could also be written this (ugly) way : $this->notify->addDecorator([$this, 'decoratePlayerNameNotifArg']);

// with the Utils functions
public function decoratePlayerNameNotifArg(string $message, array $args): array {
// if the notif message contains ${player_name} but it isn't set in the args, add it on args from $args['player_id']
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}
return $args;
}
With this example, you can call <code>$this->notify->all("pass", clienttranslate('${player_name} passes'), [ "player_id" => $player_id ]);</code> and the front will receive the player_name arg along the player_id one.

You can also declare it as an inline function :
// in construct :
this->notify->addDecorator(function(string $message, array $args) {
// if the notif message contains ${card_name} but it isn't set in the args, add it on args from $args['card']
// also set it up for translations by adding it to the i18n array
if (isset($args['card']) && !isset($args['card_name']) && str_contains($message, '${card_name}')) {
$args['card_name'] = $args['card']->name;
$args['i18n'][] = ['card_name'];
}
return $args;
});
With this example, you can call <code>$this->notify->all("playCard", clienttranslate('${player_name} plays ${card_name}'), [ "player_id" => $player_id, card => $card ]);</code> and the front will receive the card_name arg with the flag to translate it.

== Randomization ==

A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.

Here's are a list of techniques you should use in these situations, from the best to the worst.

=== Dice and bga_rand ===

'''\bga_rand( min, max )'''
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.

This is the preferred function you should use, because we are updating it when a better method is introduced.

As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.

In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).

Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".

=== Arrays ===

PHP's [https://www.php.net/array_rand array_rand()] and [https://www.php.net/shuffle shuffle()] functions are not cryptographically secure. Instead, the following code based on PHP's [https://www.php.net/random_int random_int()] provides a better method to choose a random key, value, or slice of an array. (the slice preserves keys)

<pre>
private function getRandomKey(array $array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomKey(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $key;
}
}

private function getRandomValue(array $array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomValue(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $value;
}
}

private function getRandomSlice(array $array, int $count)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomSlice(): Array is empty", E_USER_WARNING);
return null;
}
if ($count < 1 || $count > $size) {
trigger_error("getRandomSlice(): Invalid count $count for array with size $size", E_USER_WARNING);
return null;
}
$slice = [];
$randUnique = [];
while (count($randUnique) < $count) {
$rand = random_int(0, $size - 1);
if (array_key_exists($rand, $randUnique)) {
continue;
}
$randUnique[$rand] = true;
$slice += array_slice($array, $rand, 1, true);
}
return $slice;
}
</pre>

=== shuffle and cards shuffling ===

To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.

As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even if not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").

=== Other methods ===

Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.

== Game statistics ==

There are 2 types of statistics:
* a "player" statistic is a statistic associated to a player
* a "table" statistic is a statistic not associated to a player (global statistic for this game).

See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.

'''initStat( $table_or_player, $name, $value, $player_id = null )'''

Create a statistic entry with a default value.

This method must be called for each statistic of your game, in your setupNewGame method.
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.

'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.

'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.

'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.

'''setStat( $value, $name, $player_id = null )'''

Set a statistic $name to $value.

If "$player_id" is not specified, setStat consider it is a TABLE statistic.

If "$player_id" is specified, setStat consider it is a PLAYER statistic.

'''incStat( $delta, $name, $player_id = null )'''

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.

'''getStat( $name, $player_id = null )'''

Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...

During the game, you update player's score directly by updating "player_score" field of "player" table in database.

Examples:
<pre>

// +2 points to active player
$this->DbQuery( "UPDATE `player` SET `player_score` = `player_score` + 2 WHERE `player_id` = '".$this->getActivePlayerId()."'" );

// Set score of active player to 5
$this->DbQuery( "UPDATE `player` SET `player_score` = 5 WHERE `player_id` = '".$this->getActivePlayerId()."'" );

</pre>

Note: don't forget to notify the client side in order the score control can be updated accordingly.

=== Tie breaker ===

Tie breaker is used when two players get the same score at the end of a game.

Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.

Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.

When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:

<pre>
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),
</pre>

This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.

See also [https://en.doc.boardgamearena.com/Game_meta-information:_gameinfos.inc.php#Multiple_tie_breaker_management Multiple Tie Breaker Management].

=== Co-operative game ===

To make everyone win/lose together in a full-coop game:

Add the following in gameinfos.inc.php :
'is_coop' => 1, // full cooperative

Assign a score of zero to everyone if it's a loss.
Assign the same score > 0 to everyone if it's a win.

=== Semi-coop ===

If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.

=== Only "winners" and "losers" ===

For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

In this case:
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.
* Add the following lines to gameinfos.inc.php:

<pre>
// 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' => true,
</pre>

Werewolves and Coup are implemented like this, as you can see here:
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults

Adding this has the following effects:
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.

Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).

=== Solo ===

If game supports solo variant, a negative or zero score means defeat, a positive score means victory.

=== Player elimination ===

In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.

This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").

Usage:

* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).
* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.

'''Important:''' this should not be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules), except if in the course of the game, the zombie player is eliminated according to the rules.

'''Important:''' When all surviving players are eliminated at the same time BGA framework causes the game to be abandoned automatically.
To circumvent this, the game should leave 1 player not eliminated but change final scores accordingly and end the game.

=== Scoring Helper functions ===

These functions should have been API but they are not, just add them to your php game and use for every game.

// get score
function dbGetScore($player_id) {
return $this->getUniqueValueFromDB("SELECT `player_score` FROM `player` WHERE `player_id` = '$player_id'");
}

// set score
function dbSetScore($player_id, $count) {
$this->DbQuery("UPDATE `player` SET `player_score` = '$count' WHERE `player_id` = '$player_id'");
}

// set aux score (tie breaker)
function dbSetAuxScore($player_id, $score) {
$this->DbQuery("UPDATE `player` SET `player_score_aux` = $score WHERE `player_id` = '$player_id'");
}

// increment score (can be negative too)
function dbIncScore($player_id, $inc) {
$count = $this->dbGetScore($player_id);
if ($inc != 0) {
$count += $inc;
$this->dbSetScore($player_id, $count);
}
return $count;
}

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player in real time game. It does not affect turn based games.
: Standard extra time (when you don't pass $specific_time) depends on the speed of the game (small with "slow" game option, bigger with other options).
: You can also specify an exact time to add, in seconds, with the "specific_time" argument (rarely used). Using $specific_time is not recommended as this does not adjust for the game speed.
: Important Note: the total reflection time cannot be more than time allowed for the turn. So you can never make it 10 minutes if turn max is 3 min (the max is determined by game speed). As a consequence there is no point adding this at the begging of the turn of in game setup, it only matters after the action which does not lead to turn end (which is when this player becomes inactive).
: Note: standard extra time is automatically doubled for begginer

function actionBla($args) {
$this->checkAction('actionBla');
$playerId = $this->getActivePlayerId();
$this->giveExtraTime($player_id);
// do some inter-turn action
$this->notifyAll(...);
// no state transition as this player did an action but stayed active
}

; '''$this->tableOptions->isTurnBased(): bool'''
: Returns true if game is turn based
:
; '''$this->tableOptions->isRealTime(): bool'''
: Returns true if game is in real time

== Undo moves ==

Please read our [[BGA Undo policy]] before.

'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:
'db_undo_support' => true

Note: if you deploy undo support after game is in production this will take into effect for new games only, old games will give user an error if user choses Undo action, but otherwise it should not affect them.

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matters if you transition to game state not to user state after), this may affect what you end up saving.

; function undoRestorePoint()
: Restore the situation previously saved as an "Undo save point".
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).

function actionUndo() {
$this->checkAction('actionUndo');
$this->undoRestorePoint();
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)
}

'''Important note''': if you are reading game state variable right after restore (without changing state first) it won't work properly as the global table cache is not automatically refreshed after undoRestorePoint(). So you should either change state immediately to refresh game state values, or use $this->gamestate->reloadState() to refresh the state. If you choose to do the latest, be aware that this will bring the state machine back to the state during which the save point snapshot has been taken using undoSavepoint() (which means your transition you do after has to declared in the state which was saved, not in the state which was active for your actionUndo())

== Managing errors and exceptions ==

Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.

; throw new \BgaUserException ( $error_message)
: Base class to notify a user error
: You must throw this exception when a player wants to do something that they are not allowed to do.
: The error message will be shown to the player as a "red message".
: The error message must be translated, make sure you use self::_() or $this->_() here and NOT clientranslate()
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Example from Gomoku:
<pre>
throw new \BgaUserException(clienttranslate("There is already a stone on this intersection, you can't play there"));
</pre>

; throw new \BgaVisibleSystemException ( $error_message)
: You must throw this exception when you detect something that is not supposed to happened in your code.
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.

; throw new \BgaSystemException ( $error_message)
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.

Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.

Each time a zombie player must play, your "zombieTurn" method is called.

Parameters:
* $state: the name of the current game state.
* $active_player: the id of the active player.

Most of the time, your zombieTurn method looks like this:

<pre>
function zombieTurn( $state, $active_player )
{
$statename = $state['name'];

if( $statename == 'myFirstGameState'
|| $statename == 'my2ndGameState'
|| $statename == 'my3rdGameState'
....
)
{
$this->gamestate->nextState( "zombiePass" );
}
else
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );
}
</pre>

Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.

'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.

== User preferences ==
'''$this->userPreferences->get(int $playerId, int $prefId): ?int'''

Return the value of a user preference for a player. It will return the value currently selected in the select combo box, in the top-right menu.

== Player color preferences ==

BGA premium users may choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:

On your gameinfos.inc.php file, add the following lines :

// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.
'favorite_colors_support' => true,

Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.

$gameinfos = $this->getGameinfos();
...
if ($gameinfos['favorite_colors_support'])
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()
$this->reloadPlayersBasicInfos();

The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.

Note that you must update the colors to indicate the colors available for your game.

Some important remarks:
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.

=== Custom color assignments ===
Some colors don't play nicely with BGA's color difference algorithm. If you receive feedback that colors are not well chosen, you can bypass the BGA algorithm by specifying a map from user preference colors to game colors.

For example, you may wish to assign BGA's blue to your game's baby blue: <code>"0000ff" /* Blue */ => "89CFF0",</code> whereas otherwise, a deep purple might be chosen instead. Just be sure that the assigned colors are also present in the <code>player_colors</code> array passed to <code>reattributeColorsBasedOnPreferences</code>, otherwise the assignment will be ignored.

To do this, implement this method in your <code>X.game.php</code> class.

Note: the user preference colors (the keys in the returned array) should not be modified, or the code may not work as expected. These are the colors players can choose between in their profile.
/**
* Returns an array of user preference colors to game colors.
* Game colors must be among those which are passed to reattributeColorsBasedOnPreferences()
* Each game color can be an array of suitable colors, or a single color:
* [
* // The first available color chosen:
* 'ff0000' => ['990000', 'aa1122'],
* // This color is chosen, if available
* '0000ff' => '000099',
* ]
* If no color can be matched from this array, then the default implementation is used.
*/
function getSpecificColorPairings(): array {
return array(
"ff0000" /* Red */ => null,
"008000" /* Green */ => null,
"0000ff" /* Blue */ => null,
"ffa500" /* Yellow */ => null,
"000000" /* Black */ => null,
"ffffff" /* White */ => null,
"e94190" /* Pink */ => null,
"982fff" /* Purple */ => null,
"72c3b1" /* Cyan */ => null,
"f07f16" /* Orange */ => null,
"bdd002" /* Khaki green */ => null,
"7b7b7b" /* Gray */ => null,
);
}

== Legacy games API ==

For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.

This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:
* keeping a player preference/settings (=> player preferences and game options should be used instead)
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.

You should use it for:
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.

Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:

try
{
$this->storeLegacyTeamData( $my_data );
}
catch( \feException $e ) // \feException is a base class of \BgaSystemException and others...
{
if( $e->getCode() == FEX_legacy_size_exceeded )
{
// Do something here to free some space in Legacy data (ex: by removing some variables)
}
else
throw $e;
}

The keys may only contain letters and numbers, underscore seems not to be allowed.

; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )
: Store some data associated with $key for the given user / current game
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used
: in a future table with the same game.
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games.
: TTL is a time-to-live: the maximum, and default, is 365 days.
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)
: NOTICE: You can store some persistant data across all tables from your game using the specific player_id 0 which is unused. In such case, it's even more important to manage correctly the size of your data to avoid any exception or issue while storing updated data (ie. you can use this for some kind of leaderbord for solo game or contest)
: Note: This function cannot be called during game setup (will throw an error).

; function retrieveLegacyData( $player_id, $key )
: Get data associated with $key for the current game
: This data is common to ALL tables from the same game for this player, and persist from one table to another.
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible
: Note: you can use '%' in $key to retrieve all keys matching the given patterns

; function removeLegacyData( $player_id, $key )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; function storeLegacyTeamData( $data, $ttl = 365 )
: Same as storeLegacyData, except that it stores some data for the whole team within the current table and does not use a key
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.
: This is useful for games which are intended to be played several time by the same team.
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens

; function retrieveLegacyTeamData()
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; function removeLegacyTeamData()
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

== Players text input and moderation ==
This section concerns only games where the players have to write some words to play: games based on words, like "Just one" or "Codenames".

Some players will use your game to write insults or profanities. As this is part of the game and not in the game chat, these words cannot be reported by players and moderated.

If you met the following situation:

* You are asking a player to type a text (word(s) or sentence)
* The player can enter any text (this is not a pre-selection or anything you can control)
* This text is visible by at least one other player

Then, you must use the following method:

'''function logTextForModeration( $player_id, $text )'''

player_id = player who write the text

text = text that has been written

This function will have no visible consequence for your game, but will allow players to report the text to moderators if something happens.

== Language dependent games API ==

This API is used for games that are heavily language dependent. Two most common use cases are:
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)

If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages they speak.

There is a new property language_dependency in gameinfos.inc.php which can be set like this:
'language_dependency' => false, //or if the property is missing, the game is not language dependent
'language_dependency' => true, //all players at the table must speak the same language
'language_dependency' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages

In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.
; function getGameLanguage()
: Returns an index of the selected language as defined in gameinfos.inc.php.

Languages currently available on BGA are:
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)

== Debugging and Tracing ==

To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.

$this->debug("Ahh!");
$this->dump('my_var',$my_var);

See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.

== Creating other classes ==

You can create other classes in the <code>modules/php</code> dir, next to your <code>Game.php</code> file.

If they are names following the PSR-4, they will be autoloaded by BGA (no require_once needed). This doesn't work for the "legacy way" (=<code>YourGameName.game.php</code> at the game root dir).

For example, writing <code>new ScoreManager()</code> in your Game file will try to load the class <code>ScoreManager</code> of namespace <code>Bga\Games\YourGameName</code> in <code>modules/php/ScoreManager.php</code>

Don't forget to add namespace <code>Bga\Games\YouGameName;</code> at the beginning of your module.

You can even put these classes in sublevels : the class <code>Bga\Games\YourGameName\Cards\StandardCard</code> will be automatically loaded if it is stored in <code>modules/php/Cards/StandardCard.php</code>

[[Category:Studio]]

BGA Code Sharing

2025-04-18T10:52:01Z

Nalka: Add dice hospital : emergency roll to list of githubs

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW ; https://codepen.io/VictoriaLa/pen/JjZNezr
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode ; https://codepen.io/VictoriaLa/pen/QWBBbwz
|
|-
| Die: 8 sided
| https://codepen.io/VictoriaLa/pen/YzMPeGq
| code pen
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP <nowiki/> https://codepen.io/hoursgoby/pen/GRwQzxo
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
|Dice
|[https://github.com/thoun/bga-dice/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-dice/demo/index.html Demo] (not used yet)
|Handle dice display and animation '''WORK IN PROGRESS''' Only d6 is started
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout, zoom and navigation for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout just by using css
|-
|Zoom
|[https://github.com/thoun/bga-zoom/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-zoom/demo/index.html Demo] (visible on Knarr, Azul, Abyss, ...)
|Allow the user to zoom on the game board. Include the controls to zoom, and handle the scale applied to the HTML element.
|-
|Jump to
|[https://github.com/thoun/bga-jump-to/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-jump-to/demo/index.html Demo] (visible on Knarr, Elawa)
|Add floating controls to quickly jump to a player's table
|-
! colspan="3" | Algorithms
|-
|Hex grid
|tapestry,Tumbleweed,gaia project,Gold West
|
|-
|Shortest path on hex grid
|memoir 44
| Dijkstra
|-
|Largest area on hex grid
|tapestry, ...
|
|-
|Largest area on square grid
|king domino, ...
|
|-
|Tetris pieces
|patchwork, ...
|Matrix manupations to rotate, flip and fit tetris pieces
|-
|Line of sights on hex grid
|memoir 44
|Find intersecting hexes on a line between two cells
|-
! colspan="3" | Alternative implementations of BGA modules
|-
|Scrollmap with zoom
|https://github.com/yansnow78/bga_scrollmap
|you can find it in cacao, ginkgopilis, sagani, bigmonster,dominoes, Carcassonne hunters and gatherers and many others. <nowiki>#</nowiki> improvements compare to scrollmap:
- add zoom capabilities

- add possibility to adjust pan delta to tile size when clicking on arrows

- allow zoom with scroll wheel. only allow zoom with wheel if alt or ctrl or shift are pressed by default. add possibility to select which key need to be pressed when zooming with wheel

- allow pan/scroll and pinch zoom on smartphone. only allow 2 fingers to start scrolling by default, one finger is for page scrolling

- make clickable area of buttons a bit bigger on smartphone

- improve animation between game board and player bards thanks to an animation_div

- add support to long click on buttons (continuous scroll or zoom or enlarge/reduce until button released)
|-
|Scrollmap Plus
|patchwork
|Implementation with some bugs fixed, improved drag support and ability to use only one direction (i.e. only horizontal like carousel). Found in modules/extscrollmap.js
|-
|Cards
|[https://github.com/thoun/bga-cards/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-cards/demo/index.html Demo] (visible on Knarr, King of Tokyo, Abyss, ...)
|Alternative to BGA Stock component, using CSS transitions instead of dojo animations.
|-
! colspan="3" | Assorted stuff
|-
|Help
|[https://github.com/thoun/bga-help/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-help/demo/index.html Demo] (visible on Knarr)
|Add floating help buttons at the bottom left corner of the screen

|}

== Projects ==

Add the game name, a link to repository and nickname of the developer on bga (same as used for dev forum), and short description. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] topic on github.

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
! COMMENT
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
| Examples of various game components and PHP stubs of framework code to make IDE happy
|-
| Vanilla Typescipt template (not a game)
| https://github.com/elaskavaia/bga-dojoless
| Victoria_La
| Project template for typescript and using minimal dojo, good for vscode - type checking, auto-complete, navigation
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
|BGA-boilerplate
|https://github.com/bga-devs/tisaac-boilerplate/
|Tisaac (and Vincentt ?)
|Main boilerplate with extended "basic" function and code structure
|-
|BGA Type Safe Template
|https://github.com/NevinAF/bga-ts-template
|NevinAF
|Full typing of all BGA Framework components.
|-
! GAME
! CODE LINK
! DEVELOPER
! COMMENT
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Abandon All Artichokes
| https://github.com/0-wiz-0/bga-abandonallartichokes
| __wiz__, rojomojo
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
|Big Monster
|https://github.com/nmatton/bigmonster
|nicotacotac
|-
| Bonsai
| https://github.com/PhilipDavis/BGA-Bonsai
| Philip Davis (pdw3)
| Action stack for client-side undo system; generator functions to model complex turn workflows; infinite hex grid with auto resizing; all data in a single JSON blob; animated scorepad
|-
| Canosa
| https://codeberg.org/halibut/Canosa
| junibegood
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
|Copenhagen
|https://github.com/JoeProgram/bga-copenhagen
|JoeProgram
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
|Dice Hospital : Emergency Roll
|https://github.com/firgon/dicehospitaler
|firgon
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Fled
| https://github.com/PhilipDavis/BGA-Fled
| Philip Davis (pdw3)
| All data in a single JSON blob
|-
|Flip Freighters
|https://github.com/joesimpson/bga-flipfreighters
|joesimpson
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| For-Ex
| https://github.com/Fnordistan/forex
| AmadanNaBriona
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| In the Year of the Dragon (10th Anniversary Edition)
| https://github.com/Fnordistan/ityotd
| AmadanNaBriona
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| The Lady and the Tiger (Doors)
| https://github.com/Fnordistan/ladyandthetiger
| AmadanNaBriona
|-
|Linkage
|https://github.com/ShaPhi7/linkage
|ShaPhi7
|
|-
|Love Letter
|https://github.com/ShaPhi7/loveletter
|ShaPhi7
|
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
|Ninjan
|https://github.com/dorukkicikoglu/bga-ninjan
|fenadoruk
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
|Now Boarding
|https://github.com/quietmint/bga-nowboarding
|quietmint
|-
|Odin
|https://github.com/dorukkicikoglu/bga-odin
|fenadoruk
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| Perikles
| https://github.com/Fnordistan/perikles
| AmadanNaBriona
|
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Tic Tac Match
| https://github.com/leocaseiro/bga-tictacmatch
| Leo Caseiro
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).

If it is not visible: a) it has no bgg id b) it is already published (use radio button to switch) c) it is an old game not developed on studio.

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

[[Category:Studio]]

Gamehelpzenith

2025-02-09T19:57:35Z

Nalka: Add bonus tokens list and repartition

== The Game ==

Zenith is tug-of-war style game, where you and your opponent fight for control the 5 planets and compete to be first to achieve one of the three victory conditions:

Absolute Victory: Gain 3 influence tokens from the same planet.

Democratic Victory: Gain 4 influence tokens from different planets.

Popular Victory: Gain 5 influence tokens from any combination of planets.

<b>Winning</b>

Play ends immediately when a player achieves one of these win conditions.

<b>Influence</b>

In the game, gaining influence on a planet means moving that planet's influence token towards you by the number of spaces equal to the amount of influence gained. If you move a planet's influence token to your edge of the board you keep that influence token and a new token is placed on the planet. Excess influence when arriving at the edge of the board is lost.

<b>Planets</b>

The planets and their respective colours are:

* '''{{pill|Mercury|white|purple}}''' = Purple
* '''{{pill|Venus|white|orange}}''' = Orange
* '''{{pill|Terra|white|blue}}''' = Blue
* '''{{pill|Mars|white|red}}''' = Red
* '''{{pill|Jupiter|white|green}}''' = Green

== Beginning of the Game ==
Player 1 is decided randomly. Player 2 gains 1 Terra influence. Both players start with a hand of 4 cards.

== Turn Structure ==
Select a card from your hand to use for one of three actions:
=== 1. Diplomacy Action ===
:Discard the card to gain the Leader Badge, plus the diplomacy bonus for the faction of the card you are discarding (Animod, Human or Robot). If gaining the Leader Badge, take it on the silver side. If you already have the Leader Badge on the silver side, turn it to the gold side. Each side of the Leader Badge increases your hand size by one; silver = 5 cards, gold = 6 cards. If you already have the Leader Badge on the gold side you only gain the diplomacy faction bonus, your hand size remains as 6.

=== 2. Influence Action ===
:Spend the credit cost of a card (grey resource value shown in the top left) to play that card to your stack and carry out the card's effects, from left to right. All cards provide 1 influence in its planet, plus some other effects written on the card. Effects range from gaining more influence in the same or other planets, gaining new cards to your stacks, removing cards from your opponent's stacks or even stealing cards from your opponent's stacks into your stacks.

:'''Credit Discount'''
:For each card previously placed in your stack for that planet, you reduce the card's credit cost by 1. For example, if your Mercury stack has 5 purple cards in it, a purple card with a credit cost of 8 would cost you 3 credits to play (8-5). If you have equal or more cards in your stack than the cost of a card, that card is free to play. You cannot gain credits for a larger stack size then the card's credit cost.

=== 3. Technology Action ===
:Discard the card to progress your technology marker (grey or black) on the technology track for the faction of the card (Animod, Human or Robot). To carry out this action you have to spend the required Zenithium (gold resource) to pay for the next level on the respective technology track (ranging in value from 1 to 5). When your technology marker progresses to the next level you gain the effect of that level PLUS all previous levels on that faction's track. Markers can only move one level per turn.
:
:'''Technology track row bonus'''
:When you develop all three technology tracks to one of the first three levels you gain influence on a planet of your choice. The number of influence gained matches the technology level; developing all three technology tracks to level 1 gains you 1 influence, developing all three technology tracks to level 2 gains you 2 influence and developing all three technology tracks to level 3 gains you 3 influence. This is a one-time bonus and doesn't apply to levels 4 and 5.

== Bonus tokens ==
There are 16 bonus tokens in the game; 8 face up and 8 face down in a draw pile. The face up tokens are on each planet and on each technology track level 2 space. When a player is first to gain an influence token for a planet, or first to arrive at level 2 on a technology track they gain the effect of the respective face up bonus token. The face down tokens can also be achieved in other ways, giving a random, unknown bonus. These bonus tokens provide a one-time bonus and once they've been claimed they are removed and not replaced. These tokens provide a variety of bonus from gaining extra credits, Zenithium or cards, and even stealing resources or cards from your opponent.

There are 8 different kinds of bonus tokens:

* Gain 3 credits (2 copies)
* Gain 4 credits (2 copies)
* Gain 1 influence on any planet (4 copies)
* Take the leader badge (2 copies)
* Gain 1 Zenithium (3 copies)
* Mobilize 2 cards (1 copy)
* Exile 2 cards (1 copy)
* Transfer 1 card (1 copy)

== End of Turn ==
Draw new cards back up to your current hand size; default hand size of 4, hand size of 5 if you have the Leader Badge on the silver side or hand size of 6 if you have the Leader Badge on the gold side.
If you already have a larger hand than your current allowed hand size you will not draw new cards but you will keep all your cards and will not lose any excess. Play then passes to your opponent.