Board Game Arena - User contributions [en]

Main game logic: Game.php

2025-09-06T21:14:00Z

ShaPhi7: /* Excluding some players */

{{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, '''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 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, ?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->globals->get(FIRST_PLAYER_ID);
...
$selectedCardsIds = $this->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->globals->set(UNDO, $undo);

$undo = $this->globals->get(UNDO); // will return an stdClass
$undo = $this->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>

'''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 ACTIVE_PLAYER or MULTIPLE_ACTIVE_PLAYER 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 ACTIVE_PLAYER or MULTIPLE_ACTIVE_PLAYER 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 ACTIVE_PLAYER or MULTIPLE_ACTIVE_PLAYER 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 MULTIPLE_ACTIVE_PLAYER
: Note: avoid using this method in a MULTIPLE_ACTIVE_PLAYER 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 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

; $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 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.
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 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.
: 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 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)

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 send private info with such notification, hiding something on client side is not 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".
: If the error will be displayed to the player (BgaUserException), the error message should be translated (with clientranslate() and args)
: 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>
Example with translated BgaUserException using args :
<pre>
throw new \BgaUserException(clienttranslate('You must play a card bigger than ${min}', args: [min => $minCardValue]));
</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". 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->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->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->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->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->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->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->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->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.

== 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]]

Stock

2025-07-13T10:08:53Z

ShaPhi7: /* Selection */ Corrected default

{{Studio_Framework_Navigation}}

== Overview ==

'''Stock''' is a javascript component that you can use in your game interface to display a set of elements of the same size that need to be arranged in single or multiple lines.

Stock is very flexible and is the most used component in BGA games.

Examples of stock use cases:

* Display a set of cards, typically hands (examples: ''Hearts'', ''Seasons'', ''The Boss'', ''Race for the Galaxy'').
* Display items in player panels (examples: ''Takenoko'', ''Amyitis'', ...)
* ... Many other situations. For example, black dice and cubes on cards in ''Troyes'' are displayed with stock components.

Using stock:

* Your items are arranged nicely and sorted by type.
* When adding or removing items to a set, all items slide smoothly to their new position in the set.
* Selecting and unselecting items are built-in functions.
* You don't have to worry about inserting/removing HTML code; the entire life cycle of the stock is managed by the component.

== Using stock: a simple example ==

Let's have a look at how the stock is used in the game ''Hearts'' to display a hand of standard cards.

First, don't forget to add "ebg/stock" as a dependency in your js file:

<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in the Javascript "setup" method like this:

<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

Explanations:
* We create a new stock object for the player hand.
* As parameters of the "create" method, we provide the width/height of an item (a card), and the div container "myhand" - which is a simple empty "div" element defined in our HTML template (.tpl).

Then, we must tell the stock what items it is going to display during its life: the 52 cards of a standard card game. Of course, we did not create 52 different images, but a "CSS sprite" image named "cards.jpg" with the cards arranged in 4 rows and 13 columns.

Here's how we tell stock what items to display:

<pre>
// Specify that there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create card types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
</pre>

Explanation:

* First, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call the "addItemType" method that creates the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

Note: In this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".

From now on, if we need to add a card - for example, the 5 of Hearts - to a player's hand, we can do this:

<pre>
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );
</pre>

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:

<pre>
this.playerHand.addToStockWithId( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );
</pre>

If afterwards we want to remove this card from the stock:

<pre>
this.playerHand.removeFromStockById( my_card_id );
</pre>

== Complete stock component reference ==

for interest, the source is available here : https://x.boardgamearena.net/data/themereleases/220811-1000/js/modules/stock.js (this link may change with new release)

In the reference below the type StockItem refers to a record { id: number, type: number }, i.e. {id: 22, type: 3}

And StockItemType is record {weight: number, image: string, image_position: number}

=== Creation ===

'''create( page, container_div, item_width, item_height ):'''

With create, you create a new stock component.

Parameters:
* page: the container page. Usually: "this".
* container_div: the container "div" element. Its not an id, if you have id you can pass $(id). It must exists.
* width and height (in pixels) for the stock component.

(See ''Hearts'' example above).

'''addItemType(type: number, weight: number, image: string, image_position: number ): void'''

Define a new type of item (StockItemtType) and add it to the stock with given type id.

This is mandatory to define a new item type before adding it to the stock. Example: if you want to have a stock contain cubes of 3 different colors, you must add 3 item types (one for each color).

Parameters:
* type: id of the type to add. You can choose any positive integer. All item types must have distinct IDs.
* weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items; in this case, they are not sorted and their order might change randomly at any time.
* image: URL of item image. Most of the time, you will use a CSS sprite for stock items, so you have to specify CSS sprite image here.

Be careful: you must specify the image url as this:

<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>

* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.

''Important'': if there is more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite, see image_items_per_row below:

'''image_items_per_row'''
Class member to set number of columns in css sprite (or how many items per row). I.e. if you sprite is 4 cards horizontally and 6 vertically, you have to set it to 4.
<pre>
// Specify that there are 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 4;
</pre>

=== Add/Remove items ===

'''addToStock( type, from )'''

Add an item to the stock, with the specified type, but without a unique ID.

To make your life easier, in most cases we suggest you use '''addToStockWithId''' in order to give an ID to the item added. '''addToStock''' is suitable when you are using a stock to control items that are generic game materials that don't need to be tracked individually (example: a bunch of money tokens).

Parameters:
* type: ID of the item type to use (as specified in "addItemType")
* from: OPTIONAL: if you specify an HTML item here, the item will appear on this item and will be slid to its position on the stock item.

Example:
<pre>
// Add a money token to the "player money" stock.
// The money token will appear on "player_id" player panel and will move to its position.
this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );
</pre>

Important: for a given stock control, you must use either '''addToStock''' or '''addToStockWithId''', but NEVER BOTH OF THEM.

'''addToStockWithId( type, id, from )'''

This is the same method as '''addToStock''', except that it also associates an ID with the newly created item.

This is especially useful:

* When you need to know which item(s) have been selected by the user (see '''getSelectedItems''').
* When you need to remove a specific item from the stock with '''removeFromStockById'''.

'''removeFromStock( type, to, noupdate )'''

Remove an item of the specific type from the stock.

'to' is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the Stock slides to this HTML element before it disappears. Note that this method does not expose the associated animation object, however, so it's not possible to trigger other actions when it finishes, for example. If you need to do that, use Dojo's slideToObject() instead.

'noupdate' is an optional parameter. If set to "true" it will prevent the Stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. If you pass noupdate you have to call updateDisplay() after all items are removed.

'''removeFromStockById( id, to, noupdate )'''

Remove an item with a specific ID from the stock.

'to' is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the Stock slides to this HTML element before it disappears. Note that this method does not expose the associated animation object, however, so it's not possible to trigger other actions when it finishes, for example. If you need to do that, use Dojo's slideToObject() instead.

'noupdate' is an optional parameter. If set to "true" it will prevent the Stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. If you pass noupdate you have to call updateDisplay() after all items are removed.

'''removeAll()'''

Remove all items from the stock.

'''removeAllTo( to )'''

Remove all items from the stock. If "to" contains the ID of an HTML element, the item removed from the stock slides to this HTML element before it disappears.

=== Getters ===

'''getPresentTypeList()'''

Return an array with all the types of items present in the stock right now.

Example:
<pre>
this.myStockControl.removeAll();
this.myStockControl.addToStock( 65 );
this.myStockControl.addToStock( 34 );
this.myStockControl.addToStock( 89 );
this.myStockControl.addToStock( 65 );

// The following returns: { 34:1, 65:1, 89:1 }
var item_types = this.myStockControl.getPresentTypeList();
</pre>

'''count():'''

Return the total number of items in the stock right now.

'''getAllItems()'''

Get all items (same format as getSelectedItems and getUnselectedItems).

'''getItemDivId(id)'''

Get the div id using the stock item id (to manipulate element properties directly).

'''getItemById(id)'''

Get the Stock item with the id in parameter
ex : return the object { type:1, id: 1001 }

'''getItemWeightById(id: number): number|null'''

Returns item weigh given id. or null if not found

'''container_div'''

Member containing div of the stock container in dom (container_div.id would be it's id)

'''control_name'''
Its id of container_div above

=== Selection ===

'''setSelectionMode( mode )'''

For each stock control, you can specify a selection mode:
* 0: no item can be selected by the player.
* 1 (default): a maximum of one item can be selected by the player at a time.
* 2: multiple items can be selected by the player at the same time.

'''setSelectionAppearance( type )'''

For each stock control, you can specify a selection highlighting type:
* 'border': there will be a red border around selected items (this is the default). The attribute 'apparenceBorderWidth' can be used to manage the width of the border (in pixels).
* 'disappear': the selected item will fade out and disappear. This is useful when the selection has the effect of destroying the item.
* 'class': there will be an extra '''stockitem_selected''' css class added to the element when it is selected (and removed when unselected). The name of the class can be changed by using the '''selectionClass''' attribute. You can also override the default class in the css file for your game but beware of the '''!important''' keyword.

By default this class definition is:
<pre>
.stockitem_selected {
border: 2px solid red ! important;
}
</pre>

If you want to override it (for example, to change the border color) add this in your <game>.css file:
<pre>
.stockitem_selected {
border: 2px solid orange ! important;
}
</pre>

'''isSelected( id )'''

Return a boolean indicating whether the specified item id has been selected.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''selectItemsByType(type: number): void'''

Selectes all items in a stock with given type (in addition to previous selection)

'''unselectItemsByType(type: number): void'''

Unselects all items in a stock with given type

'''onChangeSelection'''

This callback method is called when the player selects/unselects an item of the stock.

You can connect this to one of your methods like this:

<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

onMyMethodToCall: function( control_name, item_id )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();

// (do something)
},
</pre>

Nota bene:
- The "control_name" argument is the ID (the "DOM" id) of the "div" container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.
- The "item_id" argument is the stock ID (index) of the stock item that has just been selected/unselected.

'''getSelectedItems()'''

Return the list of selected items, as an array with the following format:
<pre>
[
{ type:1, id: 1001 },
{ type:1, id: 1002 },
{ type:3, id: 1003 }
...
]
</pre>

'''getUnselectedItems()'''

Same as the previous one, but return unselected item instead of seleted ones.

=== Layout ===

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their positions to their original ones, you can call this method.
Note: it is the same as updateDisplay() without arugment, not sure why there are two methods.

'''updateDisplay(from)'''
Update the display completely (if 'from' is defined: moves new items from this location).

Example code if you change the underlying stock item, or otherwise want to make the stock item refresh:
<pre>
this.myStockControl.updateDisplay();
</pre>

'''item_margin'''

By default, there is a margin of 5px between the items of a stock. You can change the member variable "item_margin" to change this.

Example:
<pre>
this.myStockControl.item_margin=5;
</pre>

'''changeItemsWeight( newWeights )'''

With this method you can change dynamically the weight of the item types in a stock control.

Items are immediately re-sorted with the new weight.

Example: with a stock control that contains classic cards, you can order them by value or by color. Using changeItemsWeight you can switch from one sort method to another when a player request this.

newWeights is an associative array: item type id => new weight.

Example:
<pre>
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );
</pre>

Example2:
<pre>
// Be careful with object initialisers with variables, use the bracket notation.
// Item type 1 gets a new weight of 10
var card_type = 1;
this.myStockControl.changeItemsWeight( { [card_type]: 10 } );
</pre>

'''centerItems'''

Center the stock items in the middle of the stock container.
e.g. this.myStock.centerItems = true;

'''setOverlap( horizontal_percent, vertical_percent )'''

This functions sents stock horizontal_overlap and vertical_overlap, the calls updateDisplay(). See what overlap means below

'''horizontal_overlap'''

Make items of the stock control "overlap" each other, to save space. By default, horizontal_overlap is 0 (but there is also '''item_margin''' which affects spacing''')'''.

When horizontal_overlap=20, it means that a stock item will overlap to only show 20% of the width of all the previous items. horizontal_overlap can't be greater than 100.

'''vertical_overlap'''

There is two modes, in one mode it used to adjust every 2nd item (See the games "Jaipur" or "Koryŏ"), second mode when setting use_vertical_overlap_as_offset=false is more/less normal overlap with vertical layout except its perentage of overlap (opposite of horizontal_overlap).

This is example of vertical stock with overlap
<pre>
stock.container_div.width = "60px"; // enought just for 1 card
stock.autowidth = false; // this is required so it obeys the width set above
stock.use_vertical_overlap_as_offset = false; // this is to use normal vertical_overlap
stock.vertical_overlap = 20; // overlap
stock.horizontal_overlap = -1; // current bug in stock - this is needed to enable z-index on overlapping items
stock.item_margin = 0; // has to be 0 if using overlap
stock.updateDisplay(); // re-layout
</pre>
[[File:StockV.png]] [[File:StockHV.png]] [[File:StockMixed.png]]

'''autowidth'''

Stock does not play well if you attempt to inline-block it with other blocks, to fix that you have to set this flag which will calculate width properly
mystock.autowidth = true;

'''resizeItems( width, height, background_width, background_height )'''

background_width is an optional argument.

background_height is an optional argument.

<pre> stock.resizeItems(100, 120, 150, 170);</pre>

=== Customize Appearance ===

'''extraClasses'''

Can be set to a list of class names (separated by space) on stock object, so when div is created these are added, i.e.

this.playerHand.extraClasses='mycard';

Note that it is the same list for all items.

'''onItemCreate'''

Using onItemCreate, you can trigger a method each time a new item is added to the Stock, in order to customize it.

Complete example:
<pre>
// During "setup" phase, we associate our method "setupNewCard" with the creation of a new stock item:
this.myStockItem.onItemCreate = dojo.hitch( this, 'setupNewCard' );

// And here is our "setupNewCard":
setupNewCard: function( card_div, card_type_id, card_id )
{
// Add a special tooltip on the card:
this.addTooltip( card_div.id, _("Some nice tooltip for this item"), '' );

// Note that "card_type_id" contains the type of the item, so you can do special actions depending on the item type

// Add some custom HTML content INSIDE the Stock item:
dojo.place( this.format_block( 'jstpl_my_card_content', {
....
} ), card_div.id );
}

</pre>

'''onItemDelete'''

Function handler called when div is removed

this.myStock.onItemDelete = (card_div, card_type_id, card_id) => { console.log("card deleted from myStock: "+card_id); };

'''jstpl_stock_item'''

Override default HTML template, this is the default:
<pre>
mystock.jstpl_stock_item ='<div id="${id}" class="stockitem ${extra_classes}" style="top:${top}px;left:${left}px;width:${width}px;height:${height}px;${position};background-image:url(\'${image}\');${additional_style}"></div>';

</pre>

Note: variable ${position} normally resolve to nothing or z-index: X - depending on overlap variables, and additional_style resolves to `background-size: ${this.backgroundSize}` if it is set

'''custom CSS images'''

If you want to use your own css styles for images on the items (i.e. not grid), you can do it as following, use customize template, then modify onItemCreate to add slyle which is based on type

<pre>
mystock.jstpl_stock_item = '<div id="${id}" class="stockitem card" style="top:${top}px;left:${left}px;${position};"></div>';
mystock.onItemCreate = (card_div, card_type_id, card_id ) => { dojo.addClass(card_div, 'card_type_'+card_type_id); }
for (var type = 0; type <= 48; type++) {
mystock.addItemType(type, type); // we skipped image and image position here
}
</pre>

Note: in this case your CSS must define all styles require for these stock items such as width, heigh, image and image positioning for every type

<pre>
.card {
width: 50px;
height: 80px;
background-image: url(img/cards.jpg);
background-size: 600% auto;
}
.card_type_1 {
background-postion: 20% 0%;
}
</pre>

== Tips when adding/removing items to/from Stock components ==

Most cases will be one of the following situations:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock:

* Use '''addToStockWithId''' with a "from" argument set to the element of your interface where the card should come from (i.e. div id). For example if you want to "reveal" card from player hand and it is not an interface element you can set from to be 'player_board_'+activePlayerId (where activePlayerId is player who played that card).

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:

* On the destination Stock, use '''addToStockWithId''' with a "from" argument which is the HTML id of the corresponding item in the source Stock. For example, if the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* Then, remove the source item with '''removeFromStockById'''. Note: do NOT set the 'to' argument in this call, otherwise you'll get two animations.

(Note that it's important to do things in this order, because the source item must still exist when you use it as the origin of the slide.)

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:

* Insert the card as a classic HTML template (dojo.place / this.format_block).
* Place it on the Stock item with '''this.placeOnObject''', using the Stock item HTML id (see above).
* Slide it to its new position with '''this.slideToObject'''.
* Remove the card from the Stock item with '''removeFromStockById'''.

Using the methods above, your cards should slide to, from, and between your Stock controls smoothly.

== Known issues ==

==== Incorrectly displayed sprites on Safari ====

As mentioned above, stock displays its images using "sprites" consisting of a portion of a larger image. To accomplish this, it uses the CSS background-position attribute in negative multiples of 100%. For example, the first element of the first row would be 0% 0%. The second element of the first row would be -100% 0%, etc.

This works fine except in Safari, which sometimes slightly modifies the width of elements at smaller screen sizes (usually when minimum width of 'game_interface_width' is not null) in game. For example, you might get a ~49.99px x ~49.99px div instead of the 50px x 50px specified by CSS width/height. Combined with using percentages in background-position, this can cause sprites to be slightly off-center.

Using pixels in background-position is probably the easiest way to fix this problem, but that would require modifying the stock code itself. As a developer, you can also work around the problem by specifying a background-size attribute based on the size in elements of your source image. For example, if you have a source image that contains 5 rows of 28 sprites, you should specify "background-size: 2800% 500%;"

You can add background-size to your stock items by using the extraClasses attribute as explained above and then specifying the values in your game.css file.

[[Category:Studio]]

Game art: img directory

2025-06-05T20:39:58Z

ShaPhi7: /* Image Manipulation Tools */

{{Studio_Framework_Navigation}}

__TOC__

== Metadata images ==

Game metadata images are images of game box, banner, title, etc. These images are no longer stored in project directory.

Metadata images are managed through the [[Game_metadata_manager|Game Metadata Manager]]. After you go there select the link to the game you want to upload images for.

== Game art ==

You must upload in img directory all images of your game interface.

=== Images naming constraints ===

To be correctly deployed your images file names should not contain spaces or parentheses.

=== Images loading ===

'''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 publish images that are not useful in your img, or it will slow down the game load.

Note that you can tune the way images are loaded with Javascript method "dontPreloadImage" (see [[Game_interface_logic:_yourgamename.js|Game Interface Logic]]).

General recommendation it to have no more than dozen of image files, 2Mb max each. However if there is heavy game resources specific to a player (i.e. player board of specific color or set of cards) it is better to separate them and "don't pre-load" since in any given game only some of them will be used.

=== Images format ===

You can use these image formats while building your game interface:
;jpg images

should be used for non-transparent images. Jpg are usually lighter than pngs, so please choose Jpg for big pictures (ex: game board, cards) when you don't need transparency to accelerate game load. You don't need transparency for rounded card corners, it can be done using css.

;png images

should be used for images with transparency, such as non-square tokens, meeples, etc (combined into sprite).

;gif images

can be used for animated images. This is not recommended to use gif animated images as they can upset players, but for some specific interface element this could be useful.

;svg images

svg images can be really efficient for icons or abstract images. Note: consider also using font awesome for icons instead of separate asset file.

=== Webp ===
png and jpg images are automatically converted to webp during deployment. Webp's are lighter weight.

When requesting a png/jpg file, many modern browsers will specify a preference for webp in their Accept header, and our CDN will comply with this request serving the converted webp image instead of the original png you uploaded. You can confirm which format your browser requests by checking request and response headers for the image in the network tab of your browser's developer tools.

In rare cases, this can cause a problem because the conversion is lossy.

If and only if this does cause a problem, then you can capitalise the first letter of your image's extension, <code>.Png</code> or <code>.Jpg</code>, and reference <code>image.Png</code> instead of <code>image.png</code> in the CSS. This will bypass the webp conversion and ensure you use the original image. This should not be done unless it is required.

=== Use background-size ===

In order to allow for players to use the browser zoom without your images becoming pixelated, it's recommended to use higher resolution images than needed for the normal display of your interface, and to use the css property '''background-size''' to fit the image to the size you need for your interface.

=== Use CSS Sprites ===

To limit the number of images load and make the game load faster, you must use CSS sprites, i.e. you must gather several images in a single one. However, there are limitations. Do not make any CSS image sprite with dimensions that exceed 4096x4096 pixels or it will not work on mobile devices (Android max texture size is 4096 pixels, test your own browser at [http://webglreport.com/ WebGL Report]).

To learn more on CSS Sprites:
* [http://www.w3schools.com/css/css_image_sprites.asp CSS sprites (W3C documentation)].
* [[Game interface stylesheet: yourgamename.css]]

'''Important:''' the maximum image size should be 4096x4096 (otherwise, some devices may not display parts of the image, see https://stackoverflow.com/questions/34682482/what-is-the-maximum-sprite-sheet-size-i-can-use-for-android-devices)

Tools:
* Sprite Generator https://www.toptal.com/developers/css/sprite-generator/
* Another Sprite Generator https://www.finalparsec.com/tools/sprite_sheet_maker

=== Shrink images ===

If you get high resolution images from publisher you need to shrink them since web display requires much lower resolution than printing.

* Shrink images size without visible loss of quality
** Offline tool for PNG: https://pngquant.org/
** Online tools for PNG/JPG: https://tinypng.com/ or http://www.iloveimg.com/ or https://squoosh.app/
** Online tool for SVG: https://jakearchibald.github.io/svgomg/

== Image Manipulation Tools ==

You have no choice but to use one of the image manipulating tools to create a successful game adaptation, you would have to
deal with
* Converting to supported formats
* Adding transparency
* Stitching
* Shrinking with no quality loss
* Resizing

For that you need a good tools, recommended tools (if you know more add them here)
* Gimp (all platforms) - general GUI image editor
* Paint.net (Windows) - general GUI image editor
* ImageMagic (All platforms) - https://www.imagemagick.org/script/download.php - command line image editor, great for mass manipulations and scripting

AI tools are very good at editing photos with minimal prompting too.
=== Examples ===

PDF to png convertion (linux)
gs -sDEVICE=pngalpha -o output.png -r600 -dDownScaleFactor=3 input.pdf

PDF to jpg using image magic and cropping page
montage -colorspace sRGB -density 300 -geometry 452x+0+0 -tile 5 -crop 82x87%+130+126 input.pdf output.jpg

PSD Extraction (image magic - CMYK to sRBG - one layer per file)
for i in *.psd; do convert $i -profile /usr/share/color/icc/colord/sRGB.icc `basename $i .psd`.png; done;

Tiling - The order of the images will match the 'ls' order. If needed change the filenames if you need a specific order.

montage -colorspace sRGB -density 300 *.png -tile 6 -background transparent ../tokens.png

PDF scrabber (linux) - extract all graphics file from pdf
pdfimages my.pdf prefix-

=== Online tools ===

PSD extraction (adobe file format)

https://www.photopea.com/

Seamless background (for tiled background wallpaper)

https://www.imgonline.com.ua/eng/make-seamless-texture.php

Download game assets from tabletop simulator

https://www.npmjs.com/package/ttsbackup

[[Category:Studio]]

Gamehelpekko

2025-02-12T00:41:00Z

ShaPhi7: bag implementation game end differs from the rules

===Overview===

Empty your hand the fastest, by playing cards higher than odds, lower than evens, and cards which are the reverse of what the active number is

===Turn===

On a turn, you must try to play a card on top of what came before

If the current card is odd (+), then you must play a higher card

If the current card is even (-), then you must play a lower card

If you cannot meet this requirement, then you have to draw a card

If you play a card in the 11s, 11, 22, 33, 44 and so on, you get another go straight away

If your last played card is the next card you see, i.e. no one else could play, you can play any card ignoring odd or even rules

You can interrupt out of turn by playing a mirror of what is displayed, this is the numbers in reverse e.g. 57 can be interrupted with 75, units and whole tens are mirrors of each other e.g. 02 vs 20

If you successfully play a mirror, either discard a card of your choice (not to the play area, out of the game) or cause everyone else to draw a card

If you play an invalid card, either normally or the wrong mirror, you take it back and draw a card as penalty

===Round End===

The round ends when a player empties their hand

Every other player scores 1 point for cards remaining in hand, and 2 points for a card of the 11s in hand

Then the cards are shuffled and a new round starts

===Game Ends===

Once a player meets or exceeds 25 points, the player with the lowest score wins!

Note: At this time, the BGA implementation only plays to 12 points.

Gamehelploveletter

2024-11-27T16:35:07Z

ShaPhi7: /* Game play */ Two player available

[[Category:Card games]]

== Theme ==
In the wake of the arrest of Queen Marianna for high treason, none was more heartbroken than her daughter, Princess Annette.
Suitors throughout the City-State of Tempest sought to ease Annette's sorrow by courting her to bring some joy into her life.

You are one of these suitors, trying to get your love letter to the princess.
Unfortunately, she has locked herself in the palace, so you must rely on intermediaries to carry your message.

During the game, you hold one secret card in your hand.
This is who currently carries your message of love for the princess.

Make sure that the person closest to the princess holds your love letter at the end of the day, so it reaches her first!

== Setup ==

* One of the 16 playing cards is removed at the beginning of each round and the others are shuffled.
* Every player is dealt one card.
* The remaining cards form a pile in the centre of the table.

== Game play ==

* Players take turns drawing one card (making two cards in hand) and discarding one card (returning to one card in hand).
* When a player discards a card, its effect is applied.

{|class="wikitable" border="2" style="text-align:left;width:auto;"
|+Card effects - 2-4 players
!Value
!№
!style="width:7rem;"|Name
!style="width:12rem;"|Simplified effect description
!Full effect description
|-
|style="text-align:center;"|8
|style="text-align:center;"|1
|'''Princess''' Annette
|Discard = out!
|If you discard the Princess — no matter how or why — she has tossed your letter into the fire. You are knocked out of the round.
|-
|style="text-align:center;"|7
|style="text-align:center;"|1
|'''Countess''' Wilhelmina
|Must discard with King or Prince in hand
|Unlike other cards which take effect when discarded, the text on the Countess applies while she is in your hand. In fact, she has no effect when you discard her. If you ever have the Countess and either the King or Prince in your hand, you must discard the Countess. You do not have to reveal the other card in your hand. Of course, you can also discard the Countess even if you do not have a royal family member in your hand. She likes to play mind games.
|-
|style="text-align:center;"|6
|style="text-align:center;"|1
|'''King''' Arnaud IV
|Swap hands
|When you discard King Arnaud IV, trade the card in your hand with the card held by another player of your choice. You cannot trade with a player who is out of the round, nor with someone protected by the Handmaid. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|5
|style="text-align:center;"|2
|'''Prince''' Arnaud
|A player must discard
|When you discard Prince Arnaud, choose one player still in the round (including yourself). That player discards their hand (do not apply its effect, unless it's Princess Annette) and draws a new card. If the deck is empty, that player draws the card that was removed at the start of the round. If all other players are protected by the Handmaid, you must choose yourself.
|-
|style="text-align:center;"|4
|style="text-align:center;"|2
|'''Handmaid''' Susannah
|May not be targeted
|When you discard the Handmaid, you are immune to the effects of other players’ cards until the start of your next turn.
|-
|style="text-align:center;"|3
|style="text-align:center;"|2
|'''Baron''' Talus
|Compare -> lower = out
|When discarded, choose one other player still in the round. You and that player secretly compare your hands. The player with the lower rank is knocked out of the round. In case of a tie, nothing happens. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|2
|style="text-align:center;"|2
|'''Priest''' Tomas
|Look at one
|When you discard the Priest, you can look at one other player’s hand. DO NOT reveal the hand to all players.
|-
|style="text-align:center;"|1
|style="text-align:center;"|5
|'''Guard''' Odette
|Guess value -> out
|When you discard the Guard, choose a player and name a card value (other than 1). If that player has a card with that value, that player is knocked out of the round. If all other players still in the round are protected by the Handmaid, this card does nothing. If your opponent holds an Assassin, you're out (even if you guess correctly!)
|}

{|class="wikitable" border="2" style="text-align:left;width:auto;"
|+Card effects for '''''additional''''' cards - 5-8 players
!Value
!№
!style="width:7rem;"|Name
!style="width:12rem;"|Simplified effect description
!Full effect description
|-
|style="text-align:center;"|9
|style="text-align:center;"|1
|'''Bishop''' Vinizio
|Guess value -> +1★
|Similar to a Guard, name a number other than 1 and choose another player. If they have that number card in their hand, gain 1 ★. If the guess is correct, the targeted player can choose whether to keep or discard the card. Despite his impressive 9, the Bishop always loses to the Princess at the end of the round.
|-
|style="text-align:center;"|7
|style="text-align:center;"|1
|'''Dowager Queen''' Tummia
|Compare -> '''higher''' = out
|Acts as a Baron, but the highest card is eliminated instead of the lowest.
|-
|style="text-align:center;"|6
|style="text-align:center;"|1
|'''Constable''' Viktor
|Out -> +1★
|If this card is in your discard pile then this gives you 1 ★ if you are knocked out of the round.
|-
|style="text-align:center;"|5
|style="text-align:center;"|2
|'''Count''' Guntram
| +1 value @round end
|Add +1 to your card value at the end of the round.
|-
|style="text-align:center;"|4
|style="text-align:center;"|2
|'''Sycophant''' Morris
|Choose target
|Lets you decide who will be the target of the next card played.
|-
|style="text-align:center;"|3
|style="text-align:center;"|2
|'''Baroness''' Fiona
|Look at two
|Allows you to see TWO hands.
|-
|style="text-align:center;"|2
|style="text-align:center;"|2
|'''Cardinal''' Vesper
|Swap two hands + look at one
|Exchanges the hands of 2 players. You may see one of the hands.
|-
|style="text-align:center;"|1
|style="text-align:center;"|'''+3'''
|'''Guard''' Odette
|Guess value -> out
|When you discard the Guard, choose a player and name a card value (other than 1). If that player has a card with that value, that player is knocked out of the round. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|0
|style="text-align:center;"|1
|'''Jester''' Darius
|Guess winner -> +1★
|Allows you to guess who will win the round and score 1 ★ if this is the case.
|-
|style="text-align:center;"|0
|style="text-align:center;"|1
|'''Assassin'''
|Guard = out
|Kills your opponent if they use a guard against you.
|}

=== Round End ===

# No cards in the deck or
# One player remains.
* The player holding the Princess or card with the highest value earns 1 ★ token.

==== Tiebreak ====

* Sum of the value of each player's discarded cards.
* If a tie remains, nobody gets a ★ token.

== Game end ==

{|class="wikitable" style="text-align:center;width:auto;"
|+Winning № of ★s
!№ Players
!№ ★ tokens
|-
|2
|7
|-
|3
|5
|-
|4
|4
|-
|5-8
|4
|}

BGA Code Sharing

2024-11-15T14:16:23Z

ShaPhi7:

{{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 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
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
|Now Boarding
|https://github.com/quietmint/bga-nowboarding
|quietmint
|-
| 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]]

Gamehelploveletter

2024-11-13T17:57:39Z

ShaPhi7: Clarify Guard-Assassin rule.

[[Category:Card games]]

== Theme ==
In the wake of the arrest of Queen Marianna for high treason, none was more heartbroken than her daughter, Princess Annette.
Suitors throughout the City-State of Tempest sought to ease Annette's sorrow by courting her to bring some joy into her life.

You are one of these suitors, trying to get your love letter to the princess.
Unfortunately, she has locked herself in the palace, so you must rely on intermediaries to carry your message.

During the game, you hold one secret card in your hand.
This is who currently carries your message of love for the princess.

Make sure that the person closest to the princess holds your love letter at the end of the day, so it reaches her first!

== Setup ==

* One of the 16 playing cards is removed at the beginning of each round and the others are shuffled.
* Every player is dealt one card.
* The remaining cards form a pile in the centre of the table.

== Game play ==

* Players take turns drawing one card (making two cards in hand) and discarding one card (returning to one card in hand).
* When a player discards a card, its effect is applied.

{|class="wikitable" border="2" style="text-align:left;width:auto;"
|+Card effects - 3-4 players
!Value
!№
!style="width:7rem;"|Name
!style="width:12rem;"|Simplified effect description
!Full effect description
|-
|style="text-align:center;"|8
|style="text-align:center;"|1
|'''Princess''' Annette
|Discard = out!
|If you discard the Princess — no matter how or why — she has tossed your letter into the fire. You are knocked out of the round.
|-
|style="text-align:center;"|7
|style="text-align:center;"|1
|'''Countess''' Wilhelmina
|Must discard with King or Prince in hand
|Unlike other cards which take effect when discarded, the text on the Countess applies while she is in your hand. In fact, she has no effect when you discard her. If you ever have the Countess and either the King or Prince in your hand, you must discard the Countess. You do not have to reveal the other card in your hand. Of course, you can also discard the Countess even if you do not have a royal family member in your hand. She likes to play mind games.
|-
|style="text-align:center;"|6
|style="text-align:center;"|1
|'''King''' Arnaud IV
|Swap hands
|When you discard King Arnaud IV, trade the card in your hand with the card held by another player of your choice. You cannot trade with a player who is out of the round, nor with someone protected by the Handmaid. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|5
|style="text-align:center;"|2
|'''Prince''' Arnaud
|A player must discard
|When you discard Prince Arnaud, choose one player still in the round (including yourself). That player discards their hand (do not apply its effect, unless it's Princess Annette) and draws a new card. If the deck is empty, that player draws the card that was removed at the start of the round. If all other players are protected by the Handmaid, you must choose yourself.
|-
|style="text-align:center;"|4
|style="text-align:center;"|2
|'''Handmaid''' Susannah
|May not be targeted
|When you discard the Handmaid, you are immune to the effects of other players’ cards until the start of your next turn.
|-
|style="text-align:center;"|3
|style="text-align:center;"|2
|'''Baron''' Talus
|Compare -> lower = out
|When discarded, choose one other player still in the round. You and that player secretly compare your hands. The player with the lower rank is knocked out of the round. In case of a tie, nothing happens. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|2
|style="text-align:center;"|2
|'''Priest''' Tomas
|Look at one
|When you discard the Priest, you can look at one other player’s hand. DO NOT reveal the hand to all players.
|-
|style="text-align:center;"|1
|style="text-align:center;"|5
|'''Guard''' Odette
|Guess value -> out
|When you discard the Guard, choose a player and name a card value (other than 1). If that player has a card with that value, that player is knocked out of the round. If all other players still in the round are protected by the Handmaid, this card does nothing. If your opponent holds an Assassin, you're out (even if you guess correctly!)
|}

{|class="wikitable" border="2" style="text-align:left;width:auto;"
|+Card effects for '''''additional''''' cards - 5-8 players
!Value
!№
!style="width:7rem;"|Name
!style="width:12rem;"|Simplified effect description
!Full effect description
|-
|style="text-align:center;"|9
|style="text-align:center;"|1
|'''Bishop''' Vinizio
|Guess value -> +1★
|Similar to a Guard, name a number other than 1 and choose another player. If they have that number card in their hand, gain 1 ★. If the guess is correct, the targeted player can choose whether to keep or discard the card. Despite his impressive 9, the Bishop always loses to the Princess at the end of the round.
|-
|style="text-align:center;"|7
|style="text-align:center;"|1
|'''Dowager Queen''' Tummia
|Compare -> '''higher''' = out
|Acts as a Baron, but the highest card is eliminated instead of the lowest.
|-
|style="text-align:center;"|6
|style="text-align:center;"|1
|'''Constable''' Viktor
|Out -> +1★
|If this card is in your discard pile then this gives you 1 ★ if you are knocked out of the round.
|-
|style="text-align:center;"|5
|style="text-align:center;"|2
|'''Count''' Guntram
| +1 value @round end
|Add +1 to your card value at the end of the round.
|-
|style="text-align:center;"|4
|style="text-align:center;"|2
|'''Sycophant''' Morris
|Choose target
|Lets you decide who will be the target of the next card played.
|-
|style="text-align:center;"|3
|style="text-align:center;"|2
|'''Baroness''' Fiona
|Look at two
|Allows you to see TWO hands.
|-
|style="text-align:center;"|2
|style="text-align:center;"|2
|'''Cardinal''' Vesper
|Swap two hands + look at one
|Exchanges the hands of 2 players. You may see one of the hands.
|-
|style="text-align:center;"|1
|style="text-align:center;"|'''+3'''
|'''Guard''' Odette
|Guess value -> out
|When you discard the Guard, choose a player and name a card value (other than 1). If that player has a card with that value, that player is knocked out of the round. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|0
|style="text-align:center;"|1
|'''Jester''' Darius
|Guess winner -> +1★
|Allows you to guess who will win the round and score 1 ★ if this is the case.
|-
|style="text-align:center;"|0
|style="text-align:center;"|1
|'''Assassin'''
|Guard = out
|Kills your opponent if they use a guard against you.
|}

=== Round End ===

# No cards in the deck or
# One player remains.
* The player holding the Princess or card with the highest value earns 1 ★ token.

==== Tiebreak ====

* Sum of the value of each player's discarded cards.
* If a tie remains, nobody gets a ★ token.

== Game end ==

{|class="wikitable" style="text-align:center;width:auto;"
|+Winning № of ★s
!№ Players
!№ ★ tokens
|-
|2'''*'''
|7
|-
|3
|5
|-
|4
|4
|-
|5-8
|4
|}'''*'''''Currently unavailable on BGA''

Gamehelploveletter

2024-11-13T17:52:44Z

ShaPhi7: Clarified Bishop rule.

[[Category:Card games]]

== Theme ==
In the wake of the arrest of Queen Marianna for high treason, none was more heartbroken than her daughter, Princess Annette.
Suitors throughout the City-State of Tempest sought to ease Annette's sorrow by courting her to bring some joy into her life.

You are one of these suitors, trying to get your love letter to the princess.
Unfortunately, she has locked herself in the palace, so you must rely on intermediaries to carry your message.

During the game, you hold one secret card in your hand.
This is who currently carries your message of love for the princess.

Make sure that the person closest to the princess holds your love letter at the end of the day, so it reaches her first!

== Setup ==

* One of the 16 playing cards is removed at the beginning of each round and the others are shuffled.
* Every player is dealt one card.
* The remaining cards form a pile in the centre of the table.

== Game play ==

* Players take turns drawing one card (making two cards in hand) and discarding one card (returning to one card in hand).
* When a player discards a card, its effect is applied.

{|class="wikitable" border="2" style="text-align:left;width:auto;"
|+Card effects - 3-4 players
!Value
!№
!style="width:7rem;"|Name
!style="width:12rem;"|Simplified effect description
!Full effect description
|-
|style="text-align:center;"|8
|style="text-align:center;"|1
|'''Princess''' Annette
|Discard = out!
|If you discard the Princess — no matter how or why — she has tossed your letter into the fire. You are knocked out of the round.
|-
|style="text-align:center;"|7
|style="text-align:center;"|1
|'''Countess''' Wilhelmina
|Must discard with King or Prince in hand
|Unlike other cards which take effect when discarded, the text on the Countess applies while she is in your hand. In fact, she has no effect when you discard her. If you ever have the Countess and either the King or Prince in your hand, you must discard the Countess. You do not have to reveal the other card in your hand. Of course, you can also discard the Countess even if you do not have a royal family member in your hand. She likes to play mind games.
|-
|style="text-align:center;"|6
|style="text-align:center;"|1
|'''King''' Arnaud IV
|Swap hands
|When you discard King Arnaud IV, trade the card in your hand with the card held by another player of your choice. You cannot trade with a player who is out of the round, nor with someone protected by the Handmaid. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|5
|style="text-align:center;"|2
|'''Prince''' Arnaud
|A player must discard
|When you discard Prince Arnaud, choose one player still in the round (including yourself). That player discards their hand (do not apply its effect, unless it's Princess Annette) and draws a new card. If the deck is empty, that player draws the card that was removed at the start of the round. If all other players are protected by the Handmaid, you must choose yourself.
|-
|style="text-align:center;"|4
|style="text-align:center;"|2
|'''Handmaid''' Susannah
|May not be targeted
|When you discard the Handmaid, you are immune to the effects of other players’ cards until the start of your next turn.
|-
|style="text-align:center;"|3
|style="text-align:center;"|2
|'''Baron''' Talus
|Compare -> lower = out
|When discarded, choose one other player still in the round. You and that player secretly compare your hands. The player with the lower rank is knocked out of the round. In case of a tie, nothing happens. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|2
|style="text-align:center;"|2
|'''Priest''' Tomas
|Look at one
|When you discard the Priest, you can look at one other player’s hand. DO NOT reveal the hand to all players.
|-
|style="text-align:center;"|1
|style="text-align:center;"|5
|'''Guard''' Odette
|Guess value -> out
|When you discard the Guard, choose a player and name a card value (other than 1). If that player has a card with that value, that player is knocked out of the round. If all other players still in the round are protected by the Handmaid, this card does nothing.
|}

{|class="wikitable" border="2" style="text-align:left;width:auto;"
|+Card effects for '''''additional''''' cards - 5-8 players
!Value
!№
!style="width:7rem;"|Name
!style="width:12rem;"|Simplified effect description
!Full effect description
|-
|style="text-align:center;"|9
|style="text-align:center;"|1
|'''Bishop''' Vinizio
|Guess value -> +1★
|Similar to a Guard, name a number other than 1 and choose another player. If they have that number card in their hand, gain 1 ★. If the guess is correct, the targeted player can choose whether to keep or discard the card. Despite his impressive 9, the Bishop always loses to the Princess at the end of the round.
|-
|style="text-align:center;"|7
|style="text-align:center;"|1
|'''Dowager Queen''' Tummia
|Compare -> '''higher''' = out
|Acts as a Baron, but the highest card is eliminated instead of the lowest.
|-
|style="text-align:center;"|6
|style="text-align:center;"|1
|'''Constable''' Viktor
|Out -> +1★
|If this card is in your discard pile then this gives you 1 ★ if you are knocked out of the round.
|-
|style="text-align:center;"|5
|style="text-align:center;"|2
|'''Count''' Guntram
| +1 value @round end
|Add +1 to your card value at the end of the round.
|-
|style="text-align:center;"|4
|style="text-align:center;"|2
|'''Sycophant''' Morris
|Choose target
|Lets you decide who will be the target of the next card played.
|-
|style="text-align:center;"|3
|style="text-align:center;"|2
|'''Baroness''' Fiona
|Look at two
|Allows you to see TWO hands.
|-
|style="text-align:center;"|2
|style="text-align:center;"|2
|'''Cardinal''' Vesper
|Swap two hands + look at one
|Exchanges the hands of 2 players. You may see one of the hands.
|-
|style="text-align:center;"|1
|style="text-align:center;"|'''+3'''
|'''Guard''' Odette
|Guess value -> out
|When you discard the Guard, choose a player and name a card value (other than 1). If that player has a card with that value, that player is knocked out of the round. If all other players still in the round are protected by the Handmaid, this card does nothing.
|-
|style="text-align:center;"|0
|style="text-align:center;"|1
|'''Jester''' Darius
|Guess winner -> +1★
|Allows you to guess who will win the round and score 1 ★ if this is the case.
|-
|style="text-align:center;"|0
|style="text-align:center;"|1
|'''Assassin'''
|Guard = out
|Kills your opponent if they use a guard against you.
|}

=== Round End ===

# No cards in the deck or
# One player remains.
* The player holding the Princess or card with the highest value earns 1 ★ token.

==== Tiebreak ====

* Sum of the value of each player's discarded cards.
* If a tie remains, nobody gets a ★ token.

== Game end ==

{|class="wikitable" style="text-align:center;width:auto;"
|+Winning № of ★s
!№ Players
!№ ★ tokens
|-
|2'''*'''
|7
|-
|3
|5
|-
|4
|4
|-
|5-8
|4
|}'''*'''''Currently unavailable on BGA''

Gamehelplinkage

2021-08-11T20:49:57Z

ShaPhi7: Created page with "== In 100 words == This game is played on a 7x7 board with the center square removed. There are 24 pieces, 6 of 4 different colors. Each piece is a domino covering exactly tw..."

== In 100 words ==

This game is played on a 7x7 board with the center square removed. There are 24 pieces, 6 of 4 different colors. Each piece is a domino covering exactly two cells of the board. Both players choose pieces from a shared pool.

There are two players in the game: the starting player is called 'More' and the other player is called 'Fewer'.

The goals of the game are opposite for both players. The 'Fewer' player wins a finished game if the number of distinct groups of cells of the same color is less than 12. Otherwise the 'More' player wins.

== Introduction ==

Linkage is played on a 7x7 square grid with dominoshaped pieces that cover two squares each.
The two players have different goals: one player, called
"Fewer" needs to keep the number of color groups low,
while the other player, called "More", needs to make the
number of color groups high.

== Components ==

A Linkage set includes:
- A board with a 7x7 square grid
- 24 playing pieces, 6 of each color (white, blue,
red, and yellow).
- 1 black counter and 1 green counter

== Game Rules ==

The game begins with the board empty, except for the
black counter, which is placed on the center square:
Players choose who will be More and who will be
Fewer.
The More player always goes first. Each turn consists of
choosing one of the remaining pieces and placing it on
the board, then placing the green counter on top of that
piece. Note that neither player owns any of the pieces;
they may choose any color to place on each turn.
When placing a piece, it may be placed anywhere it fits
without overlapping other pieces or the black counter.
There is, however, one restriction: the piece may not be
placed so that it touches the previously-placed piece
which is marked by the green counter.
If a player does not have a legal move because of the
location of the green counter, he removes it from the
board and passes that turn.
Play continues until there are no more available moves.

== End of Game ==

Once no more moves can be made, the number of color
groups on the board is counted. A color group is any set
of one or more pieces of the same color that are
connected vertically or horizontally. See the diagram for
an example. If there are 12 or more color groups, More
wins the game. If there are 11 or less, the Fewer player
wins.

== Optional Rule ==

At the time this is being printed, Linkage strategy has
developed somewhat and shows a slight advantage for
the More player. So the following rule can be played
both to mitigate this advantage, and to add some variety
to the starting configuration.
When beginning the game, one player starts by placing
the black counter anywhere on the board. Then the
other player chooses whether to play More or Fewer.
Play then continues normally, with whoever is More
going first as usual.