Board Game Arena - User contributions [en]

Main game logic: Game.php

2026-10-07T01:06:43Z

Victoria La: /* File Structure */

{{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, do not change code from template, only add to it. It accepts a magic parameter <code>int $currentPlayerId</code> (or <code>int $currentPlayerNo</code>) to fetch the information from the point of view of the current player id (or no). It should not have any other parameter.
* '''getGameProgression''': where you compute the game progression indicator. Returns a number indicating percent of progression (0-100). Used to calculate ELO changes of remaining players when a player quits, or as a conceding requirement (in non-tournament 2 player games, a player may concede if the progression is at least 50%).
* Utility functions: your utility functions.
* '''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
* '''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 don't see this its ok, it is no longer needed in new framework
The following section are no longer part of Game template but part of state class, but they can still be there as fallback
* 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]).
* '''zombieTurn''': what to do it's the turn of a zombie player.

== Accessing player information ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing the database ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

Result:
[
'myuser0',
'myuser1'
]

</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Game options (old globals) ==

See also: [[Options and preferences: gameoptions.json, gamepreferences.json]]

Game options are stored in the "global" database table.

; <nowiki>$this->bga->tableOptions->get(int $optionId): ?int</nowiki>
: Returns the value of a game option (using the key in gameoptions.jsonc file, a number from 100 - 199). The value may be null if the option doesn't exist for this table.

=== BGA predefined globals ===

BGA stores some internal data in the same "global" database table. Use the following to access this:

; <nowiki>$this->bga->tableOptions->getGameVersion(): int</nowiki>
: Returns the current game version. ''(based on global_id = 300)''

; <nowiki>$this->bga->tableOptions->isTurnBased(): bool</nowiki>
: Returns true if the game is turn based. ''(based on global_id = 200)''

; <nowiki>$this->bga->tableOptions->isRealTime(): bool</nowiki>
: Returns true if the game is real time. ''(based on global_id = 200)''

; <nowiki>$this->bga->logs->getCurrentMoveId(): int</nowiki>
: Returns the current move ID. ''(based on global_id = 3)''

; <nowiki>$this->getGameLanguage(): string</nowiki>
: Returns the index of the selected language as defined in gameinfos.jsonc, as a string like "1", "2", etc. ''(based on global_id = 207)''

Other BGA predefined globals exist, but you should not read/write these anywhere in your game code. However, 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
''Access with '''$this->bga->logs->getCurrentMoveId()'''''
|-
| 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:
''Access with '''$this->bga->tableOptions->isRealTime()'''''
* 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:
''Access with '''$this->bga->tableOptions->isTurnBased()'''''
* 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
''Access with '''$this->getGameLanguage()'''''
|-
| 300 || game_db_version ||GAMESTATE_GAMEVERSION: Current version of the game (when in production)
''Access with '''$this->bga->tableOptions->getGameVersion()'''''
|-
| 301 || game_result_neutralized ||GAMESTATE_GAME_RESULT_NEUTRALIZED
|-
| 302 || neutralized_player_id ||GAMESTATE_NEUTRALIZED_PLAYER_ID
|-
| 304 || undo_moves_stored ||GAMESTATE_UNDO_MOVES_STORED
|-
| 305 || undo_moves_player ||GAMESTATE_UNDO_MOVES_PLAYER
|-
| 306 || lock_screen_timestamp ||GAMESTATE_LOCK_TIMESTAMP
|}

== Game states and active players ==

=== Activate player handling ===

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

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

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

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

=== Multiple activate player handling ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Private parallel states ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Inactive Players ====

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

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

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

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

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

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

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

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

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

=== Possible attributes ===

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

...

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

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

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

...

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

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

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

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

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

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

...

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

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

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

...

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

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

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

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

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

...

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

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

On client side:

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

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

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

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

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

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

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

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

</pre>

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

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

== Players turn order ==

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

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

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

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

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

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

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

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

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

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

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

== Notifications ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

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

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

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

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

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

=== Notify ===

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

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

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

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

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

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

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

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

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

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

Complete notify all example (from "Reversi"):

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

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

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

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

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

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

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

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

==== Recursive Notifications ====

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

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

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

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

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

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

(...)

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

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

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

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

==== Using player names ====

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

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

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

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

=== NotifyPlayer ===

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

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

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

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

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

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

=== Notification decorators ===

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

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

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

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

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

=== Use player no in notifications ===

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

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

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

== Randomization ==

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

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

=== Dice and bga_rand ===

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

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

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

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

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

=== Arrays ===

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

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

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

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

=== shuffle and cards shuffling ===

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

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

=== Other methods ===

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

== Game statistics ==

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

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

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

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

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

Create a statistic entry with a default value.

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

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

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

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

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

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

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

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

Set a statistic $name to $value.

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

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

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

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

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

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

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

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

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

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

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

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

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

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

Examples:
<pre>

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

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

</pre>

=== Tie breaker ===

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

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

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

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

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

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

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

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

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

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

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

...

public function onEnteringState() {
...

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

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

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

=== Result neutralization ===

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

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

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

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

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

=== Co-operative game ===

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

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

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

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

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

...

public function onEnteringState() {
...

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

=== Semi-coop ===

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

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

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

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

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

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

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

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

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

=== Solo ===

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

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

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

...

public function onEnteringState() {
...

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

=== Player elimination ===

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

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

Usage:

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

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

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

=== Player concede ===

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

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

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

== Reflexion time ==

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

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

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

== Undo moves ==

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

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

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

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

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

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

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

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

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

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

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

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

== Managing errors and exceptions ==

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

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

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

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

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

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

== Zombie mode ==

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

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

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

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

== Player color preferences ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Legacy games API ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

If you met the following situation:

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

Then, you must use the following method:

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

player_id = player who write the text

text = text that has been written

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

== Tournament API (🚧 Beta) ==

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

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

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

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

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

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

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

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

== Language dependent games API ==

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

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

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

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

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

== Debugging and Tracing ==

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

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

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

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

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

== Creating other classes ==

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

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

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

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

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

[[Category:Studio]]

Contact BGA Studio

2026-09-02T00:16:59Z

Victoria La: /* Help with Game development or setup */

== Purpose ==
This page is to find solutions for technical issues or manual steps related to games development on BGA Studio.

To contact BGA team if you are a player or a publisher (i.e. not a game software developer) please use this form https://en.boardgamearena.com/faq?anchor=faq_team_contact

If you are a publisher and you could not reach BGA via the channel above you can go Developer discord server and ask for developers on #looking-for-developers channel (invite link at the bottom).

== Studio Accounts Management ==

BGA player account is not the same as studio account (even if you name them the same).

* Create studio account https://studio.boardgamearena.com (if you already logged in logout first)
* Resend welcome email (original) https://studio.boardgamearena.com/account?page=welcomeemail
** Same if you forgot database or ftp account
** Still cannot get email, tried searching in junk for BGA, contact studio via https://studio.boardgamearena.com/support
* Forgot password https://studio.boardgamearena.com/account?page=lostpassword
* Cannot ftp
** See section "Help with Game development or setup"
* Upload ssh key https://studio.boardgamearena.com/controlpanel

== Studio Games Management ==

* Game management control panel located in Gear link if you click on your Account circle, direct link https://studio.boardgamearena.com/controlpanel
** This allows to create projects, delete projects and manage projects
* Access to other project's source code
** Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/projects page (almost any project).
** If project is not there - its either does not have bgg id, already published (in this case check radio button on this page) or was not developed on studio (some old games).
** You can also try to use direct link https://studio.boardgamearena.com/gamepanel?game=template (replace template with game name in the link)
** If you prefer github see https://en.doc.boardgamearena.com/BGA_Code_Sharing
* Access to frontend
** Even if you cannot get source access via studio, you can see the java code, css and images asset by using Browser dev tools, see [[Practical_debugging]]
* Push game to Alpha or Beta
** You cannot do it yourself, you have to go though checklist first https://en.doc.boardgamearena.com/Pre-release_checklist then use Request Alpha or Request Beta button in control panel
* Your project seems to be deleted after you came back a year after - create a new project with SAME name as before (you have to remember name) - it will be restored
* You have permission issues syncing files, but you are admin - re-add yourself as admin via control panel. DO NOT delete yourself, select Admin (!Important, double check you selected Admin not Read/Write) type your name (same account name as before) and click add.
* You managed to delete yourself from your own project, or are not admin anymore - require admin interferance - contact studio via https://studio.boardgamearena.com/support
* You want to take over abandoned game
** Please first ask the dev (in PM, dev forum or discord) - it may not be actually abandoned
** Contact the Studio support to ask for access to this project via https://studio.boardgamearena.com/support
* You have error creating new game: Not authorized adminstudionewproject
** Wait a little longer and try again

== Help with Game development or setup ==

If you stuck or looking for help in regards to development (even if you think there is bug in framework) please contact fellow developers first before attempting to contact any of admins

* Google it, you may find an answer unrelated to BGA
* Post question on DISCORD chat server for BGA developers (invite link https://discord.gg/YxEUacY). Game authors and publishers can also go there to ask about digital adaptations. Do not go there if you are a non-developer BGA player, but feel free to check out unofficial BGA user servers (at your own risk)
* Search and/or post on [http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]
* If you think there is bug in studio or APIs check these bugs [https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]. You can also submit a bug there

Also some specific reading may help
* Studio development setup including sftp issues - [[Tools and tips of BGA Studio]]
* Debugging - [[Practical debugging]]
* Completely Stuck - [[Troubleshooting]]
* Anything else - [[Studio]]

== Help with Game assets or licenses ==

* https://studio.boardgamearena.com/licensing
* Graphics help https://en.doc.boardgamearena.com/Game_art:_img_directory
* Request game assets (graphics) - https://studio.boardgamearena.com/support

== Last resort ==

You can file a request that will land in the BGA ticketing system from the [https://studio.boardgamearena.com/support studio support page].

Pretty please use text above to solve your problems before filing a support request.

[[Category:Studio]]

Pre-release checklist

2026-08-01T15:07:28Z

Victoria La: add note about committing first when use minificationand other typos

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first

=== Move from Dev to Alpha ===
# ''' License '''
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.
# ''' Metadata and game assets '''
## [[Game_meta-information: gameinfos.jsonc]] has correct and up to date information about the game.
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
## You have added the requested images in the Game Metadata Manager to make the game page pretty
## There are no images in the img directory that are not needed anymore
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
## Each image should not exceed 4Mb
## Total size should not exceed 15Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 15Mb (i.e. expansions), you have to make a note of that when requesting move to alpha
## If you use extra fonts, they should be freeware (please include a .txt with the license information in addition to the font files). Fonts should be placed to "fonts" directory
## Sounds should be placed to "sounds" directory
# ''' Server side '''
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function
## Game progression is implemented (getGameProgression() in php)
## Zombie turn is implemented (zombieTurn() in php). For more details about how the Zombie code should work and be tested, see [[Zombie Mode|Zombie mode]].
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expansions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)
# ''' Client side '''
## Check that you use ajaxcall/bgaPerformAction only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automatically (i.e. during replay)''
# ''' User Interface '''
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
## If your game elements become blurry or pixelated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
## Non-self explanatory graphic elements should have tooltips
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
## Test if the game is readable in dark mode. See [[Game interface stylesheet: yourgamename.css#Support of the Dark mode]] for more details
# ''' Special testing '''
## Click "Use minified JS" and "Use minified CSS" buttons on the game management page, then test your game (you have to commit in studio first). This will prevent you from having a panic attack when the game releases in alpha and it is stuck in "Connecting to game".
## Game is tested with spectator (non player observer): click the red arrow next to Test spectator, under player panels. As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
## Game is tested with in-game replay from last move feature (by clicking on notification log items).
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
# ''' Cleanup '''
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)
## Remove all unnecessary debug logging from your php code
## Copyright headers in all source files have your name
## Remove unnecessary files from main folder (can move some to misc folder)
## If using TypeScript and Scss - move them to "src" folder from "modules", if not there already (modules deployed to prod, only transposed files are needed)
# ''' Static Analysis '''
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Dry run build"
## There is also "Check project" button (it will open like a game table, and you can type your project and click on Start button to run analysis) - but it may be obsolete

=== Finally move to Alpha status ===
# We want the correct formal name of the game to be used for the project (i.e. '''agricola''', not '''myagricolaproject'''). If you DO NOT have the correct formal name of the game for your project, then
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it. In this case, after you request the alpha deployment, please reply to the automatic reply with the correct name.
## If you DO have the correct formal name of the game for your project, or completed the above steps, create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
# Are you really ready?
## Click on the '''Request ALPHA status''' button available above your just built version. You cannot deploy yourself from the "manage game" page until this first ALPHA deploy has been done by the admins. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed. Note: you can also ask for moving your project to "private Alpha" - in this case you will invite people manually rather than having your game immediately visible to the whole BGA reviewers community. When you press you button you should receive acknowledgement email, reply to this email with more details.
# Reply to alpha request e-mail with following information
## Is this final project name or need renaming (this is actually part of submission form now)
## What is your production BGA user name (because they have to link it to be game admin in prod)
## If private alpha requested - BGA user names of other admins - usually publisher/designer
## If you have license or/and alpha approval, include approval email (form publisher)
## If you have exceptions for items from this checklist (i.e. size of assets, custom fonts, etc) add explanations
# Wait
## When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps. If you waiting for 2 weeks+ you can ping them again.

=== Move from Alpha to Beta ===
# The implementation '''must be approved by the publisher''' (if not a public domain game)
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals
# Click on the '''Request BETA status''' button available above your latest build. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed.

[[Category:Studio]]

BGA Studio Migration Guide

2026-07-22T12:58:57Z

Victoria La: /* Dojo usage */

This page is only for people who started long time ago and now need to re-write older projects into more modern versions.
Also if you trying to fix older game you may have to look here.

==Overview==
See announcement here https://studio.boardgamearena.com/forum/viewtopic.php?f=12&t=45248

📌 This symbol: direct information about migration
== Structural changes==

'''''gameoptions.inc.php''''' => gameoptions.json, gamepreferences.json

Previously, options and preferences were specified in a single gameoptions.inc.php file.

Now options and preferences are 2 json files, follow Migration steps on this page https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Migration

See [[#User preferences]] and [[#Game options]] for API changes.

When building the game with this file you will see deprecation warning: The file gameoptions.inc.php is deprecated. click "Reload game options configuration" to generate the JSON content you can then put on a gameoptions.json and gamepreferences.json file. Then you can safely delete the gameoptions.inc.php file.

'''''<gamename>.game.php''''' => modules/php/Game.php

Move and refactor, see section [[BGA Studio Migration Guide#Namespaced game class|Namespaced game class]]

'''<gamename>.action.php => remove'''

See section [[BGA Studio Migration Guide#Autowire game actions|Autowire game actions]]

'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' => remove

See section [[BGA Studio Migration Guide#Removal of view and template|Removal of view and template]]

'''gameinfos.inc.php'''

File still there. Deprecated keys '''designer''', '''artist''', '''year''', '''presentation''', '''tags''', '''complexity''', '''strategy''', '''luck''', '''diplomacy''', '''is_beta''' are no longer in use. Please remove these keys and use the Game Metadata Manager instead.

The file has a new optional flag <code>'exception_on_warning' => true</code> that should be added to better detect warnings, that are usually source of undetected bugs.

'''''material.inc.php''''' => optional

See section [[#Material]]

'''''states.inc.php''''' => modules/php/States

See section [[#States]]

'''stats.inc.php''' => stats.json

Deprecation warning: The file stats.inc.php is deprecated. click "Reload statistics configuration" to generate the JSON content you can then put on a stats.json file. Then you can safely delete the stats.inc.php file.

'''<gamename>.js'''

Equivalent file is in modules/js/Game.js, it is ES6 js class (yay) and no dojo mess.
There are also massive API changes, see bottom sections

==IDE Support==
A new _ide_helper.php file is now provided in every project dir, allowing IDE to provide syntax error highlighting for the framework functions. This file is regularly updated to match the latest framework updates.

Same with bga-framework.d.ts for those using TypeScript.

📌 Sync the files from the FTP dir to your local copy to benefit from it. Most of the IDE like Visual Studio Code should handle _ide_helper.php if you already followed https://en.doc.boardgamearena.com/Setting_up_BGA_Development_environment_using_VSCode

==Game configuration ==

===User preferences===

Access to user preferences and listener: https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#User_preferences

📌
*If you had a custom function called <code>setupPreferences()</code> reading the <select> values, you can now use <code>onGameUserPreferenceChanged</code> instead.
*If you had a copy of the user preferences on a DB table, it's not needed anymore. Remove all support of writing to this table. Replace access to this table with
$pref = $this->userPreferences->get($playerId, $prefCode) ?? $defaultValue;
*If you used $this->player_preferences - replace the use with use of proper API

====Instant cssPref on user preferences====
A reload is not needed anymore to apply cssPref on a user preference change.

📌 Remove forceReload: true if it was only set to update the cssPref. The player will appreciate to not reload the whole page!

===Game options===

New functions to access the table options (game options) without hassle

https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Game_Options

📌
*Remove declaration of game options from "<code>initGameStateLabels</code>"
* Instead of using <code>$this->getGameStateValue</code> or <code>$this->gamestate->table_globals</code> use
$this->tableOptions->get(int $optionId)

This new object can also return the Real-time/Turn-based setting: https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Reflexion_time

==Server parts (php, sql, etc)==

===PHP migration===

Oct 2025: The migration was made from PHP7.4 to PHP8.4 new syntax and functions.

New projects are generated using the strict mode

📌

*Replace all <code>self::</code> to <code>$this-></code> - The new project template has been updated to remove this bad practice (that may be unsupported in a future PHP version)

*Add <code>declare(strict_types=1);</code> to all .php files and fix compiler warnings (if you use IDE it will detect it before upload).

===Namespaced game class===
Game class from '''''<gamename>.game.php''''' are now namespaced (and moved to modules/php/Game.php) and can autoload other classes of the same namespace

[[Main game logic: Game.php#Creating other classes]]

📌 The class file should be moved to modules/php/Game.php and adopted

(In examples below YourGameName is NOT verbatim its your game name)

* Move YourGameName.game.php to modules/php (create this dir if does not exists)
* Rename to Game.php
* Find the place below the copyright and add

declare(strict_types=1);
namespace Bga\Games\YourGameName;

* Remove
require_once APP_GAMEMODULE_PATH . "module/table/table.game.php";

* Find you class declaration change YouGameName to Game (verbatim) and change extends

class Game extends \Bga\GameFramework\Table

* All references to non-namespaced classes in this file should be defined on top of the file with "use", for example "use \BgaUserException;" as it is this non-namespaced exception is used in the zombieTurn function.

* All includes with relative path will need to be updated too.

* The material.inc.php to have be moved and included directly (see below)

Multiple functions of "Table" base class are now deprecated, see how to migrate in corresponding section

* notifyAllPlayers
* notifyPlayer
* mysql_fetch_assoc
** Deprecation warning: mysql_fetch_assoc function detected. It is deprecated, and may be removed someday. Please replace it by standard framework DB functions!
* Table (class access without namespace)
* isMutiactiveState (misspelled version)
* State management functions (getState, state, getPrivateState)
* Player information functions (getActivePlayerName, getCurrentPlayerName, getCurrentPlayerColor)
* Game mode functions (isAsync, isRealtime)
* Exception classes (feException, BgaUserException, etc.)
* ...

===Material===
Material file '''material.inc.php''' is now optional. You can define all your material directly in php class. If you still like to keep it, and using namespaced Game.php you have to move it to subfolder and include directly [[Game material description: material.inc.php#Move it to modules/php]]

=== Autowire game actions===
Simplify the action calls by removing '''<gamename>.action.php''' file

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29

📌 Autowired actions needs to start with "act", so it's risky to change them (if you change all actions names in the states.php, game, action and JS file, Real-time players will call the old name until they refresh. So, it needs to be done in two steps with duplicates on back side, or to be deployed when there is no Realt-time table running.

When migration is done, the action.php file can be deleted.

Deprecation warning: Actions detected on .action.php file. You can now use [[Main game logic: Game.php#Actions (autowired)|Auto-wired actions]] to avoid pass-through functions in .action.php file. If you transform your project to use only auto-wired actions, you can then delete the .action.php file.

=== Notifications===
Functions notifyAllPlayers and notifyPlayer from main game.php are deprecated

📌 Replace <code>$this->notifyAllPlayers</code> with <code>$this->bga->notify->all</code>
and Replace <code>$this->notifyPlayer</code> with <code>$this->bga->notify->player</code>

====Notification Decorators====
New notify function that handles decorators, reducing the duplicate code on notification args.

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Notification_decorators

====Notification args consistency====
Previously, when you sent an arg that was transformed by format_string_recursive or bgaFormatText, the args object was mutated and you got the transformed value in the notif_ handler.

The solution was to send the values in 2 different names like this:

[
'roundNumber' => $roundNumber, // number, to update the round counter
'round_number' => $roundNumber, // number that will be transformed to string by bgaFormatText, when shown in bold in the logs
]
📌 Do not duplicate the value, as the notif_ handler will now get unmutated args

===Deprecated getGameName===
The getGameName() function is now useless in the Game PHP file and can be deleted

📌 Delete the getGameName function in the Game PHP file.

Deprecation warning: getGameName function detected. It is deprecated. You can delete it, it is not used anymore

===State Management Functions===
Several state-related functions have been deprecated in favor of more explicit methods:

📌
* Replace <code>$this->gamestate->state()</code> with <code>$this->getCurrentMainState()</code> or <code>$this->getCurrentState(int $playerId)</code>
* Replace <code>$this->getState()</code> with <code>$this->getCurrentMainStateId()</code> or <code>$this->getCurrentStateId(int $playerId)</code>
* Replace <code>$this->getPrivateState($playerId)</code> with <code>$this->getCurrentState($playerId)</code>
* Replace <code>$this->gamestate->states</code> access with <code>$this->getCurrentMainState()</code> or <code>$this->getCurrentState(int $playerId)</code>
* Replace <code>$this->isMutiactiveState()</code> (misspelled) with <code>$this->isMultiactiveState()</code>

===Player Information Functions===
Several functions for getting player information are deprecated in favor of more flexible methods:

📌
* Replace <code>$this->getActivePlayerName()</code> with <code>$this->getPlayerNameById($activePlayerId)</code> using $activePlayerId magic parameter
* Replace <code>$this->getCurrentPlayerName()</code> with <code>$this->getPlayerNameById($currentPlayerId)</code> using $currentPlayerId magic parameter
* Replace <code>$this->getCurrentPlayerColor()</code> with <code>$this->getPlayerColorById($currentPlayerId)</code> using $currentPlayerId magic parameter

===Game Mode Functions===
Functions to check game mode (turn-based vs real-time) have been moved to tableOptions:

📌
* Replace <code>$this->isAsync()</code> with <code>$this->tableOptions->isTurnBased()</code>
* Replace <code>$this->isRealtime()</code> with <code>$this->tableOptions->isRealTime()</code>

===Exception Classes===
Old exception classes are deprecated in favor of namespaced versions:

📌
* Replace <code>feException</code> with <code>\Bga\GameFramework\UserException</code>, <code>\Bga\GameFramework\SystemException</code>, or <code>\Bga\GameFramework\VisibleSystemException</code> depending on your need
* Replace <code>BgaUserException</code> with <code>\Bga\GameFramework\UserException</code>
* Replace <code>BgaSystemException</code> with <code>\Bga\GameFramework\SystemException</code>
* Replace <code>BgaVisibleSystemException</code> with <code>\Bga\GameFramework\VisibleSystemException</code>
* Remove usage of <code>FEX_NOCODE</code> constant - new exception classes don't need error codes

===Namespace for Base Classes===
Old class references without namespaces are deprecated:

📌
* Replace <code>extends Table</code> with <code>extends \Bga\GameFramework\Table</code>
* Replace <code>Deck</code> with <code>\Bga\GameFramework\Components\Deck</code>

=== Deprecated APP_* Classes ===
Deprecation warning:

Reference to old APP_* class detected.

We recommend you to use composition instead of extend:

Pass `private Game $game` in the constructor of your object that need to access Table functions

If it's too complicated, at least replace APP_Object/APP_GameClass by APP_DbObject as APP_Object/APP_GameClass may be removed soon and don't contain anything more than APP_DbObject.

Don't hesitate to ask for help in the Dev Discord or in the Dev forum if you don't know how to do it!
class Tokens extends APP_GameClass {
becomes:
class Tokens extends \APP_DbObject {

=== Deprecated translation functions ===

On php side translation story is simplified

* totranslate function is not longer needed and can be replaced with clienttranslate
* $this->_() (or self::_()) can also be replaced with clienttranslate when use for non parameterized strings (but not in deprecated <game>.view.php file):

throw new UserException(clienttranslate('You must choose 3 cards'));

UserException is also handling parameterized strings like the notify functions.

All parameterized strings on PHP side have to use either the notify or the UserException formatting. If some parameterized strings are none of these, you have to remove them from PHP and rewrote them in JavaScript using dojo.string.substitute.

See [[Translations]]

=== Deprecated getNew ===
Function getNew that was only used to create new deck object is now deprecated, use $this->deckFactory->createDeck('') instead

=== Stats ===

The stats function such as initStat, setStat and getStat are also deprecated in favor of access via the objects <code>$this->tableStats and $this->playerStats</code>
See https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_Game.php#Game_statistics

===Legacy===
New object to access the legacy functions, removing the need to manually decode the JSON result when getting the values.

[[Main game logic: Game.php#Legacy games API|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Legacy_games_API]]

📌 Use $this->legacy->actionname instead of $this->actionnameLegacy and remove JSON decoding on getters

===Any Globals===
New database table and API to handle any type variables instead of numerical values only

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Use_globals

📌 If you had custom tables just for that you can drop them and use standard table

=== Server Counters ===
2 new counter classes have been added to easily handle the various counters your game might have. You also have 2 prebuilt counters: playerScore and playerScoreAux, to handle the scoring values, so you don't need to update manually the DB when setting the scores.

https://en.doc.boardgamearena.com/PlayerCounter_and_TableCounter

📌 Replace setting player_score/player_score_aux using db queries with use of $this->playerScore and $this->playerScoreAux. Remove the notifications, or part of notifications, updating the player panel score counter (if you had some custom notification you may still need them).
===Updated Zombie Mode documentation and recommendations===
We now recommend making the zombie player playing randomly, instead of passing as a default. A new "Zombie Mode level" field has been added to the Game Metadata Manager, to indicated the Zombie Mode you implemented in your game.

https://en.doc.boardgamearena.com/Zombie_Mode

===View and template files: deprecated===
'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' are now optional and are not generated anymore on a new project. The new project templates demonstrate how to work without them.

📌 The DOM should be built on the JS side to remove the view/template files, so it can be complicated for old projects using them intensively. It would look like this:
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<nowiki><span>${_('My translated text')}</span></nowiki><nowiki><div id="player-tables"></div></nowiki>
`);

See more in [[#Access template elements]]

====Forbid access to global BGA variables and direct DB access on action/view files====
If you did not remove action and view files, you cannot longer use some stuff in them, such $g_user global and db access functions.

A new getCurrentPlayerId() function has been added to those action/view classes for easier migration

📌 Replace $g_user->get_id() by $this-> getCurrentPlayerId()

Replace DB calls by $this->game->DbQuery() (and such...)

===States===
There is now a way to describe each game state in a State class, that will handle all logic and description of the state. It helps splitting the code into multiple files, instead of one big Game.php file.

https://en.doc.boardgamearena.com/State_classes:_State_directory

📌 Create a State class for each state of the game (except 1 and 99 if they are still described in states.inc.php), move the state definition in it, and adapt the "st", "arg", "actXXX" and "zombie" functions in the class. When all classes are migrated, you can remove the states.inc.php file in the FTP folder.

==== If still using states.php====
The new class GameStateBuilder helps you build the state machine, allowing auto-completion, and avoid typo errors on state types. Complete example: 📌 https://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php

States 1 and 99, that must not be changed, are now optional.

📌 Replace the array definition by GameStateBuilder use. You can remove the declaration of states 1 and 99.

Note: it's only useful if you don't migrate to State classes described above

==Client parts (js, html, css) ==
===Main class===
File is moved from yourgamename.js to modules/js/Game.js and has a different structure
https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js
It won't be easy to convert this, maybe best just to use old one which still works, but move when you write a new game.

===Deprecated ajaxcall ===
Introduced function bgaPerformAction to replace ajaxcall and checkAction combination, with a simpler syntax:

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Actions

Deprecation warning: The <code>ajaxcall</code> function is deprecated, check [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|the]] <code>bgaPerformAction</code> [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|function]].

📌 Replace combination of checkAction/ajaxcall by bgaPerformAction. Beware of the options (3rd param) if it was an ajaxcall without checkAction.

===New this.bga.* API Structure===
Many client-side functions have been reorganized into namespaced objects under <code>this.bga</code> for better organization and discoverability:

====Player Functions (this.bga.players)====
📌
* Replace <code>this.isSpectator</code> with <code>this.bga.players.isCurrentPlayerSpectator()</code>
* Replace <code>this.isCurrentPlayerActive()</code> with <code>this.bga.players.isCurrentPlayerActive()</code>
* Replace <code>this.isPlayerActive(player_id)</code> with <code>this.bga.players.isPlayerActive(player_id)</code>
* Replace <code>this.getActivePlayers()</code> with <code>this.bga.players.getActivePlayerIds()</code>
* Replace <code>this.getActivePlayerId()</code> with <code>this.bga.players.getActivePlayerId()</code>
* Replace <code>this.getFormattedPlayerName(...)</code> with <code>this.bga.players.getFormattedPlayerName(...)</code>
* Replace <code>this.addAutomataPlayerPanel(...)</code> with <code>this.bga.players.addAutomataPlayerPanel(...)</code>

====State Functions (this.bga.states)====
📌
* Replace <code>this.on_client_state</code> with <code>this.bga.states.isOnClientState()</code>
* Replace <code>this.setClientState(stateName, args)</code> with <code>this.bga.states.setClientState(stateName, args)</code>
* Replace <code>this.restoreServerGameState()</code> with <code>this.bga.states.restoreServerGameState()</code>

====Status Bar Functions (this.bga.statusBar)====
📌
* Replace <code>this.updatePageTitle()</code> with <code>this.bga.statusBar.setTitle(title, args)</code>
* Replace <code>this.removeActionButtons()</code> with <code>this.bga.statusBar.removeActionButtons()</code>

====Action Functions (this.bga.actions)====
📌
* Replace <code>this.checkAction(action, nomessage)</code> with <code>this.bga.actions.checkAction(action, nomessage)</code>
* Replace <code>this.checkPossibleActions(action)</code> with <code>this.bga.actions.checkPossibleActions(action)</code>
* Replace <code>this.bgaPerformAction(...)</code> with <code>this.bga.actions.performAction(...)</code> - Note: catch result is now <code>{ message, args }</code> instead of just <code>message</code>

====Dialog Functions (this.bga.dialogs)====
📌
* Replace <code>this.showMoveUnauthorized()</code> with <code>this.bga.dialogs.showMoveUnauthorized()</code>
* Replace <code>this.showMessage(msg, type)</code> with <code>this.bga.dialogs.showMessage(msg, type)</code>
* Replace <code>this.confirmationDialog(text, callback, callback_cancel)</code> with <code>this.bga.dialogs.confirmation(text)</code> - Note: now returns a Promise instead of using callbacks
* Replace <code>this.multipleChoiceDialog(text, choices, callback)</code> with <code>this.bga.dialogs.multipleChoice(text, choices)</code> - Note: now returns a Promise instead of using callbacks

====Image Functions (this.bga.images)====
📌
* Replace <code>this.dontPreloadImage(image)</code> with <code>this.bga.images.dontPreloadImage(image)</code> or <code>this.bga.images.dontPreloadImages([...])</code>
* Replace <code>this.ensureSpecificGameImageLoading(imagelist)</code> with <code>this.bga.images.preloadImage(image)</code> or <code>this.bga.images.preloadImages([...])</code>

====Game Area Functions (this.bga.gameArea)====
📌
* Replace <code>this.getGameAreaElement()</code> with <code>this.bga.gameArea.getElement()</code>
* Replace <code>this.addLastTurnBanner(message, args)</code> with <code>this.bga.gameArea.addLastTurnBanner(message, args)</code>
* Replace <code>this.removeLastTurnBanner()</code> with <code>this.bga.gameArea.removeLastTurnBanner()</code>
* Replace <code>this.addWinConditionBanner(message, args)</code> with <code>this.bga.gameArea.addWinConditionBanner(message, args)</code>

====Player Panel Functions (this.bga.playerPanels)====
📌
* Replace <code>this.getPlayerPanelElement(playerId)</code> with <code>this.bga.playerPanels.getElement(playerId)</code>
* Replace <code>this.scoreCtrl[player_id]</code> with <code>this.bga.playerPanels.getScoreCounter(player_id)</code>

====User Preferences (this.bga.userPreferences)====
📌
* Replace <code>this.getGameUserPreference(pref_id)</code> with <code>this.bga.userPreferences.get(pref_id)</code>
* Replace <code>this.setGameUserPreference(pref_id, value)</code> with <code>this.bga.userPreferences.set(pref_id, value)</code>

====Notification Functions (this.bga.notifications)====
📌
* Replace <code>this.bgaSetupPromiseNotifications(...)</code> with <code>this.bga.notifications.setupPromiseNotifications(...)</code>

====Animation Functions (this.bga.gameui)====
📌
* Replace <code>this.instantaneousMode</code> with <code>this.bga.gameui.bgaAnimationsActive()</code> - Note: logic is reversed (instantaneousMode was true when animations should be skipped, bgaAnimationsActive() returns true when animations should play)

===Access to DOM elements ===
New functions getPlayerPanelElement(player_id) and this.getGameAreaElement()

Note: These functions are now deprecated in favor of <code>this.bga.playerPanels.getElement(playerId)</code> and <code>this.bga.gameArea.getElement()</code>. See [[#New this.bga.* API Structure]] above.

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Adding_stuff_to_player%27s_panel

📌 Code like dojo.place(html, player_board_${player.id}); would be replaced by this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', html);
===Notification setup===
Notifications can now be automatically scanned and called without needing to register them one by one. They'll handle Promises, so they end synchronously when the Promise resolves.

Note: <code>bgaSetupPromiseNotifications</code> is now deprecated in favor of <code>this.bga.notifications.setupPromiseNotifications</code>. See [[#New this.bga.* API Structure]] above.

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Notifications

A wait function has been added to return a Promise when a delay is passed (compatible with fast-replay mode)

A new utility function has been added to support Promises for old Dojo animations

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Animation_Callbacks

📌 Dojo.subscribe calls in setupNotifications must be removed if using promise-based notification setup. Notif_ function should be async and return a Promise, make sure they wait for the expected amount of time if the sync setup was using a numerical duration

If you used Dojo animation, make them Promise compatible with "await this.bgaPlayDojoAnimation(dojoAnim);"

===Status bar manipulation===
Function to change the title from the JS

Note: <code>this.statusBar.*</code> methods are now available via <code>this.bga.statusBar.*</code> for consistency. See [[#New this.bga.* API Structure]] above.

https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar

📌 Replace direct title div manipulation with this.bga.statusBar.setTitle(title: string, args?: object), and benefit from replacement of ${actplayer}/${you}/... (see example in the link above).

This also includes a new function to create action buttons, that are more screen-reader compatible than the previous version. The new button parameters also allow you to set a confirm popin or an autoclick for confirmation buttons

📌 Replace this.addActionButton by this.bga.statusBar.addActionButton. Notice the parameters have changed, so they need to be adapted too! Remove manual setActionTimer or manual confirm with the new parameters.

===Dojo usage===
Dojo usage has been removed in the new project template and the doc. Old game can still use it but its best to migrate. This is migration table.

📌 Replace dojo by vanilla JS where possible
{| class="wikitable"
! Dojo API
! Category
! Description
! Vanilla JS Replacement
|-
| <code>dojo.byId("id")</code>
| DOM Selection
| Selects a single DOM element by its ID.
| <code>document.getElementById("id")</code>
|-
| <code>dojo.query("selector")</code>
| DOM Selection
| Selects a collection of DOM elements using CSS selectors.
| <code>document.querySelectorAll("selector")</code> or <code>document.querySelector("selector")</code>
|-
| <code>dojo.connect(node, "onclick", fn)</code>
| Event Handling
| Connects an event handler to a DOM element.
| <code>node.addEventListener("click", fn)</code>
|-
| <code>dojo.disconnect(handle)</code>
| Event Handling
| Removes an event handler created with <code>dojo.connect</code>.
| <code>handle.remove()</code> for event listeners, or <code>node.removeEventListener("click", fn)</code>
|-
| <code>dojo.stopEvent(evt)</code>
| Event Handling
| Prevents propagation and default action for an event.
| <code>evt.preventDefault(); evt.stopPropagation();</code>
|-
| <code>dojo.place(node, parent, "last")</code>
| DOM Manipulation
| Places a DOM node inside a parent node at a specific position.
| <code>parent.appendChild(node)</code>, when using raw html <code>parent.insertAdjacentHTML('beforeend', html)</code>
|-
| <code>dojo.create("tag", props, parent)</code>
| DOM Manipulation
| Creates a new DOM element with optional properties.
| <code>document.createElement("tag")</code>, then set properties and use <code>parent.appendChild()</code>
|-
| <code>dojo.style(node, "color", "red")</code>
| Styling
| Sets an inline CSS property on a DOM node. <b>CAUTION:</b> <code>dojo.style(node, "left")</code> (and "right", "width", etc) return lengths in pixels as numbers, not the set CSS style.
| <code>node.style.color = "red"</code>
|-
| <code>dojo.hasClass(node, "className")</code>
| Styling
| Checks if a DOM node has a specific CSS class.
| <code>node.classList.contains("className")</code>
|-
| <code>dojo.addClass(node, "className")</code>
| Styling
| Adds a CSS class to a DOM node.
| <code>node.classList.add("className")</code>
|-
| <code>dojo.removeClass(node, "className")</code>
| Styling
| Removes a CSS class from a DOM node.
| <code>node.classList.remove("className")</code>
|-
| <code>dojo.forEach(array, fn)</code>
| Array Utilities
| Iterates over an array.
| <code>array.forEach(fn)</code>
|-
| <code>dojo.map(array, fn)</code>
| Array Utilities
| Transforms an array by applying a function to each element.
| <code>array.map(fn)</code>
|-
| <code>dojo.fadeOut, dojo.fadeIn</code>
| Animations
| Various animations
| Use https://en.doc.boardgamearena.com/BgaAnimations or CSS animations
|-
| <code>dojo.hitch(this, "functionName")</code>
| Variable scoping
| Binds <code>this</code> (or other variable) in a callback
| <code>functionName.bind(this)</code>
|-
|<code>dojo.destroy(node)</code>
|DOM Manipulation
|Destroys a DOM element
|<code>node.remove()</code>
|-
|<code>dojo.indexof(array,value)</code>
|Array Utilities
|index of the item in the array,
|<code>array.indexof(value) or array.indexof(test)</code>
|-
|<code>dojo.string.substitute</code>
|String Utilities
|template substitution
|<code>Use JS template strings, i.e. `<div id=${id}></div>`. Note: not suitable for translations if variables are used inside</code>

For translations use `this.bga.gameui.format_string` or `this.bga.gameui.format_string_recursive`
|}

===Sound loading===
New functions load/play have been added for the sounds:

https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Sounds

📌 Replace template loading of sounds and global function playSound

===Formatting of log message using bgaFormatText===
This function, if defined, will allow you to insert HTML in the logs without overriding format_string_recursive. Example: 📌https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Define_this.bgaFormatText%28%29_method

📌 Replace the override of format_string_recursive by bgaFormatText (the last line will change)

===Automata player panel===
A new framework function to add a player panel for your game automas https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Adding_a_player_panel_for_an_automata

📌 Replace manually created automata player panel with this new function

===New JS libraries===
New JS libraries are created to help you design your games, especially for components that you will find on numerous games. See [[Studio#BGA Studio game components reference]]

📌 Replace manually created animation, stocks, etc with components (check the link above, don't want to duplicate it here)

===CSS imports===
Default BGA imports are auto-included, if you find this code and comment in .css you can delete it
@import url(../../../css/csslayer.css);
/* Note: you must not use any @import directive other than this one */

===Future support of dark mode===
BGA doesn't support dark mode yet. To have some games compatible when we do, we added a theme data tag you can use as described here:

https://en.doc.boardgamearena.com/Game_interface_stylesheet:_yourgamename.css#Support_of_the_Dark_mode
[[Category:Studio]]

Using AI for BGA game development

2026-07-16T18:44:31Z

Victoria La:

This page is to share resources and advice about using AI for BGA development.
== Overview ==

At the point of writing (Apr 2026) there is no model that can successfully code meaningful game completely using BGA framework.
But AI can be used for a lot of tasks, examples of usages:

* Generating boilerplate code
* Translating game rules from a rulebook into structured game logic and state machines
* Writing and maintaining unit tests for game operations
* Converting game material (cards, tokens, boards) from spreadsheets into PHP data structures
* Debugging complex state machine flows by analyzing execution traces
* Extracting patterns across multiple open source games
* Writing client-side UI code (TypeScript/JS) for token rendering and animations
* Reviewing code for common BGA framework pitfalls and anti-patterns
* Generating CSS/SCSS for card layouts and sprite positioning from asset images
* Explaining unfamiliar parts of the BGA framework or existing codebase
* Reviewing against bga UI guildlines
* Migrating game from old framework

== Setup ==
To set up AI for success you need to add some documentation to your project, I suggest to use misc/docs folder.
In addition you can run something like /init command to create initial AI document which it will use for your project.

Files:
* CLAUDE.md (or AI.md) - top-level project instructions that AI tools read automatically (would be in root of project)
* RULES.md - exact rules converted from PDF (you can use AI to do that too. Make sure it is NOT summarized)
* DESIGN.md - design of your game (software design) - if it does not exist ask AI to create software design document
* PROCEDURES.md - add workflows that you want AI to follow (can reference explicit skills)
* PLAN.md - implementation plan (when game is not complete)
* TODO.md - todo list (when game is complete but few things left)
* ASSETS.md - asset pipeline documentation (PDF sources, sprite sheets, conversion steps, sounds, fonts)

== Skills ==
The best way to save the workflows is to use skills. If you developed some AI skills share it here by providing link (and contact if not clear from link).

DISCLAIMER: skills shared here comes from community and not affiliated with BGA itself, contact repo maintainer for questions

=== claude-code-bga — from rulebook to a testable game on Studio ===
[https://github.com/rbellec/claude-code-bga claude-code-bga] (MIT) is a skill for [https://claude.ai/claude-code Claude Code] targeting the new (2025+) BGA framework. Rather than a single prompt, it packages the full development workflow:

* '''Project setup''' — Makefile, SFTP deploy, config files, git workflow;
* '''Framework patterns''' — PHP state machine and ES6 client, plus on-demand reference guides for the standard BGA libraries (Deck, BgaCards, Stock, Counter, Scrollmap, …);
* '''Rules clarification''' — ambiguities found during implementation are logged as tracked questions and assumptions to discuss with the game's author, instead of being silently guessed;
* '''Automated deploy-and-test loop''' — via the Claude in Chrome extension: deploy, start a hotseat table on Studio, read the browser console for PHP/JS errors, fix, repeat (~30 s per cycle);
* '''Known pitfalls''' — dbmodel.sql comments, table name conflicts, zombie handling, and other traps documented with their fixes.

It has been used to implement several games on Studio (e.g. [https://github.com/rbellec/BGA_quantum_tic_tac_toe Quantum Tic-Tac-Toe], [https://github.com/rbellec/Go-On-Rasalva-on-BGA Go On Rasalva]), to migrate a legacy game to the new framework, and to walk through rule edge cases directly on Studio tables during testing. The generated code still needs review by the developer — the skill automates the BGA-specific plumbing and test cycle, not the game design decisions.

== Other resources ==
* Chrome MCP server allows AI to see the real game https://developer.chrome.com/blog/chrome-devtools-mcp
* https://www.reddit.com/r/ClaudeAI/comments/1us9hfz/asked_claude_what_in_my_docs_was_hurting_its/
* https://www.reddit.com/r/ClaudeAI/comments/1uc7izy/i_added_a_clause_to_andrej_karpathys_4_claudemd/
* https://www.reddit.com/r/ClaudeAI/comments/1t4ncbj/10_things_about_claude_that_took_me_way_too_long/

----

[[Category:Studio]]

Create a game in BGA Studio: Complete Walkthrough

2026-07-14T01:42:10Z

Victoria La: /* Create a project */

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using the BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the [[Studio|BGA Studio]].
* Know (at least somewhat) the languages used by BGA Studio: PHP, SQL, HTML, CSS, JavaScript/TypeScript
* Set up your development environment: [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother trying to create a new game until you have completed at least one of the tutorials.

If you're stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
There is also a comunity-based Discord dev you can join here: https://discord.gg/YxEUacY.
If you find typos in this wiki, fix them (to edit wiki login in BGA itself).

'''Note on framework versions:''' BGA has a modern framework (2024+) that uses PHP state classes, TypeScript (encouraged but not mandatory), JSON config files, and attribute-based action declarations. This walkthrough covers the modern framework. If you see older examples elsewhere using <code>states.inc.php</code>, <code>material.inc.php</code>, <code>gameoptions.inc.php</code>, <code>stats.inc.php</code>, or heavy Dojo usage — those are the old patterns. This document uses the new patterns throughout.

== Select a First Game ==

For your first '''real''' game (after you've completed at least one tutorial), you must select a game from one of these options:
* [https://studio.boardgamearena.com/licensing Available Licenses]
* Public Domain

But what if the game you want isn't in either of those categories? If you're able to successfully publish another game, you may gain the trust of the BGA admins, and they will then be happy to assist you in obtaining a license for a game you really want to do. Alternatively, you can request a license yourself. For more about game licenses, see the [[BGA Game licenses]] page. Don't start a project until you are sure BGA have the licence for this game, or it will never be published to BGA!

After you choose a game, but before creating a new project, take a few seconds to [http://studio.boardgamearena.com/#!projects check the list of current projects], to make sure that someone is not already developing that game. If they are, consider asking to join the project rather than starting a new project yourself.

But even if you see a few projects with the name of the game in question, they may not be active. There are a lot of abandoned game projects. If it's not clear by the status of the project, then post to the Developers forum asking if anybody is actively working on the project, or send a message to the developers listed for the abandoned projects. At the same time, ask admins on the same forum to send you graphics for that game if they have them. (There's a button on the [https://studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but that button just sends an email.)

If your goal was to fix bugs in an existing project, first try to locate it on Studio. If the project cannot be found in Studio, write a support ticket to ask for access. Contact a project admin about getting write access to the original project, or ask if they are willing to apply your patches. If they are not active anymore, write a support ticket to ask for maintainance access for this project.

If you want to take over an existing project, first ask on the forum to see if the project is abandoned, then get read-only access (via project list) and see if it's worth using the existing project. If it has no code or graphics, then just start from the scratch. If the original project admin is not answering, write a support ticket to ask for access.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken, check the previous paragraph about existing projects. To see how to create a new game here [https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio Create a new game]

Find and start the game in turn based mode, make sure it works.

Second, modify the text in your client source (.ts or .js file) to output hello world or something, build, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a non-starter.

Update your project status on [http://studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for the license" or "waiting for graphics" or a combination of those.

== Development Tools ==

At some point, you need to setup your development environment which consists of multiple tools, such as
* Editor or IDE (VSCode is recommended for TypeScript projects)
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools
* Build tools (npm, TypeScript compiler, SCSS compiler, rollup/esbuild for bundling)

Please scan through articles from [[Studio#BGA_Studio_user_guide]] especially those related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If it's a real game, I would commit the code to version control right at the start. You are going to find yourself in a situation where the game does not even start anymore and there is no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of the major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via Studio Control Panel.

== Obtain game graphics ==

If you developing a game from the Available Licenses section, ask the admins to send you graphics by using the '''Request Art Files''' button available on the studio license page. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to the next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you are lucky they also sometimes have boards and token scans in "Game Pieces" section of Images
* If that fails, google "boardgame <name>" and check the Images section
* Get the rules PDF as well, there're tools that allow you to extract graphics from PDF, which are usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage them to fit in the BGA criteria, which usually involves
* If the publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off the scoring "ring" around the board of the game since the scoring track is not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain an electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get data from these than trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game info and box graphics ==

Even if is not playable yet, start with making sure the game looks descent in the game selector, meaning it has nice box graphics and the information is correct.

For that we need to edit [[Game_meta-information: gameinfos.jsonc|gameinfos.jsonc]].
What you would do for the real game you would go to http://boardgamegeek.com find the game and use information from the website to fill the gameinfos.

The next step is to set game metadata images, such as game box image, and they are handled in the Game Metadata Manager. Details about images can be found here: [[Game art: img directory]].

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want to put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in the project directory, it's about 10 files. Make sure the project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of a lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 players vs 4, start with the most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
First, make sure your have the [[BGA Studio Guidelines]] in mind!

Technically game elements are already designed by a board game designer but your job is to map them to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunately in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearance (i.e. red cube is a different type than blue cube)
* Super Type - one of the more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there are no colors but like player 1 - but is conceptually the same, I use color because it's easier to track)

Personally, I like to encode my elements in a string using reverse DNS notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of a yellow card (in this case yellow is the color of the deck, not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case, we don't really need to define red meeple vs blue meeple. In the new framework, material data lives in a PHP class (e.g. <code>Material.php</code>) rather than the old <code>material.inc.php</code>. For complex games, keep material data in CSV files and auto-generate the PHP code.
'meeple'=>['name'=>clienttranslate('Meeple')]
3. Client (TypeScript/JS, CSS) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css (or .scss) something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup, you have to generate all the pieces and place them in the right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in the material file as much as possible)

For complex card games, I think it is best to keep all these info and rules in a spreadsheet or CSV files and generate other files such as Material.php.
See more info below about the design of the individual layers.

More details on game elements can be found here [[BGA_Studio_Cookbook#Game_Elements]]

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with the game layout and graphics pieces. Even when nothing is working it gives you moral satisfaction!

In the modern framework, you generate all HTML from JavaScript/TypeScript — there is no template engine (<code>.tpl</code> / <code>.view.php</code> files are no longer used). You have two main approaches:
* Start with nothing and generate it all by JavaScript/TypeScript
* Generate a complete static HTML structure from JS during <code>setup()</code> and then just move pieces around with JS during notifications

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Create all UI elements by JS/TS during <code>setup()</code>.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every piece of boardgame would have its "print" in multiple files in your game:
* Some sort of "div" in html (generated by JS), where id of element match id of element in database (easiest way)
* CSS/SCSS for the element (either unique or for class), usually with background property refering to part of sprite image
* Entry in Material.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in JavaScript/TypeScript to represent a static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create the board in your client <code>setup()</code> method and place inside the main game area. In the new framework, use <code>bga.gameArea.getElement()</code> to get the game area:
<pre>
this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', `
<div id="board" class="board shadow board4p"> ... </div>
`);
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board which is different than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That would be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material file

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material file (Material.php):
<pre>
$this->token_types = [
...
'slot_action_2' => [
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
],
...
];
</pre>

Entry in HTML generated by JS, inside the "board" div:
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In CSS/SCSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
For creation, use template literals in client:
<pre>
const tokenDiv = `<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>`;
// then place it: someParent.insertAdjacentHTML('beforeend', tokenDiv);
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it during setup() and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create SCSS and HTML snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial setup (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up. In the new framework, use <code>bga.playerPanels.getElement(playerId)</code> to access individual player panels.
* Create Material.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just CSS, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Create Database Schema ==

At some point you have to design your game database. Do it sooner than later since it would be harder to change it later, since some code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible. Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank. Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance. You can forget about normalizing and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e. all token/card properties such as name, tooltips, "strength", color, etc. This is stored in the Material class (Material.php) and server has access to it from anywhere, as well as the client if you send it with <code>getAllDatas()</code>. The only reason to store some of it in database is if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture of the play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step).
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either.
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, it's usually "face up/face down", "tapped/untapped", "right side up/up side down".
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state.
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html.
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its two, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order.
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of database issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games. Here are some example of how real games are mapped to such database:

'''Chess:'''

chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos.

Note: you may need more DB tables to represent non-material aspect of the game. For example advanced action machine or multi-step undo tables.

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page and implement these step by step populating the database (using database access API). Game initialization is performed in php method <code>setupNewGame</code>, this method is called once when game table is created. LOGGING does not work in this function.

In the modern framework, <code>setupNewGame</code> in the base class handles player creation and stat initialization. You create <code>setupNewGameTables()</code> to set up your game-specific tables. The method can return a state class to jump to after setup:

<pre>
protected function setupNewGame($players, $options = []) {

// here is some generate code from template LEAVE IT UNTOUCHED
...

return $this->setupNewGameTables(); // this is YOUR new method
}

function setupNewGameTables() {
try {
$players = $this->loadPlayersBasicInfos();
// code the function
// ...
$this->activeNextPlayer(); // just in case so its not 0
$this->initStats(); // to be coded
// Setup the initial game situation here
$this->initGameTables(); // to be coded
// beggining of the turn for active player (if player state if first state)
$player_id = $this->getActivePlayerId();
$this->playerStats->inc('turns_number', 1, $player_id, true);
} catch ( Exception $e ) {
// logging does not actually work in game init :(
$this->error("Fatal error while creating game");
$this->dump('err', $e);
}
return GameDispatch::class; // return the initial state class
}
</pre>

For more tricks about debugging see this [https://en.doc.boardgamearena.com/Practical_debugging#Debugging_setupNewGame Debugging setupNewGame]

Stats are now defined in <code>stats.json</code> (not <code>stats.inc.php</code>).
<pre>
// stats.json
{
"table": {
"turns_number": { "id": 10, "name": "Number of turns", "type": "int" }
},
"player": {
"turns_number": { "id": 10, "name": "Number of turns", "type": "int" },
"game_vp_total": { "id": 11, "name": "Total VP", "type": "int" }
}
}
</pre>

For the <code>initStats()</code> method, its likely that all of the stats are <code>int</code> and you can just use this genetic initializer, but your stats have to start with <code>game_</code> prefix (verbatim):
<pre>
public function initStats()
{
// INIT GAME STATISTIC
$all_stats = $this->getStatTypes();
$player_stats = $all_stats['player'];
// auto-initialize all stats that starts with game_
// we need a prefix because there is some other system stuff
foreach ($player_stats as $key => $value) {
if (str_starts_with($key, 'game_')) {
$this->playerStats->init($key, 0);
}
if ($key === 'turns_number') {
$this->playerStats->init($key, 0);
}
}
$table_stats = $all_stats['table'];
foreach ($table_stats as $key => $value) {
if (str_starts_with($key, 'game_')) {
$this->tableStats->init($key, 0);
}
if ($key === 'turns_number') {
$this->tableStats->init($key, 0);
}
}
}
</pre>

As for <code>initGameTables()</code> - if you have a SQL layer you can use it to initialize everything, if not - the best would be to push everything in php <code>array</code> and then do one <code>INSERT</code> at the end (after all the fiddling and shuffling).

For example for the token database above, I will push all data into an array, then at the end run <code>INSERT</code>, i.e.

$values=[];
$values [] = "('meeple_ff0000_1', 'home_ff0000', 0)"; // this is actually string not array
...
$sql = "INSERT INTO token (token_key, token_location, token_state) VALUES " . implode(',', $values);
$this->DbQuery($sql);

Note: the actual data is usually either to be read from Material or call some specific methods, i.e. createGameToken('worker_red','supply',0);

== Implement one time game model synchronization ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix <code>getAllDatas</code> function to return all possible data we need to reconstruct the game. The base class <code>getAllDatas</code> already handles player info and game options, but you have to extend it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your client <code>setup()</code> method (which receives <code>gamedatas</code>) you add calls that handle data sent by server, usually by calling rendering functions such as "<code>placeToken</code>" or "<code>placeCard</code>".

So this is roughly what you need to include in <code>getAllDatas()</code>:

* Extra player info.
* Material file variables. Note - I strongly recommend using only one variable for generic data information, such as <code>$this->token_types</code>. If you start splitting it i.e. <code>card_types</code>, <code>meeple_types</code>, <code>building_types</code> - it will be very hard to deal with this programmatically as it will be lots of switches. Also call it the same as in php - otherwise its really hard to correlate.
* Game options are handled by the base class using <code>gameoptions.json</code>.
* Dump of database tables filtered by current player view.
* To be fancy you can also include php constants so you can access them in client as well.

<pre>
protected function getAllDatas() {
$result = [];

// 1. Get information about players
// Note: you can retrieve some extra field you added for "player" table in "dbmodel.sql" if you need it.
// would have been much better if its just * but we not looking for easy solutions here! so it all have to be aliases
$sql = "SELECT player_id id, player_score score, player_no no FROM player"; // note - the framework will all bunch of more fields
$result ['players'] = self::getCollectionFromDb($sql);

// 2. Material data
$result['token_types'] = $this->token_types;
// 3. Game options
$table_options = $this->getTableOptions();
$result ['table_options'] = [];
foreach ( $table_options as $option_id => $option ) {
$value = 0;
if (array_key_exists($option_id, $this->gamestate->table_globals)) {
$value = (int) $this->gamestate->table_globals [$option_id];
}
$result ['table_options'] [$option_id] = $option;
$result ['table_options'] [$option_id] ['value'] = $value;
}
// 4. Rest of the database filtered by current player
$current_player_id = self::getCurrentPlayerId(); // !! We must only return informations visible by this player !!
$result ['tokens'] = [];
$players_basic = $this->loadPlayersBasicInfos();
foreach ( $players_basic as $player_id => $player_info ) {
$color = $player_info ['player_color'];
// tableau is public info
$result ['tokens']+=$this->tokens->getTokensInLocation("tableau_$color"); // this is sql access layer for tokens table but it can be just raw SQL query with getCollectionFromDb kind of call
// hand if private info
if ($current_player_id==$player_id) {
$result ['tokens']+=$this->tokens->getTokensInLocation("hand_$color");
} else {
$result ['counters']["hand_$color"]=$this->tokens->countTokensInLocation("hand_$color");
}
}
$result ['counters']["deck]=$this->tokens->countTokensInLocation("deck");
$result ['counters']["discard"]=$this->tokens->countTokensInLocation("discard");

return $result;
</pre>

== Create State Machine ==

In the modern framework, game states are defined as '''PHP classes''' extending <code>GameState</code>, not as arrays in <code>states.inc.php</code>. Each state class is a separate file in the <code>modules/php/States/</code> directory. There is no <code>states.inc.php</code> file at all.

Here is an example of a state class:
<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\MyGame\States;

use Bga\GameFramework\StateType;
use Bga\GameFramework\States\GameState;
use Bga\GameFramework\States\PossibleAction;
use Bga\GameFramework\Actions\Types\JsonParam;
use Bga\Games\MyGame\Game;
use Bga\Games\MyGame\StateConstants;

class PlayerTurn extends GameState {
public function __construct(protected Game $game) {
parent::__construct(
$game,
id: StateConstants::STATE_PLAYER_TURN,
type: StateType::ACTIVE_PLAYER,
descriptionMyTurn: clienttranslate('${you} perform an action'),
description: clienttranslate('${actplayer} performs an action')
);
}

public function getArgs(int $active_player_id): array {
// Return state arguments (visible to players)
return [];
}

public function onEnteringState(int $active_player_id) {
// Called when this state becomes active
}

#[PossibleAction]
function action_resolve(#[JsonParam] array $data) {
// Handle player action — declared with #[PossibleAction] attribute
// No need for separate action file or possibleactions array!
}

#[PossibleAction]
function action_pass() {
// Another action
$this->game->gamestate->nextState("pass");
}

public function zombie(int $playerId) {
// Handle zombie (disconnected) player
}
}
</pre>

Key differences from the old framework:
* '''No <code>states.inc.php</code>''' — states are PHP classes in <code>modules/php/States/</code>
* '''No separate action files''' — actions are methods with <code>#[PossibleAction]</code> attribute directly on the state class
* '''No <code>possibleactions</code> array''' — the attribute replaces it
* '''State arguments''' come from <code>getArgs()</code> method, not from an <code>args</code> function name in the state array
* '''Zombie handling''' via <code>zombie()</code> method on the state class itself
* '''JSON parameters''' use <code>#[JsonParam]</code> attribute for automatic parsing
* '''CheckAction''' can be disabled per-action with <code>#[CheckAction(false)]</code> attribute

The state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go. Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states) to collect this info.

On the '''client side''', the modern framework uses a state registration pattern instead of a big switch statement. You register state handlers in your game constructor:

<pre>
// In TypeScript
class PlayerTurnHandler {
private game: Game;
private bga: Bga;

constructor(game: Game, bga: Bga) {
this.game = game;
this.bga = bga;
}

onEnteringState(args: any, isCurrentPlayerActive: boolean) {
if (!isCurrentPlayerActive) return;
// Set up UI for this state
this.bga.statusBar.addActionButton(
_('Pass'),
() => this.bga.actions.performAction('action_pass')
);
}

onLeavingState(args: any, isCurrentPlayerActive: boolean) {
// Clean up UI
}
}

// In your Game class constructor:
constructor(bga: Bga) {
super(bga);
this.bga.states.register("PlayerTurn", new PlayerTurnHandler(this, bga));
}
</pre>

This replaces the old <code>onUpdateActionButtons</code> big switch pattern. Each state gets its own handler class.

==Handle Turn Order==

If your game goes in clockwise order in natural sitting position nothing is really needed, you just use standard API and you are good. However if position is complicated it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
*Turn order depends on game situation (such as we take player with highest number of red cubes).
*Turn order is custom and assign on previous step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use <code>player_no</code> column) or use order markers that come with game (i.e. <code>marker_ff0000</code> on <code>position_1</code>). In this we can build player array in right order and pick next player based on previous player using existing helper function such as <code>$this->createNextPlayerTable($player_ids)</code>.

Handling turn order would go to the game state which is usually follows active player state.

==Hook User Input==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

In the modern framework, you set up click handlers in the state handler's <code>onEnteringState</code> method and clean them up in <code>onLeavingState</code>. Use standard DOM <code>addEventListener</code> or the framework's utilities.

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "<code>active_slot</code>", with visual effect of white dashed outline (outline is better than border, because border changes will make piece slightly move since it changes the size) or <code>box-shadow</code> (i.e. neon glow).

Here is an example with the modern framework pattern:
<pre>
// In a state handler's onEnteringState:
onEnteringState(args: any, isCurrentPlayerActive: boolean) {
if (!isCurrentPlayerActive) return;

// Highlight clickable elements
document.querySelectorAll('.card').forEach((node) => {
node.classList.add('active_slot');
node.addEventListener('click', this.onCardClick);
});

// Add action buttons to the status bar
this.bga.statusBar.addActionButton(
_('Pass'),
() => this.bga.actions.performAction('action_pass')
);
}

onLeavingState(args: any, isCurrentPlayerActive: boolean) {
// Clean up
document.querySelectorAll('.active_slot').forEach((node) => {
node.classList.remove('active_slot');
node.removeEventListener('click', this.onCardClick);
});
}

onCardClick = (event: Event) => {
const id = (event.currentTarget as HTMLElement).id;
this.bga.actions.performAction('action_playCard', { id });
};
</pre>

When user clicks on something, client sends an ajax call to server via <code>bga.actions.performAction()</code>. The server processes it, updates the database, sends notifications, and transitions to a new state. The client then receives notifications and applies animations.

'''Important:''' Use <code>bga.actions.performAction()</code> instead of the old <code>this.ajaxcall()</code> pattern. The new method handles error display, action checking, and returns a Promise:
<pre>
// Modern framework — clean and promise-based
this.bga.actions.performAction('action_playCard', { id: cardId })
?.then((result) => { console.log('action complete'); })
.catch((e) => { console.error(e.message); });
</pre>

When you insert a single action you have to update multiple files:
* In your client state handler: add <code>bga.actions.performAction()</code> call
* In the PHP state class: add a method with <code>#[PossibleAction]</code> attribute — that's it! No separate action file, no <code>possibleactions</code> array needed.
* In your PHP state method: validate input, update database, send notifications, transition to new state
* Back in client: add notification subscription and handler

==Implement Notification handling and Animation==

To handle notifications in the modern framework, use <code>bga.notifications.setupPromiseNotifications()</code>:

<pre>
// In your Game class
setupNotifications() {
this.bga.notifications.setupPromiseNotifications({
moveToken: async (args: { token_id: string, location: string }) => {
// Animate the token moving
await this.animateToken(args.token_id, args.location);
},
scoreUpdate: (args: { player_id: number, score: number }) => {
// Update score display
}
});
}
</pre>

This replaces the old pattern of <code>dojo.subscribe('notif_xxx', this, 'notif_xxx')</code>.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens. Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.
==Wrap Up==

*Implement game progression (<code>getGameProgression()</code> in php).
*Implement zombie mode. In the new framework, each state class has its own <code>zombie()</code> method.
*Define and implement some meaningful statistics for your game in <code>stats.json</code> (i.e. total points, point from source A, B, C...).
*The games logs should explain what happened if player was not looking.
*You need to implement tiebreaking (using aux score field) and updated tiebreaker description in meta-data.
*Make sure all UI strings are marked for translation.
*UI elements which are images (i.e. tokens, cards) should have tooltips.

==Alpha==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, create a build and click on the "Request ALPHA status" button and admins will check your game and push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
*Links to the rules (in multiple languages if available).
* Links to teaching videos.
*In the "On the web" section, links to:
**The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

Note: later can be done by community members, you don't actually have to do it yourself

==Level Up==

When you successfully created a basic game and you want more, it's time to make it fancy!

*Add game extensions and variants using <code>gameoptions.json</code> (not the old <code>gameoptions.inc.php</code>).
*Add user preferences for customizations using <code>gamepreferences.json</code>.
*Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs.
*You can use fancy scoring board at the end of game instead of default nothing.
*And finally super cool dice rolling, card flipping and victory points evaporating effects.

==After the alpha stage ==
If you want to update your game after alpha, please look at the [[Post-release phase]]

[[Category:Studio]]

Using AI for BGA game development

2026-07-13T23:51:13Z

Victoria La: /* Other resources = */

Using AI for BGA game development

2026-07-13T23:50:59Z

Victoria La:

Using AI for BGA game development

2026-07-13T23:49:43Z

Victoria La: /* Overview */

Translations

2026-07-04T15:31:57Z

Victoria La: /* Gender specific pronouns */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notify->all or notify->player will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notify->all or notify->player, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be marked for translation ==

YES:
* Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

NO:
* Error messages that are not supposed to happen (unexpected errors).
* Player names (i.e. do not put player_name or any php key send via notification which is essentially a player name, such as 'other_player' in 'i18n' array)
* Proper names of characters or places in some cases (consult the publisher)
* Numbers (i.e _("42"))
* Keywords used internally

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>clienttranslate("Winner")</pre> and <pre>clienttranslate("Winners")</pre> (two strings to translate) with <pre>clienttranslate("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>clienttranslate("First part of the string, ").$argument.' '.clienttranslate("second part of the string")</pre>
Write instead:
<pre>clienttranslate_('First part of the string, ${argument} second part of the string'), ['argument' => $argument ]</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* This also applies to punctuation marks. I.e. this is not good: _("Pick")+":"
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* Use same sentence for plural vs singular. We prefer to write "player gets 1 coin(s)" (or "coin/s") rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate. Also using the icon to represent coin in logs may solve this issue.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== Gender specific pronouns ==

'''Avoid using gender-specific wording as much as possible'''

Subject pronouns
* Do not use subject pronouns (he, she), use ${player_name} or word "player" if needed. Word "they" is fine in English (plural) but may be not in other languages (like French), so avoid using it also (use "players" or similar nouns).
* Do not use weird stuff like he/she or s/he, see about on how to replace them

Possessive pronouns
* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).
* The pronoun replacement system does not change word "their" as a singular genderless pronoun. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")
* If possible re-phrase to not use possessive either: "returns card to the hand" or "returns card to player's hard" is better.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = clienttranslate("my string"); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = clienttranslate( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = clienttranslate( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method. If you do that you will see this error in browser debug console:
Try to use a translated string in JS object declaration : impossible => string is NOT translated

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* Good characters to demarcate formatting are: <code>['*', '_']</code> (other single characters will work, just make sure it will be clear to a translator)
* If the replacements object is a string, the inner text will be placed within a <code><span></code> tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''Game state classes''', for the fields "description" and "descriptionmyturn".

<pre>
description: clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notify->all'' or ''notify->player'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
$this->bga->notify->all( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
$this->bga->notify->all( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
$this->bga->notify->all( 'log', notif,[]); // GOOD

$this->bga->notify->all( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
$this->bga->notify->all( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

$this->bga->notify->all( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

$this->bga->notify->all( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

==== Formatting arrays with i18n ====

When sending list to a i18n parameter, the framework will translate each entry if the value is an array.

For example with a code like this:
<pre>
'resourceNames' => ['wood', 'crystal', 'copper']),
'i18n' => ['resourceNames'],
'separator' => ['resourceNames' => 'and'],
</pre>

It will display "Wood, Crystal and Copper" (for this example, the translation is the same word with an uppercase).

There is 2 predefined separators : 'or' & 'and', that will display a comma separated list ending with that separator.

Any other separator will be used to join the list, so <code>'separator' => ['resourceNames' => ' / '],</code> will render "Wood / Crystal / Copper" (notice the spaces in the separator).

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new UserException(clienttranslate('You must choose 3 cards'));
</pre>

Note that the use of UserException signals that this exception is "expected". In theory, all exception that are expected should be translated.

<pre>
// this is the same but with variable
throw new UserException(new NotificationMessage(clienttranslate('You must choose ${n} cards'), ['n' => $card_num]));
</pre>

==== Creating labels ====
Label which is generated based of player's name, using client side (which is better):
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== Preview another language ==

Once a game is released, you can view a table as a specific language by appending a language code to the URL, such as <pre>&lang=es</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extract all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Using translations from a base project ==

In some cases, when 2 projects share a big part of the same code (example: Ticket to Ride and Ticket to Ride Europe), you might not want the translators to re-translate every sentence in common for every language. We have an experimental feature to avoid translations of sentences that are common, if you are concerned for a new project please contact us using https://studio.boardgamearena.com/support.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

Translations

2026-07-02T22:05:38Z

Victoria La: /* Gender specific pronouns */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notify->all or notify->player will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notify->all or notify->player, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be marked for translation ==

YES:
* Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

NO:
* Error messages that are not supposed to happen (unexpected errors).
* Player names (i.e. do not put player_name or any php key send via notification which is essentially a player name, such as 'other_player' in 'i18n' array)
* Proper names of characters or places in some cases (consult the publisher)
* Numbers (i.e _("42"))
* Keywords used internally

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>clienttranslate("Winner")</pre> and <pre>clienttranslate("Winners")</pre> (two strings to translate) with <pre>clienttranslate("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>clienttranslate("First part of the string, ").$argument.' '.clienttranslate("second part of the string")</pre>
Write instead:
<pre>clienttranslate_('First part of the string, ${argument} second part of the string'), ['argument' => $argument ]</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* This also applies to punctuation marks. I.e. this is not good: _("Pick")+":"
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* Use same sentence for plural vs singular. We prefer to write "player gets 1 coin(s)" (or "coin/s") rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate. Also using the icon to represent coin in logs may solve this issue.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== Gender specific pronouns ==

'''Avoid using gender-specific wording as much as possible'''

Subject pronouns
* Do not use subject pronouns (he, she), use ${player_name} or word "player" if needed. Word "they" is fine in English (plural) but may be not in other languages (like French), so avoid using it also (use "players" or similar nouns).
* Do not use weird stuff like he/she or s/he, see about on how to replace them

Possessive pronouns
* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).
* Also avoid "their". The pronoun replacement system cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")
* If possible re-phrase to not use possessive either: "returns card to the hand" or "returns card to player's hard" is better.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = clienttranslate("my string"); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = clienttranslate( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = clienttranslate( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method. If you do that you will see this error in browser debug console:
Try to use a translated string in JS object declaration : impossible => string is NOT translated

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* Good characters to demarcate formatting are: <code>['*', '_']</code> (other single characters will work, just make sure it will be clear to a translator)
* If the replacements object is a string, the inner text will be placed within a <code><span></code> tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''Game state classes''', for the fields "description" and "descriptionmyturn".

<pre>
description: clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notify->all'' or ''notify->player'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
$this->bga->notify->all( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
$this->bga->notify->all( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
$this->bga->notify->all( 'log', notif,[]); // GOOD

$this->bga->notify->all( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
$this->bga->notify->all( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

$this->bga->notify->all( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

$this->bga->notify->all( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

==== Formatting arrays with i18n ====

When sending list to a i18n parameter, the framework will translate each entry if the value is an array.

For example with a code like this:
<pre>
'resourceNames' => ['wood', 'crystal', 'copper']),
'i18n' => ['resourceNames'],
'separator' => ['resourceNames' => 'and'],
</pre>

It will display "Wood, Crystal and Copper" (for this example, the translation is the same word with an uppercase).

There is 2 predefined separators : 'or' & 'and', that will display a comma separated list ending with that separator.

Any other separator will be used to join the list, so <code>'separator' => ['resourceNames' => ' / '],</code> will render "Wood / Crystal / Copper" (notice the spaces in the separator).

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new UserException(clienttranslate('You must choose 3 cards'));
</pre>

Note that the use of UserException signals that this exception is "expected". In theory, all exception that are expected should be translated.

<pre>
// this is the same but with variable
throw new UserException(new NotificationMessage(clienttranslate('You must choose ${n} cards'), ['n' => $card_num]));
</pre>

==== Creating labels ====
Label which is generated based of player's name, using client side (which is better):
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== Preview another language ==

Once a game is released, you can view a table as a specific language by appending a language code to the URL, such as <pre>&lang=es</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extract all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Using translations from a base project ==

In some cases, when 2 projects share a big part of the same code (example: Ticket to Ride and Ticket to Ride Europe), you might not want the translators to re-translate every sentence in common for every language. We have an experimental feature to avoid translations of sentences that are common, if you are concerned for a new project please contact us using https://studio.boardgamearena.com/support.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

Translations

2026-07-02T21:26:58Z

Victoria La: /* How to not make translators crazy ;) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notify->all or notify->player will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notify->all or notify->player, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be marked for translation ==

YES:
* Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

NO:
* Error messages that are not supposed to happen (unexpected errors).
* Player names (i.e. do not put player_name or any php key send via notification which is essentially a player name, such as 'other_player' in 'i18n' array)
* Proper names of characters or places in some cases (consult the publisher)
* Numbers (i.e _("42"))
* Keywords used internally

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>clienttranslate("Winner")</pre> and <pre>clienttranslate("Winners")</pre> (two strings to translate) with <pre>clienttranslate("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>clienttranslate("First part of the string, ").$argument.' '.clienttranslate("second part of the string")</pre>
Write instead:
<pre>clienttranslate_('First part of the string, ${argument} second part of the string'), ['argument' => $argument ]</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* This also applies to punctuation marks. I.e. this is not good: _("Pick")+":"
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* Use same sentence for plural vs singular. We prefer to write "player gets 1 coin(s)" (or "coin/s") rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate. Also using the icon to represent coin in logs may solve this issue.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== Gender specific pronouns ==

* Avoid using gender-specific wording as much as possible.
* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).
* Also avoid "their". The pronoun replacement system cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = clienttranslate("my string"); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = clienttranslate( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = clienttranslate( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method. If you do that you will see this error in browser debug console:
Try to use a translated string in JS object declaration : impossible => string is NOT translated

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* Good characters to demarcate formatting are: <code>['*', '_']</code> (other single characters will work, just make sure it will be clear to a translator)
* If the replacements object is a string, the inner text will be placed within a <code><span></code> tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''Game state classes''', for the fields "description" and "descriptionmyturn".

<pre>
description: clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notify->all'' or ''notify->player'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
$this->bga->notify->all( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
$this->bga->notify->all( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
$this->bga->notify->all( 'log', notif,[]); // GOOD

$this->bga->notify->all( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
$this->bga->notify->all( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

$this->bga->notify->all( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

$this->bga->notify->all( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

==== Formatting arrays with i18n ====

When sending list to a i18n parameter, the framework will translate each entry if the value is an array.

For example with a code like this:
<pre>
'resourceNames' => ['wood', 'crystal', 'copper']),
'i18n' => ['resourceNames'],
'separator' => ['resourceNames' => 'and'],
</pre>

It will display "Wood, Crystal and Copper" (for this example, the translation is the same word with an uppercase).

There is 2 predefined separators : 'or' & 'and', that will display a comma separated list ending with that separator.

Any other separator will be used to join the list, so <code>'separator' => ['resourceNames' => ' / '],</code> will render "Wood / Crystal / Copper" (notice the spaces in the separator).

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new UserException(clienttranslate('You must choose 3 cards'));
</pre>

Note that the use of UserException signals that this exception is "expected". In theory, all exception that are expected should be translated.

<pre>
// this is the same but with variable
throw new UserException(new NotificationMessage(clienttranslate('You must choose ${n} cards'), ['n' => $card_num]));
</pre>

==== Creating labels ====
Label which is generated based of player's name, using client side (which is better):
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== Preview another language ==

Once a game is released, you can view a table as a specific language by appending a language code to the URL, such as <pre>&lang=es</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extract all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Using translations from a base project ==

In some cases, when 2 projects share a big part of the same code (example: Ticket to Ride and Ticket to Ride Europe), you might not want the translators to re-translate every sentence in common for every language. We have an experimental feature to avoid translations of sentences that are common, if you are concerned for a new project please contact us using https://studio.boardgamearena.com/support.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

Tutorial reversi

2026-06-22T19:00:36Z

Victoria La:

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* '''Setup your development environment''' [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]

Note: If you get stuck and you need the source code for this project you can get read only access to project reversi from the Studio projects page.

=== Javascript or Typescript ===
If your not familiar with Typescript, we recommend to follow the tutorial using the Javascript version.

If you're more comfortable with Typescript than plain Javascript, you can try to follow the Typescript version of the tutorial.

Any difference between the Javascript and the Typescript version of this tutorial will be <span style="outline: 3px solid #3178C6; padding: 5px;margin: 5px;"><span style="background: #3178C6; color: white; margin-right: 5px;">TS</span>outlined with this color</span>.

== Create your first game ==

''Note: you should already have created a project following instructions in [[First_steps_with_BGA_Studio#Create_a_new_game_project|Create a new game project]]. While you will find a '''reversi''' directory in your SFTP folder, do not use it for this tutorial. Instead, use the project you have created as an (empty) starting point.''

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 2. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games. By default the game requires 2 players, so press "Express Start". It will open another tab with another of your players.
* Reminder: Always use the "Express Start" button to start the game.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

End the game by clicking on the game options icon on the top right, and then on "Express Stop".

'''If you don't want to use TypeScript in your project,''' you can delete the package.json, tsconfig.json, rollup.config.mjs files and the src-disabled folder.

== Editing the game information (Optional) ==

This step is optional and will fix the warnings on the project page (missing BGG_ID and presentation).

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.jsonc</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 26.
** Add <code>1,</code> to the players array (so you can start 1-player games while testing) - that's around line 29.
* Upload the <code>gameinfos.jsonc</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the the local version, click Game page and check if the information match what you changed in the gameinfos file. [[File:Studio local version block.png|frameless]]

===== Not working? =====
Some changes will require bypassing the cache (adding/changing images). It is often worth doing a hard refresh (Ctrl+F5) to make sure the latest version is used.

== Make sure the IDE is properly configured ==
Try to add some invalid values in the framework names like this :

[[File:Voluntary reversi tutorial ide error.png]]

The error should be underlined if your IDE is properly configured. If it is not, check [[Setting up BGA Development environment using VSCode]]

In the same fashion, the autocomplete of the IDE should propose you some values after <code>this->bga-></code>.

You can also check if the upload works as expected, the game should now work and display the error (Undefined property: Bga\Games\EmptyGame\Game::$bgaTEST ...).

Revert to the correct syntax.

== Make it look like Reversi ==

Let's start with the board. This will give you a good idea of how things will look and where tokens should go.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we chose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg files are lighter than png, so they are faster to load. Later, we are going to use PNGs for tokens because they allow for transparency.

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>modules/js/Game.js</code> to add the <code>div</code> for your board at the beginning of the setup function.

Note: If you are building this game by following the tutorial, you will have a different project name than <code>reversi</code> (i.e. <code>mygame.css</code>). The file names in your project will be different than shown in this tutorial, replacing <code>reversi</code> with your project name. Be sure that any code (other than comments) that references <code>reversi</code> is changed to your actual project name.

<div style="outline: 3px solid #3178C6; padding: 5px;margin: 5px;"><span style="background: #3178C6; color: white; margin-right: 5px;">TS</span>Whenever the tutorial mentions Game.js, change the src/ts/Game.ts instead. Make sure you have installed the necessary dependencies with <code>npm i</code> then trigger autobuild with <code>npm run build:ts</code> so the TS you change is built to modules/js/Game.js</div>.

Edit the Game.js file and replace the code after '''// Example to add a div on the game area''' with the following:
<pre>
this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', `
<div id="board">
</div>
`);
</pre>

Note: example above use backticks, aka string template literals. This technique used a lot in code of games as it allows to easily create html with strings substitutions, use quotes, double quotes and newlines.
If you don't know what it is check here
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals

*edit your <code>reversi.css</code> file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
}

and remove the code in Game.js in method onEnteringState that refers to adding action buttons and remove the section under <code>// example of adding a div for each player"</code>.

'''Important: refresh your page.''' Here's your board:[[File:reversi1.jpg]]

If the board does not appear, refresh the page (always do this when you update the CSS file), and check the image filename. Remember file names are case sensitive!

==== Code the Grid====
Now, we need to create some invisible HTML elements where squares are. These elements will be used as position references for the white and black tokens.

=====Build the grid of squares=====
The board is 8 squares by 8 squares. This means we need 64 squares. To avoid writing 64 individual <code>div</code> elements on our template, we are going to generate the squares on JS <code>setup</code>.

We'll do this in our Javascript <code>setup</code> method under <code>// TODO: Set up your game interface here, according to "gamedatas"</code>.

<pre>
const board = document.getElementById('board');
const hor_scale = 64.8;
const ver_scale = 64.4;
for (let x=1; x<=8; x++) {
for (let y=1; y<=8; y++) {
const left = Math.round((x - 1) * hor_scale + 10);
const top = Math.round((y - 1) * ver_scale + 7);
// we use afterbegin to make sure squares are placed before discs
board.insertAdjacentHTML(`afterbegin`, `<div id="square_${x}_${y}" class="square" style="left: ${left}px; top: ${top}px;"></div>`);
}
}
</pre>

Note: as you can see, squares in our <code>board.jpg</code> files do not have an exact width/height in pixels, and that's the reason we are using floating point numbers here.

=====Style Those Squares=====
Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
position: relative;
}

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
display: flex;
justify-content: center;
align-items: center;
}
</pre>

Explanations:
*With "<code>position: relative</code>" on board, we ensure square elements are positioned relatively to board.
*<code>background-color: red;</code> is used for testing. This allows us to see the invisible elements. (You could instead do something like <code>outline: 2px solid orange;</code> have fun and be creative)
*The display flex with center will place the disc in the center of the square.

Let's refresh and check our (beautiful) squares:

[[File:reversi2.jpg]]

Now that you know the squares are there, you can remove the test line <code>background-color: red;</code> from your <code>.square</code> class in the CSS stylesheet.

===== Not Working?=====
If the styled squares do not appear, inspect and check your css (Chrome DevTools: Application > Frames > top > Stylesheets > reversi.css).

==The Tokens==

Now, our board is ready for some tokens!

[Note: Throughout this tutorial, sometimes "tokens" is used, and sometimes "discs" is used. They are often swapped if you're looking at code in the reversi example project.]

===Build the Token===
There are quite a few steps before the tokens will appear. You may be used to testing after every change, but that won't work well here. The token will '''not''' show until you have add styles to the css, utility method in the js, adjusted the php file, and added the token to the board in the js file.

====Add Token to img directory ====
Here's a new piece of art with the tokens. We need transparency here so we are using a png file:

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory. NB: may need to manually upload as have found that the automatic SFTP does't seem to pick up images.

Important Fun Fact: we are using ONE file for both tokens. It is really important to use a minimum number of graphic files for your game. This is called the "CSS sprite" technique, because it makes the game load faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

====Style the Tokens in .css file ====
<pre>
.disc {
position: relative;
width: 54px;
height: 54px;
z-index: 3;
transform-style: preserve-3d;
}
.disc .disc-faces {
transform-style: preserve-3d;
}
.disc[data-color="000000"] .disc-faces {
transform: rotateY(180deg);
}

.disc-face {
position: absolute;
width: 54px;
height: 54px;
background-image: url('img/tokens.png');
background-size: auto 100%;
backface-visibility: hidden;
}
.disc-face[data-side="white"] {
background-position-x: 0%;
transform: rotateY(0deg);
}
.disc-face[data-side="black"] {
background-position-x: 100%;
transform: rotateY(180deg);
}
</pre>

With this CSS code, we can set and change the token color by changing the <code>data-color</code> attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).
We will create a disc-faces div in the disc containing 2 disc-face divs, to represent each face of the disc. It will allow us to have a nice flip animation!

====Add Token Utility Method in .js file====
Now, let's make the first token appear on our board. Tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, using a template string

Let's create a method in our Javascript code (in the <code>modules/js/Game.js</code> file) that will make a token appear on the board, using this template. Add under the section <code>//// Utility methods</code>:

<pre>
async addDiscOnBoard( x, y, playerId, animate = true )
{
const color = this.gamedatas.players[ playerId ].color;
const discId = `disc_${x}_${y}`;

document.getElementById(`square_${x}_${y}`).insertAdjacentHTML('beforeend', `
<div class="disc" data-color="${color}" id="${discId}">
<div class="disc-faces">
<div class="disc-face" data-side="white"></div>
<div class="disc-face" data-side="black"></div>
</div>
</div>
`);

if (animate) {
const element = document.getElementById(discId);
await this.animationManager.fadeIn(element, document.getElementById(`overall_player_board_${playerId}`));
}
}
</pre>

<div style="outline: 3px solid #3178C6; padding: 5px;margin: 5px;"><span style="background: #3178C6; color: white; margin-right: 5px;">TS</span>Type the function parameters: <code>async addDiscOnBoard( x: number, y; number, playerId: number, animate: boolean = true )</code></div>

For this to work, you will also need to initialize the animation manager. Include the function in your .js file by updating as outlined here: [[BgaAnimations]]. Then add this in the setup function:
<pre>

this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});
</pre>

<div style="outline: 3px solid #3178C6; padding: 5px;margin: 5px;"><span style="background: #3178C6; color: white; margin-right: 5px;">TS</span>Uncomment the code in libs.ts then add <code>import { BgaAnimations, BgaCards } from "./libs";</code> at the very beginning of the Game.ts file</div>

=====Utility Method Explanation=====
*with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of the square div element.
*Immediately after, using <code>this.animationManager.fadeIn</code> BGA method, we make the disc slide in (with a fade in animation) from the player panel.

Also note the trailing comma - this is needed because there may be other functions defined after this one, making <code>addDiscOnBoard</code> just one element in an array of functions.

====Set Token Colors in setupNewGame in modules/php/Game.php file====
Before we can show a token, we need to set the player colors in the <code>setupNewGame</code> function in <code>modules/php/Game.php</code>:

Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
$default_colors = ["ffffff", "000000"];
</pre>

Note: A few lines below, you may have to remove the line <code>this->reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );</code>

===Test the Token===
Now, to test if everything works fine we will call the <code>addTokenOnBoard()</code> in .js file to Test

In <code>modules/js/Game.js</code>, in the <code>setup</code> function, under the code we added to generate the squares.
this.addDiscOnBoard(2, 2, this.bga.players.getCurrentPlayerId(), false);
Now restart the game.

A token should appear and slide immediately to its position, like this:

[[File:reversi3.jpg]]

==The database==

We did most of the client-side programming, so let's have a look on the other side now. To design the database model of our game, you will need to access the database. You won't need to do anything in database UI, yet.

===Accessing the Database===
To access the database, start a game, then click "Go to game database" link at the bottom of our game, to access the database directly with a PhpMyAdmin instance.

After the first time you've access the database, you could skip opening a game and instead, go to https://studio.boardgamearena.com/db/ . Your PhpMyAdmin username/password is in your welcome email.

'''Note''': do not remove existing tables

===Create Table in .sql file===
Now, you are able to create the table(s) you need for your game, and report every SQL command used in your <code>dbmodel.sql</code> file.

The database model of Reversi is short: just one table with the squares of the board.

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint unsigned NOT NULL,
`board_y` smallint unsigned NOT NULL,
`board_player` int unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
</pre>

Add the above SQL to <code>dbmodel.sql</code>. Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL.

===Test the Table===
Now, a new database with a <code>board</code> table will be created each time we start a Reversi game. This is why after modifying our <code>dbmodel.sql</code> it's a good time to stop your current game & start a new game.

Start a new game and verify a table is created : Click the "Go to game database", use the login and password your received by email, then you should see <code>board</code> in the list of tables (the db of the current table is automatically selected when clicking on this button).

== Setup the initial game position ==

'''Note''': From now on, you must launch the game with '''two players''' to get two <code>player_id</code>s within the database. Otherwise, the game will crash.

The <code>setupNewGame</code> method of our <code>Game.php</code> is called during initial setup. This initializes our data and places the starting tokens on the board. At the beginning of the game, there should be 4 tokens on the board.

===Initialize the Board in modules/php/Game.php file===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board
<pre>
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
// Init the board
$this->boardManager->initializeBoard(8, (int) $blackplayer_id, (int) $whiteplayer_id);
</pre>

Wait, is that all?

No, the boardManager doesn't exist, we'll create it so it will handle all the functions related the tokens on the board. Splitting the code in multiple files will help us have easier to read classes, even more if each class handle a specific responsability.

Create a BoardManager.php file next to Game.php, and put this code in it:
<pre>
<?php
declare(strict_types=1);

namespace Bga\Games\Reversi;

class BoardManager
{
public function __construct(private Game $game)
{
}

public function initializeBoard(int $boardSize, int $blackPlayerId, int $whitePlayerId): void
{
$sqlValues = [];
$boardSizeHalf = (int) floor($boardSize / 2);

for ($x = 1; $x <= $boardSize; $x++) {
for ($y = 1; $y <= $boardSize; $y++) {
$discValue = 'NULL';
if (($x === $boardSizeHalf && $y === $boardSizeHalf) || ($x === ($boardSizeHalf + 1) && $y === ($boardSizeHalf + 1))) {
$discValue = (string) $whitePlayerId;
} elseif (($x === $boardSizeHalf && $y === ($boardSizeHalf + 1)) || ($x === ($boardSizeHalf + 1) && $y === $boardSizeHalf)) {
$discValue = (string) $blackPlayerId;
}

$sqlValues[] = "($x,$y,$discValue)";
}
}

$sql = "INSERT INTO `board` (`board_x`,`board_y`,`board_player`) VALUES " . implode(',', $sqlValues);
$this->game->DbQuery($sql);
}
}
</pre>

Once the php file is created edit the namespace and change \Reversi to be the name of your project

Note: the file name match the class name, and the namespace will now match the one from Game.php (so we are following PSR-4 specification), allowing BGA to autoload the class when we will need it. Let's initialize it from the Game.php file!

Before the Game __construct, add
<pre>
public BoardManager $boardManager;
</pre>

At the end of the Game __construct, add
<pre>
$this->boardManager = new BoardManager($this);
</pre>

Passing the game object to the constructor allows us to use its db functions.

If we were managing cards, we would have probably used the [[Deck]] component, and ideally we would create a CardManager that holds the Deck and all game specific logic about managing the cards.

==== Board Initialization Explanation ====

*We create one table entry for each square, with a <code>NULL</code> value which means "empty square"
* On 4 of the squares, we place an initial token.

After this, we set <code>activeNextPlayer</code> to make the first player active at the beginning of the game (this line is already present in the default code template).

If you didn't do it earlier, you need to remove the call to <code>this->reattributeColorsBasedOnPreferences()</code> in <code>SetupNewGame()</code>. If you don't, player color preferences will try (and fail) to override the two colors supported here.

===Show the Initial Token Setup ===
Now, we need to make these tokens appear on the client side. The first step is to return the token positions with our <code>getAllDatas()</code> PHP method. <code>getAllDatas()</code> is called during each page reload.

In the <code>getAllDatas()</code> method, after <code>// TODO: Gather all information about current game situation (visible by player $current_player_id)</code>, add the following lines:

<pre>
// Get reversi board token
$result['board'] = $this->boardManager->getOccupiedDiscs();
</pre>
And in the board manager, add:
<pre>
public function getOccupiedDiscs(): array
{
return $this->game->getObjectListFromDB(
"SELECT `board_x` `x`, `board_y` `y`, `board_player` `player`
FROM `board`
WHERE `board_player` IS NOT NULL"
);
}
</pre>

Next, you will modify the query that gets player information to also get the player's colors. Above the lines you just inserted in <code>getAllDatas()</code> notice how we've added <code>player_color color</code> to the sql query in the code below.

<pre>
$result["players"] = $this->getCollectionFromDb(
"SELECT `player_id` `id`, `player_score` `score`, `player_color` `color` FROM `player`"
);
</pre>

We are using the BGA framework's <code>getObjectListFromDB()</code> that formats the result of this SQL query in a PHP array with x, y and player attributes. We add it to the result associative array with the key <code>board</code>.

Last, we process this array client side. Let's place a token on the board for each array item. We'll do this in our Javascript <code>setup</code> method under the code we added to generate the squares.

This will result in a removal or edit of the previously added line <code>this.addDiscOnBoard(2, 2, this.bga.players.getCurrentPlayerId());</code>

<pre>
for( var i in gamedatas.board ) {
const square = gamedatas.board[i];

if( square.player !== null ) {
this.addDiscOnBoard( square.x, square.y, square.player );
}
}
</pre>

The <code>board</code> entry created in <code>getAllDatas()</code> is used here as <code>gamedatas.board</code>

===Test the Game Start===
Reload... and here we are:

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

==State Machine==

Stop your game, again. You're about to start the core game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic. For reversi, it's relatively simple. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

===Build your States===
And here are the classes we need to create on the <code>module/php/States</code> folder, according to this diagram (note - PlayerTurn is replaced by PlayDisc):

'''PlayDisc.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class PlayDisc extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game) {
parent::__construct($game,
id: 10,
type: StateType::ACTIVE_PLAYER,

description: clienttranslate('${actplayer} must play a disc'),
descriptionMyTurn: clienttranslate('${you} must play a disc'),
);
}

function zombie(int $playerId) {
}
}
</pre>

(The ''declare(strict_types=1)'' is optional but recommended for new games). The ''<?php'' at the beginning is necessary for your IDE to understand the php syntax. )

In PlayDisc.js remove the code in onEnteringState (which sets the title top you/activealayer must play a counter )

'''NextPlayer.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class NextPlayer extends \Bga\GameFramework\States\GameState
{

public function __construct(protected Game $game) {
parent::__construct($game,
id: 90,
type: StateType::GAME,

updateGameProgression: true,
);
}
}
</pre>
Note: state ids 1 and 99 are reserved by the framework for gameSetup and gameEnd. We don't need to describe those states as the framework will take care of that for us.

In setupNewGame in Game.php, make sure the return is <code>return PlayDisc::class;</code> so the framework knows which game state is the initial one.

===Test Your States===
... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state <code>PlayDisc</code> right after the initial setup. That's why the status bar contains the description of <code>PlayDisc</code> state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

==The rules==

We will use the <code>getPossibleMoves</code> PHP method to:
*Indicate to the current player where she is allowed to play by returning a list of coordinates
*Check if the player has the right to play in the spot they choose

<blockquote>
Example of <code>getPossibleMoves</code> here https://gist.github.com/leocaseiro/a8bc2851bd0caddd06685b5035937d15
</blockquote>

This is pure PHP programming here, and there are no special things from the BGA framework that can be used. This is why we won't go into details here. The overall idea is:
* Create a <code>getTurnedOverDiscs(x,y)</code> method that returns coordinates of discs that would be turned over if a token would be played at <code>x</code>,<code>y</code>.
* Loop through all free squares of the board and call the <code>getTurnedOverDiscs</code> method on each of them. If at least 1 token is turned over, this is a valid move.

IMPORTANT: Making a database query is slow! Please don't load the entire game board with a SQL query multiple times. In our implementation, we load the entire board once at the beginning of <code>getPossibleMoves</code>, and then pass the board as an argument to all methods.

If you want to look into details, please look at the "utility method" sections of <code>Game.php</code>. If building the tutorial yourself, copy the functions under "Utility functions" comment from the Reversi tutorial.

==Display allowed moves==

Now we want to highlight the squares where the player can place a disc.

To do this, we add a <code>getArgs</code> method in <code>modules/php/States/PlayDisc.php</code>. This method is called on the server each time we enter into <code>PlayDisc</code> game state, and its result is transferred automatically to the client-side:

<pre>
function getArgs(int $activePlayerId): array
{
return [
'possibleMoves' => $this->game->boardManager->getPossibleMoves($activePlayerId)
];
}
</pre>

Now we need to handle it on the JS side.
Replace the state classes definition in the Game constructor by this:
<pre>
// Declare the State classes
this.playDisc = new PlayDisc(this, bga);
this.bga.states.register('PlayDisc', this.playDisc);
</pre>
So it matches the state we described in PHP. The state name is the PHP class name, that we use in register to link them.

Replace the class PlayerTurn in <code>modules/js/Game.js</code> by this one:
<pre>
class PlayDisc {
constructor(game, bga) {
this.game = game;
this.bga = bga;
}

onEnteringState(args, isCurrentPlayerActive) {
this.bga.statusBar.setTitle(isCurrentPlayerActive ?
_('${you} must play a disc') :
_('${actplayer} must play a disc')
);

if (isCurrentPlayerActive) {
this.updatePossibleMoves(args.possibleMoves);
}
}
}
</pre>

<div style="outline: 3px solid #3178C6; padding: 5px;margin: 5px;"><span style="background: #3178C6; color: white; margin-right: 5px;">TS</span>In Typescript, we will split the classes in different files that will all be bundled in Game.js in the end. So put the PlayDisc class in src/ts/States/PlayDisc.ts and export the class, so it can be then imported into Game.ts

The typings to add
<pre>
constructor(private game: Game, private bga: Bga<YourGameNamePlayer, YourGameNamePGamedatas>) {
...
onEnteringState(args: PlayDiscArgs, isCurrentPlayerActive: boolean) {
</pre>

Also add in types.d.ts:
<pre>
type PossibleMoves = {[x: number]: {[y: number]: boolean } };
interface PlayDiscArgs {
possibleMoves: PossibleMoves;
}
</pre>
</div>

<b>Note:</b> We set the title when entering the state, so you can now remove description/descriptionMyTurn in the PHP class that was just here for test purpose.

We use the <code>getPossibleMoves</code> method we just developed.

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method of the JS State class. This lets us use the data returned by the method above on the client side.

So, when we enter into <code>PlayDisc</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method is added to PlayDisc class and looks like this:
<pre>
updatePossibleMoves(possibleMoves) {
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

for( let x in possibleMoves ) {
for( let y in possibleMoves[ x ] ) {
// x,y is a possible move
document.getElementById(`square_${x}_${y}`).classList.add('possibleMove');
}
}

this.bga.gameui.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
}
</pre>
Here's what this does. At first, it removes all <code>possibleMove</code> classes currently applied with the very useful <code>document.querySelectorAll</code> method.

Then it loops through all possible moves our PHP <code>updatePossibleMoves</code> function created for us, and adds the <code>possibleMove</code> class to each corresponding square.

Finally, it uses the BGA framework <code>addTooltipToClass</code> method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

<div style="outline: 3px solid #3178C6; padding: 5px;margin: 5px;"><span style="background: #3178C6; color: white; margin-right: 5px;">TS</span>We can reuse the type <code>PossibleMoves/code> we defined before :
<pre>
updatePossibleMoves(possibleMoves: PossibleMoves) {
</pre>
</div>

To see the possible moves we need to create a CSS class (<code>possibleMove</code>) that can be applied to a <code>square</code> element to highlight it:
<pre>
.possibleMove {
background-color: white;
opacity: 0.2;
cursor: pointer;
}
</pre>

And here we are:

[[File:reversi8.jpg.jpg]]

==Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a square, check if it is a <code>possibleMove</code> and if so, send the move to the server.
*Server side, check the move is correct, apply Reversi rules and jump to next player.
*Client side, change the token position to reflect the move.

First we associate each click on a square to one of our methods using our Javascript <code>setup</code> method:

<pre>
document.querySelectorAll('.square').forEach(square => square.addEventListener('click', e => this.onPlayDisc(e)));
</pre>

Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc(evt) {
// Stop this event propagation
evt.preventDefault();
evt.stopPropagation();

// Get the cliqued square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if(!document.getElementById(`square_${x}_${y}`).classList.contains('possibleMove')) {
// This is not a possible move => the click does nothing
return ;
}

this.bga.actions.performAction("actPlayDisc", {
x:x,
y:y
});
},
</pre>

What we do here is:
*We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
*We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
*We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
*Finally, we make a call to the server using BGA <code>bgaPerformAction</code> method with argument x and y. This call will check that <code>actPlayDisc</code> action is possible, according to current game state (we will add the <code>PossibleAction</code> attribute on <code>actPlayDisc</code> just after). This check is important to avoid issues if a player double clicks on a square.

Now, we have to manage this <code>actPlayDisc</code> action on the server side. Add a corresponding <code>actPlayDisc</code> method in our <code>PlayDisc</code> state class (<code>PlayDisc.php</code>):

<pre>
#[PossibleAction]
function actPlayDisc( int $x, int $y, int $activePlayerId )
{
</pre>
And add <code>use Bga\GameFramework\States\PossibleAction;</code> at the top of the file.

(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check [[Main game logic: Game.php|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29]] )

now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible:
<pre>
// Now, check if this is a possible move
$board = $this->game->boardManager->getBoard();
$turnedOverDiscs = $this->game->getTurnedOverDiscs( $x, $y, $activePlayerId, $board );

if( count( $turnedOverDiscs ) === 0 ) {
throw new SystemException("Impossible move");
}
</pre>

we update the database to change the color of all turned over disc + the disc we just placed:
<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$this->game->boardManager->applyMove($activePlayerId, $x, $y, $turnedOverDiscs);
</pre>

We add this part to the BoardManager before going back to our act function:
<pre>
public function applyMove(int $playerId, int $x, int $y, array $turnedOverDiscs): void
{
$positions = [];
foreach ($turnedOverDiscs as $turnedOver) {
$turnedX = (int) $turnedOver['x'];
$turnedY = (int) $turnedOver['y'];
$positions[] = "($turnedX,$turnedY)";
}
$positions[] = "($x,$y)";

$sql = "UPDATE `board` SET `board_player` = $playerId WHERE (`board_x`, `board_y`) IN (" . implode(',', $positions) . ")";
$this->game->DbQuery($sql);
}
</pre>

define what game statistics we want to record (for more details read [[Game statistics: stats.json]]), For this tutorial we need to edit the stats.json file and set it to the following:
{
"table": [],
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
we manage game statistics:
<pre>
$this->bga->playerStats->inc('turnedOver', $disc_count, $activePlayerId);
$updatedStat = 'discPlayedOnCenter';
if( ($x==1 && $y==1) || ($x==$board_size && $y==1) || ($x==1 && $y==$board_size) || ($x==$board_size && $y==$board_size) ) {
$updatedStat = 'discPlayedOnCorner';
} else if( $x==1 || $x==$board_size || $y==1 || $y==$board_size ) {
$updatedStat = 'discPlayedOnBorder';
}
$this->bga->playerStats->inc($updatedStat, 1, $activePlayerId);
</pre>

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

$this->bga->notify->all( "turnOverDiscs", '', array(
'player_id' => $activePlayerId,
'turnedOver' => $turnedOverDiscs
) );
</pre>

Then we update the scores accordingly
<pre>
$playerIds = array_keys($this->game->loadPlayersBasicInfos());
foreach ($playerIds as $playerId) {
$tokens = $this->game->boardManager->countDiscsForPlayer((int) $playerId);
$this->bga->playerScore->set($playerId, $tokens); // this will update the JS counter automatically
}
</pre>

In BoardManager, add:
<pre>
public function countDiscsForPlayer(int $playerId): int
{
return (int) $this->game->getUniqueValueFromDB("SELECT COUNT(*) FROM `board` WHERE `board_player` = $playerId");
}
</pre>

We are using for that 2 notifications (<code>playDisc</code> and <code>turnOverDiscs</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

Finally, we jump to the next game state.
<pre>
// Then, go to the next state
return NextPlayer::class;
</pre>

To make the statistics work, we have to initialize them in <code>stats.json</code>:

<pre>
{
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
</pre>

A last thing to do on the server side is to activate the next player when we enter the <code>NextPlayer</code> game state (in the <code>modules/php/States/NextPlayer.php</code> file):

Add `const ST_END_GAME = 99;` at the top of the file, then add:

<pre>
function onEnteringState(): void
{
// Active next player
$player_id = intval($this->game->activeNextPlayer());

// Check if both player has at least 1 discs, and if there are free squares to play
$player_to_discs = $this->game->getCollectionFromDb( "SELECT board_player, COUNT( board_x )
FROM board
GROUP BY board_player", true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
return ST_END_GAME;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
return ST_END_GAME;
}

// Can this player play?

$possibleMoves = $this->game->getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = (int)$this->game->getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( $this->game->getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
return ST_END_GAME;
}
else
{
// => pass his turn
return NextPlayer::class;
}
}
else
{
// This player can play. Give him some extra time
$this->game->giveExtraTime( $player_id );
return PlayDisc::class;
}
}
</pre>

Now, when we play a token, the rules are checked and the token appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

==Make the move appear automatically==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our <code>setupNotifications</code> method in <code>modules/js/Game.js</code>, we tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

<pre>
setupNotifications() {
console.log( 'notifications subscriptions setup' );

// automatically listen to the notifications, based on the `notif_xxx` function on this class.
this.bga.notifications.setupPromiseNotifications();
}
</pre>

We will associate each of our 3 notifications with a method prefixed with <code>notif_</code>.

Let's have a look now on the <code>playDisc</code> notification handler method:<pre>
async notif_playDisc(args) {
// Remove current possible moves (makes the board more clear)
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

await this.addDiscOnBoard( args.x, args.y, args.player_id );
}
</pre>

No surprise here, we re-used some existing stuff to:
*Remove the highlighted squares.
* Add a new disc on board, coming from player panel. That's where the async await part of <code>addDiscOnBoard</code> becomes useful.

<div style="outline: 3px solid #3178C6; padding: 5px;margin: 5px;"><span style="background: #3178C6; color: white; margin-right: 5px;">TS</span>In the same way we added the state args in the types.d.ts, add the following to types.d.ts :
<pre>
interface NotifPlayDiscArgs {
player_id: number;
x: number;
y: number;
}
</pre>

And the function signature becomes:
<pre>
async notif_playDisc(args: NotifPlayDiscArgs) {
</pre>
</div>

Now, here's the method that handles the <code>turnOverDiscs</code> notification:

<pre>
async animateTurnOverDisc(disc, targetColor) {
const squareDiv = document.getElementById(`square_${disc.x}_${disc.y}`);
const discDiv = document.getElementById(`disc_${disc.x}_${disc.y}`);

squareDiv.classList.add('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation to finish

discDiv.dataset.color = targetColor;

const parallelAnimations = [{
keyframes: [ // flip the disc
{ transform: `rotateY(180deg)` },
{ transform: `rotateY(0deg)` },
]
}, {
keyframes: [ // lift the disc
{ transform: `translate(0, -12px) scale(1.2)`, offset: 0.5 },
]
}];

await this.animationManager.slideAndAttach(discDiv, squareDiv, { duration: 1000, parallelAnimations });

squareDiv.classList.remove('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation removal to finish
}

async notif_turnOverDiscs(args) {
// Get the color of the player who is returning the discs
const targetColor = this.gamedatas.players[ args.player_id ].color;

// wait for the animations of all turned discs to be over before considering the notif done
await Promise.all(
args.turnedOver.map(disc =>
this.animateTurnOverDisc(disc, targetColor)
)
);
}
</pre>

The list of the discs to be turned over has been made available by our server side code in <code>args.turnedOver</code> (see previous paragraph). We loop through all these discs, and trigger a single disc animation using <code>animateTurnOverDisc</code>. This function creates a complex animation using [[BgaAnimations]] for the disc in parameter.

We create a chain of 3 animations using await to make the square highlight, then flip the token, then remove the square highlight.

==Implement the zombie mode ==
When a player leave the table, a Zombie (bot) will play for the leaver, so the table can continue. For that, we write code in the zombieTurn function.

to learn more about the Zombie mode, read [[Zombie Mode]]

Add this at the end of your PlayDisc.php file :
<pre>
function zombie(int $playerId) {
// Zombie level 1
$possibleMoves = $this->game->boardManager->getPossibleMoves($playerId);
// transform the 2 dimensional array into a flat array of possible [$x, $y]
$possibleMovesArray = [];
foreach($possibleMoves as $x => $ys) {
foreach($ys as $y => $valid) {
$possibleMovesArray[] = [$x, $y];
}
}

$zombieChoice = $this->getRandomZombieChoice($possibleMovesArray);
return $this->actPlayDisc($zombieChoice[0], $zombieChoice[1], $playerId);
}
</pre>

And that's it ! Everytime a leaver should be playing, the Zombie will random play one of the possible moves, and the remaining player will be able to play the next move.

== Add a debug function to help up test the code==
Add this at the end of your Game.php file :
<pre>

function debug_playAutomatically(int $moves = 50) {
$this->bga->debug->playUntil(fn(int $count) => $count === $moves);
}

function debug_playToEndGame() {
$this->debug_playAutomatically(64); // reversi max moves is under 64 for the standard size board
}
</pre>
This function plays automatically until we reach the end of the game. The functions starting with "debug_" can be triggered in the Studio with a special menu.
It uses the tool <code>$this->debug->playUntil</code> that will trigger zombie actions, but you could put any code in the debug function for the tests you need.

Start a new game, click on the Bug icon on the top left then "playToEndGame". You should see the game randomly playing until it reaches the end game, so it helps you check the animations, and you can see if the final scoring is also working as expected. This example will allow us to easily test the Zombie code, as it will play as a Zombie for all players until the end of the game. It's also an easy way to see if end score computation is working as expected!

You can create as many debug function as you like!

==Optional: add unit tests==
Follow the instruction on https://en.doc.boardgamearena.com/Testing_by_developer#PHP to setup phpunit and create the first Reversi unit tests that are given as examples there.

Running <code>phpunit</code>, it should be 4/4 OK! And we have a good hint the case of the full board should be handled OK without actually completing a game :)

==After the tutorial==
You might want to check another tutorial, or start working on your first real project !

[[Create a game in BGA Studio: Complete Walkthrough]]
[[Category:Studio]]

BGA Studio Guidelines

2026-05-23T01:15:59Z

Victoria La: /* A.4 Popups */

= BGA Studio Guidelines (UX/UI) =

This page covers UX guidelines for games on Board Game Arena. Read the [[Media:Guidelines UX new compressed.pdf|official PDF]] or [https://bga.li/mRdx bga.li/mRdx] first. This page is an unofficial summary.

Goal: most games should be instantly playable on any device — desktop at midnight or phone at lunch.

Use this page to validate UX before switching your game from '''ALPHA → BETA → RELEASE'''.

== A — Layouts ==

=== A.1 Layout arrangement ===

Game should fit a square ratio and show everything the active player needs. Use vertical scroll for secondary info (other players' progress, secondary boards).

'''✔️ Do'''
* Center the play area on all devices.
* Leave a "no action" margin around the board (deselect, scroll on mobile).
* Use HTML anchors to jump between distant sections.
* Use spacers / transparent whiteblocks to group pieces clearly.
* Keep score, turn order, and objectives '''accessible''' (button/tab/panel), not always visible.
* Tuck rare abilities into tooltips.

'''❌ Don't'''
* Do not hide game components behind popups — you should see everything you'd see on a real table.
* Do not place "always accessible" info permanently on the player panels.
* Do not add in-game logos or branding that isn't part of the actual game.
* Do not scatter related info (e.g. resources) across three corners.

Note: '''Layout mantra:''' Central = shared actions. Top/Bottom = global info. Panels = private resources.

[[File:Ux-01-layouts.jpg]]

=== A.2 Action Bar ===

The Action Bar always shows the current state: turn in progress, who we're waiting for, or what the player can do.

[[File:Ux-03-action-bar-mock.jpg]]

'''✔️ Do'''
* Center '''main awaited actions''' (Play card, End turn, Confirm move).
* Place secondary/greyed-out actions next to them.
* Put '''cancel / undo / remove''' on the right, visually separated from forward actions.
* Use the Action Bar for: actions targeting another player, Pass/End turn/time-related actions, auction phases, and small resource exchanges without dedicated board space.
* Keep it to '''max 4 buttons + context''' so it doesn't overflow on mobile.

'''❌ Don't'''
* Do not replace board-component actions with Action Bar buttons — players should act on the board like in real life.
* Do not stick custom buttons next to BGA's built-in buttons (replay controls, etc.).
* Do not let cancel actions visually compete with main actions.
* Do not show "Round in progress" text inside the bar — display it on the table or as flavor text of the current action.

''Example: Wingspan shows the current round as flavor text under the action bar.''

[[File:Ux-02-action-bar-examples.jpg]]

→ See [[#C.3 Button colors and styling|C.3]] for button colors.

=== A.3 Player panels ===

Player panels let anyone glance at: who's playing, color, score, turn order, and resources gained.

'''✔️ Do'''
* Keep panels compact — a 4-player game on mobile must not occupy more than '''¼ of the screen'''.
* Offer HTML anchor shortcuts to jump to a player's main components.

'''❌ Don't'''
* Do not put settings, titles, round numbers, or other redundant info in panels.
* Do not put always-accessible info (score, objectives) ''only'' on player panels.

[[File:Ux-04-player-panel.jpg]]

=== A.4 Popups ===

'''✔️ Do'''
* Reserve automatic popups for '''tutorials only'''.
* Make any required popup skippable on click/touch/timer.
* Use the game wiki for rules, hints, scoring tips, helpers.
[[File:Ux-06-wiki.jpg]]

'''❌ Don't'''
* Do not block game flow with popups (forbidden).
* Do not use popups mid-game — only allowed for between-round/stage scoring.

Example: area around popup clickable - should be used to close it

[[File:Ux-05-popup.jpg]]

→ See [[#B.1 Tooltips|B.1]] for non-blocking alternatives.

=== A.5 Clarity & Zoom ===

Use vertical space and good layout instead of zoom controls.

'''✔️ Do'''
* Design so the core game is fully playable at '''100% scale'''.
* Trust browser zoom: Ctrl+wheel on desktop, pinch on mobile.

'''❌ Don't'''
* Do not add zoom buttons unless absolutely necessary (large secondary boards, very text-heavy cards like Ticket to Ride).

'''If you must add zoom buttons:'''
* '''+''' (plus): zoom in
* '''–''' (minus): zoom out
* 🏠 Home: reset to default

== B — Usability ==

=== B.1 Tooltips ===

Tooltips add insight, not duplication.

'''✔️ Do'''
* Add extra detail beyond what's on screen (translatable text, hints about when to use).
* Use them to zoom into small text/icons on large game boards.
* Close tooltips when the user taps away on mobile.

'''❌ Don't'''
* Do not show the same info twice the same way.
* Do not add a tooltip that's just a zoomed-in copy of an already-visible card — that's a sign your components are mis-sized.

''Example: Ticket to Ride hover tooltips name cards/decks without distraction.''

[[File:Ux-07-tooltip-1.jpg]]

''Example: Altered shows minimal default info, with full detail on hover.''

[[File:Ux-08-tooltip-2.jpg]]

=== B.2 Forbidden actions ===

'''✔️ Do'''
* Grey out / disable actions that exist but aren't currently available.

'''❌ Don't'''
* Do not show disabled buttons for actions that are never relevant in the current context — just hide them.

=== B.3 Undo, Reset, Restart ===

BGA philosophy: fast, fluid, intuitive. Use these controls sparingly.

'''✔️ Do'''
* Use '''Confirm''' buttons for impactful, irreversible actions (end turn, discard, commit resources).
* Prefer timed confirmation (5–8s) over undo.
* Offer one '''Restart Turn''' for the whole turn when rules allow, not per-micro-action undo.
* Allow "Undo last move" only when a turn has '''more than 2 actions'''.

'''❌ Don't'''
* Do not add an Undo button for every action — multiplies validation steps, slows the game.
* Do not layer Undo on top of Reset on top of Confirm — over-validation.
* Do not use Undo to paper over misclicks — fix the layout instead (bigger targets, clearer highlights).

== C — Design ==

=== C.1 Typography & translations ===

Clarity beats style.

'''✔️ Do'''
* Use the default BGA font.
* Use clean sans-serif if you must change.
* Maintain good line spacing.
* Make all text translatable via BGA's translation system.
* Support LTR ''and'' RTL languages — test alignment & mirroring.
* Ensure your font supports accents/diacritics (é, ñ, ü).
* Meet '''WCAG AA''' contrast.
* Test on a phone — what's readable on a 27" monitor may not be on mobile.

'''❌ Don't'''
* Do not use decorative or themed fonts (hard to read, licensing risk, missing glyphs).
* Do not mix multiple fonts for "theme."
* Do not embed text directly into images without alt-text.

=== C.2 Highlights & Glowing auras ===

Players should never wonder "what do I click?"

'''✔️ Do'''
* Highlight valid options so the awaited action is obvious.
* Show consequences visually before the player commits.

''Example of highlighting valid options on the table.''

[[File:Ux-09-active-element.jpg]]

=== C.3 Button colors and styling ===

Button colors are a shared language across BGA. Mandatory for consistency.

{| class="wikitable"
! Color !! Meaning !! <code>statusBar.addActionButton</code>
|-
| 🔵 '''Blue''' || Advance, confirm, move forward || <code>primary</code>
|-
| 🔴 '''Red''' || Cancel, undo, stop, exit || <code>alert</code>
|-
| ⚪ '''White / Transparent''' || Optional/side actions || <code>secondary</code>
|-
| ⚫ '''Grey''' || Disabled, completed, unavailable || (disabled state of any of the above)
|}

'''✔️ Do'''
* Display usernames in their assigned player color.
* Outline player-color text so it stays visible (e.g. yellow on white).
* Test player colors on both light and dark backgrounds.
* Take any extra colors from '''game components''' (cards, tiles, tokens), not UI buttons.

'''❌ Don't'''
* Do not reassign blue/red/grey for game-specific meaning.
* Do not tint UI buttons to match the game's theme.

Note: Think of button colors as '''traffic lights''': blue = go, red = stop, grey = unavailable.

=== C.4 Sizing & responsiveness ===

'''✔️ Do'''
* Keep the main play area centered on every device.
* Use fluid layouts that expand/contract to fit available space.
* Leave margins around the board (prevents mobile misclicks).
* On desktop/tablet: show the entire board when possible.
* On mobile (vertical): stack secondary elements ''below'' the main action zone.
* Make everything readable and usable at 100% scale.
* Add HTML anchors / jump-links for vertical layouts.

'''❌ Don't'''
* Do not use fixed-width designs.
* Do not rely on zoom for legibility.
* Do not let layout break when players zoom in/out.
* Do not make any interactive element smaller than '''32×32px''' (see [[#E.3 Tap targets|E.3]]).

''Reference implementation:'' [https://thoun.github.io/bga-jump-to/demo/index.html bga-jump-to demo]

=== C.5 Background & extras ===

The background is the table surface your game sits on.

'''✔️ Do'''
* Use thematic, modern backgrounds (subtle playmat look).
* Add slight texture or pattern.
* Apply a touch of blur so components remain the visual focus.
* Prioritize contrast against the game's components.

'''❌ Don't'''
* Do not use pure flat colors.
* Do not use sharp, busy, detailed backgrounds that compete with the game.
* Do not let the background reduce component visibility.

== D — Feedback ==

=== D.1 Errors & invalid actions ===

Silence is never acceptable. Every failed action must say why.

'''✔️ Do'''
* Use a short shake, grey-out, or tooltip on failure.
* Show concise plain-text errors: ''"You don't have enough resources."''
* Pair color with icons or text (don't rely on red alone).

'''❌ Don't'''
* Do not leave the player guessing.
* Do not use color alone — colorblind users won't see it.

=== D.2 Game Logs ===

Logs are the narration of the match. Critical for asynchronous games.

'''✔️ Do'''
* Log every major action: card plays, moves, resource changes, eliminations.
* Always say '''who''' acted and '''what''' changed.
* Use icons, colors, formatting for fast scanning.
* Provide alt-text for graphic components inside logs.
* Group small simultaneous actions into a one-liner.
* Log automated/forced actions too.

'''❌ Don't'''
* Do not write walls of text or use oversized images that break log flow.
* Do not hide ''who'' did the action.

''Good:''
* "Marianna placed [red tile] on [central board] (+2 points)."
* "Alex drew 2 [train cards]."

''Bad:''
* "+2 points"
* "Card drawn"

=== D.3 Animation ===

Animations explain '''what moved, where it went, why it matters'''.

'''✔️ Do'''
* Use animations for: cards entering a hand, tokens moving, score count-up.
* Keep regular animations at '''0.5s''', max '''0.8s'''.
* Batch repetitive updates (don't show 50 tiny +1 animations).

'''❌ Don't'''
* Do not animate trivial updates one by one.
* Do not use looping, bouncing, or glowing animations as decoration.

→ See [https://en.doc.boardgamearena.com/BgaAnimations BGA animation library].

=== D.4 Sound effects ===

Sound is a bonus, not a requirement.

'''✔️ Do'''
* Keep volume '''below''' the BGA default.
* Keep sounds short, sharp, purposeful.
* Always pair sound with a visual cue.

'''❌ Don't'''
* Do not add long looping soundtracks.
* Do not let any action be communicated by '''sound only'''.
* Do not surprise players with loud audio.

== E — Accessibility ==

=== E.1 Design for all ===

'''✔️ Do'''
* Pair colors with icons, textures, or shapes.
* Meet contrast ratio '''4.5:1''' minimum.
* Label every button, icon, and interactive element (screen readers).
* Use bold shapes, clear outlines, strong contrast to differentiate pieces.

'''❌ Don't'''
* Do not rely on color alone.
* Do not use flashing or rapidly alternating visuals.
* Do not depend on fine details or subtle shading to differentiate components.

=== E.2 Colorblind-safe design ===

'''✔️ Do'''
* Add unique shapes/symbols/outlines per pawn or token color.
* Place small icons in card corners (or patterns) so suits are recognizable without hue.
* Meet '''WCAG AA''' for text and icons.
* Outline player-color names so yellow doesn't vanish on white.

'''❌ Don't'''
* Do not assume players perceive color differences.

=== E.3 Tap targets ===

'''✔️ Do'''
* Minimum '''32×32px''' for any interactive element.
* Aim for '''40–44px''' (greatly reduces mis-taps).
* Leave spacing between buttons, tokens, cards.
* Group many options into expandable menus or secondary panels.
* When space runs out, add scrolling — don't shrink components.

'''❌ Don't'''
* Do not cram small icons into tight clusters.
* Do not shrink components below the minimum to fit.

=== E.4 Settings & customization ===

'''✔️ Do'''
* Put all game settings in BGA's '''standard settings menu'''.
* Reuse existing BGA controls.
* Offer per-game options only where relevant: animation speed, tooltip detail, sound on/off.

'''❌ Don't'''
* Do not build custom settings UI (the platform is phasing those out).
* Do not duplicate controls already available globally.

== F — Technical ==

=== F.1 Endgame & Replays ===

'''✔️ Do'''
* Make replays flow without interruption.
* Keep animations skippable and playable at minimum speed.
* Keep logs and highlights in sync with each replayed action.
* Match the scoring pay-off to game length — long games deserve a longer reveal.
* Use synchronous notifications per scoring step and <code>this.displayScoring</code> for points animations.

'''❌ Don't'''
* Do not put blocking popups in replays.
* Do not drop the final score instantly at the end of a long game.

=== F.2 Refresh & Continuity ===

A refresh should feel invisible.

'''✔️ Do'''
* Restore the exact game state after refresh (no missing/corrupted info).
* Restore temporary UI: whose turn it is, pending actions, selected components.
* Treat the server as the source of truth for all critical state.
* Expect disconnect/reconnect as normal — BGA may do it at any time.

'''❌ Don't'''
* Do not store critical state in client-only memory.
* Do not rely on session continuity hacks.

=== F.3 Error handling ===

'''✔️ Do'''
* Handle disconnects and dropped actions without breaking flow.
* Show players short, friendly messages explaining what went wrong.
* Log precise error details to the developer console.
* Isolate the error to the affected action.

'''❌ Don't'''
* Do not crash the game on invalid input.
* Do not expose raw server logs or stack traces to players.
* Do not block the whole table because of one failed request.

== Pre-release Checklist ==

''Version 1.0.0 — May 22, 2026''

{| class="wikitable"
! # !! Check
|-
| 1 || Layout centers and scales on all devices.
|-
| 2 || Action Bar ≤ 4 buttons, never replaces components.
|-
| 3 || Tooltips: clear, translatable, useful.
|-
| 4 || Buttons follow BGA standards (blue = forward, red = cancel).
|-
| 5 || No blocking popups mid-game.
|-
| 6 || Animations: quick, smooth, informative.
|-
| 7 || All tap/click targets ≥ 32px.
|-
| 8 || Colorblind-safe icons in place.
|-
| 9 || Endgame shows breakdown + replay option.
|-
| 10 || Game state restores cleanly after refresh.
|}

== Closing thoughts ==

* '''Alpha:''' gather usability feedback.
* '''Beta:''' listen to the crowd — confusion spots = redesign spots.
* '''Iterate:''' small UX tweaks = big retention gains.
* '''Watch metrics:''' if players stall at a phase, that's your design flag.

Play other BGA games with similar mechanics — get inspired, challenge your assumptions, and treat UX as a key part of design, not an afterthought.

= BGA Studio Guidelines (Source Code) =
Make your code as easy to read and understand as possible: clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

== Front (JS) code ==

=== Generated code ===
Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

=== Templates ===
Use of .tpl file and view.php is deprecated and forbidden for new projects.

== Back (PHP) code ==
Game name and option names should be Capitalized.

=== Framework functions ===

===== Undocumented functions =====
Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

==== Function override ====
Do not override framework functions. Use a wrapper instead.

'''Bad :'''

<pre>
public function getPlayerNameById($player_id) { // same name as the framework function = override
if ($player_id == 0) {
return 'Automata';
} else {
return parent::getPlayerNameById($player_id);
}
}
</pre>

'''Better :'''
<pre>
public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
if ($player_id == 0) {
return 'Automata';
} else {
return $this->getPlayerNameById($player_id);
}
}
</pre>

==== State functions ====
States functions should be prefixed "st"

Args functions should be prefixed "arg"

Action functions should be prefixed "act"

=== Namespacing ===
The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <code><mygame>/PowerCard/PowerCardManager.php</code> and start like this :

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\<mygame>\PowerCard;
class PowerCardManager {
</pre>

=== Other ===
.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function must check any input. To avoid code duplication, they can use the arg function.

''Example :''

<pre>
$args = $this->argPlayCards();
if (!in_array($cardId, $args['selectableCardsIds'])) { throw new \BgaUserException(...); }
</pre>

Don’t use `@` to ignore the errors of a function call.

[[Category:Studio]]

BGA Studio Guidelines

2026-05-23T01:13:52Z

Victoria La: /* A.4 Popups */

= BGA Studio Guidelines (UX/UI) =

This page covers UX guidelines for games on Board Game Arena. Read the [[Media:Guidelines UX new compressed.pdf|official PDF]] or [https://bga.li/mRdx bga.li/mRdx] first. This page is an unofficial summary.

Goal: most games should be instantly playable on any device — desktop at midnight or phone at lunch.

Use this page to validate UX before switching your game from '''ALPHA → BETA → RELEASE'''.

== A — Layouts ==

=== A.1 Layout arrangement ===

Game should fit a square ratio and show everything the active player needs. Use vertical scroll for secondary info (other players' progress, secondary boards).

'''✔️ Do'''
* Center the play area on all devices.
* Leave a "no action" margin around the board (deselect, scroll on mobile).
* Use HTML anchors to jump between distant sections.
* Use spacers / transparent whiteblocks to group pieces clearly.
* Keep score, turn order, and objectives '''accessible''' (button/tab/panel), not always visible.
* Tuck rare abilities into tooltips.

'''❌ Don't'''
* Do not hide game components behind popups — you should see everything you'd see on a real table.
* Do not place "always accessible" info permanently on the player panels.
* Do not add in-game logos or branding that isn't part of the actual game.
* Do not scatter related info (e.g. resources) across three corners.

Note: '''Layout mantra:''' Central = shared actions. Top/Bottom = global info. Panels = private resources.

[[File:Ux-01-layouts.jpg]]

=== A.2 Action Bar ===

The Action Bar always shows the current state: turn in progress, who we're waiting for, or what the player can do.

[[File:Ux-03-action-bar-mock.jpg]]

'''✔️ Do'''
* Center '''main awaited actions''' (Play card, End turn, Confirm move).
* Place secondary/greyed-out actions next to them.
* Put '''cancel / undo / remove''' on the right, visually separated from forward actions.
* Use the Action Bar for: actions targeting another player, Pass/End turn/time-related actions, auction phases, and small resource exchanges without dedicated board space.
* Keep it to '''max 4 buttons + context''' so it doesn't overflow on mobile.

'''❌ Don't'''
* Do not replace board-component actions with Action Bar buttons — players should act on the board like in real life.
* Do not stick custom buttons next to BGA's built-in buttons (replay controls, etc.).
* Do not let cancel actions visually compete with main actions.
* Do not show "Round in progress" text inside the bar — display it on the table or as flavor text of the current action.

''Example: Wingspan shows the current round as flavor text under the action bar.''

[[File:Ux-02-action-bar-examples.jpg]]

→ See [[#C.3 Button colors and styling|C.3]] for button colors.

=== A.3 Player panels ===

Player panels let anyone glance at: who's playing, color, score, turn order, and resources gained.

'''✔️ Do'''
* Keep panels compact — a 4-player game on mobile must not occupy more than '''¼ of the screen'''.
* Offer HTML anchor shortcuts to jump to a player's main components.

'''❌ Don't'''
* Do not put settings, titles, round numbers, or other redundant info in panels.
* Do not put always-accessible info (score, objectives) ''only'' on player panels.

[[File:Ux-04-player-panel.jpg]]

=== A.4 Popups ===

'''✔️ Do'''
* Reserve automatic popups for '''tutorials only'''.
* Make any required popup skippable on click/touch/timer.
* Use the game wiki for rules, hints, scoring tips, helpers.
[[File:Ux-06-wiki.jpg]]

'''❌ Don't'''
* Do not block game flow with popups (forbidden).
* Do not use popups mid-game — only allowed for between-round/stage scoring.

[[File:Ux-05-popup.jpg]]

→ See [[#B.1 Tooltips|B.1]] for non-blocking alternatives.

=== A.5 Clarity & Zoom ===

Use vertical space and good layout instead of zoom controls.

'''✔️ Do'''
* Design so the core game is fully playable at '''100% scale'''.
* Trust browser zoom: Ctrl+wheel on desktop, pinch on mobile.

'''❌ Don't'''
* Do not add zoom buttons unless absolutely necessary (large secondary boards, very text-heavy cards like Ticket to Ride).

'''If you must add zoom buttons:'''
* '''+''' (plus): zoom in
* '''–''' (minus): zoom out
* 🏠 Home: reset to default

== B — Usability ==

=== B.1 Tooltips ===

Tooltips add insight, not duplication.

'''✔️ Do'''
* Add extra detail beyond what's on screen (translatable text, hints about when to use).
* Use them to zoom into small text/icons on large game boards.
* Close tooltips when the user taps away on mobile.

'''❌ Don't'''
* Do not show the same info twice the same way.
* Do not add a tooltip that's just a zoomed-in copy of an already-visible card — that's a sign your components are mis-sized.

''Example: Ticket to Ride hover tooltips name cards/decks without distraction.''

[[File:Ux-07-tooltip-1.jpg]]

''Example: Altered shows minimal default info, with full detail on hover.''

[[File:Ux-08-tooltip-2.jpg]]

=== B.2 Forbidden actions ===

'''✔️ Do'''
* Grey out / disable actions that exist but aren't currently available.

'''❌ Don't'''
* Do not show disabled buttons for actions that are never relevant in the current context — just hide them.

=== B.3 Undo, Reset, Restart ===

BGA philosophy: fast, fluid, intuitive. Use these controls sparingly.

'''✔️ Do'''
* Use '''Confirm''' buttons for impactful, irreversible actions (end turn, discard, commit resources).
* Prefer timed confirmation (5–8s) over undo.
* Offer one '''Restart Turn''' for the whole turn when rules allow, not per-micro-action undo.
* Allow "Undo last move" only when a turn has '''more than 2 actions'''.

'''❌ Don't'''
* Do not add an Undo button for every action — multiplies validation steps, slows the game.
* Do not layer Undo on top of Reset on top of Confirm — over-validation.
* Do not use Undo to paper over misclicks — fix the layout instead (bigger targets, clearer highlights).

== C — Design ==

=== C.1 Typography & translations ===

Clarity beats style.

'''✔️ Do'''
* Use the default BGA font.
* Use clean sans-serif if you must change.
* Maintain good line spacing.
* Make all text translatable via BGA's translation system.
* Support LTR ''and'' RTL languages — test alignment & mirroring.
* Ensure your font supports accents/diacritics (é, ñ, ü).
* Meet '''WCAG AA''' contrast.
* Test on a phone — what's readable on a 27" monitor may not be on mobile.

'''❌ Don't'''
* Do not use decorative or themed fonts (hard to read, licensing risk, missing glyphs).
* Do not mix multiple fonts for "theme."
* Do not embed text directly into images without alt-text.

=== C.2 Highlights & Glowing auras ===

Players should never wonder "what do I click?"

'''✔️ Do'''
* Highlight valid options so the awaited action is obvious.
* Show consequences visually before the player commits.

''Example of highlighting valid options on the table.''

[[File:Ux-09-active-element.jpg]]

=== C.3 Button colors and styling ===

Button colors are a shared language across BGA. Mandatory for consistency.

{| class="wikitable"
! Color !! Meaning !! <code>statusBar.addActionButton</code>
|-
| 🔵 '''Blue''' || Advance, confirm, move forward || <code>primary</code>
|-
| 🔴 '''Red''' || Cancel, undo, stop, exit || <code>alert</code>
|-
| ⚪ '''White / Transparent''' || Optional/side actions || <code>secondary</code>
|-
| ⚫ '''Grey''' || Disabled, completed, unavailable || (disabled state of any of the above)
|}

'''✔️ Do'''
* Display usernames in their assigned player color.
* Outline player-color text so it stays visible (e.g. yellow on white).
* Test player colors on both light and dark backgrounds.
* Take any extra colors from '''game components''' (cards, tiles, tokens), not UI buttons.

'''❌ Don't'''
* Do not reassign blue/red/grey for game-specific meaning.
* Do not tint UI buttons to match the game's theme.

Note: Think of button colors as '''traffic lights''': blue = go, red = stop, grey = unavailable.

=== C.4 Sizing & responsiveness ===

'''✔️ Do'''
* Keep the main play area centered on every device.
* Use fluid layouts that expand/contract to fit available space.
* Leave margins around the board (prevents mobile misclicks).
* On desktop/tablet: show the entire board when possible.
* On mobile (vertical): stack secondary elements ''below'' the main action zone.
* Make everything readable and usable at 100% scale.
* Add HTML anchors / jump-links for vertical layouts.

'''❌ Don't'''
* Do not use fixed-width designs.
* Do not rely on zoom for legibility.
* Do not let layout break when players zoom in/out.
* Do not make any interactive element smaller than '''32×32px''' (see [[#E.3 Tap targets|E.3]]).

''Reference implementation:'' [https://thoun.github.io/bga-jump-to/demo/index.html bga-jump-to demo]

=== C.5 Background & extras ===

The background is the table surface your game sits on.

'''✔️ Do'''
* Use thematic, modern backgrounds (subtle playmat look).
* Add slight texture or pattern.
* Apply a touch of blur so components remain the visual focus.
* Prioritize contrast against the game's components.

'''❌ Don't'''
* Do not use pure flat colors.
* Do not use sharp, busy, detailed backgrounds that compete with the game.
* Do not let the background reduce component visibility.

== D — Feedback ==

=== D.1 Errors & invalid actions ===

Silence is never acceptable. Every failed action must say why.

'''✔️ Do'''
* Use a short shake, grey-out, or tooltip on failure.
* Show concise plain-text errors: ''"You don't have enough resources."''
* Pair color with icons or text (don't rely on red alone).

'''❌ Don't'''
* Do not leave the player guessing.
* Do not use color alone — colorblind users won't see it.

=== D.2 Game Logs ===

Logs are the narration of the match. Critical for asynchronous games.

'''✔️ Do'''
* Log every major action: card plays, moves, resource changes, eliminations.
* Always say '''who''' acted and '''what''' changed.
* Use icons, colors, formatting for fast scanning.
* Provide alt-text for graphic components inside logs.
* Group small simultaneous actions into a one-liner.
* Log automated/forced actions too.

'''❌ Don't'''
* Do not write walls of text or use oversized images that break log flow.
* Do not hide ''who'' did the action.

''Good:''
* "Marianna placed [red tile] on [central board] (+2 points)."
* "Alex drew 2 [train cards]."

''Bad:''
* "+2 points"
* "Card drawn"

=== D.3 Animation ===

Animations explain '''what moved, where it went, why it matters'''.

'''✔️ Do'''
* Use animations for: cards entering a hand, tokens moving, score count-up.
* Keep regular animations at '''0.5s''', max '''0.8s'''.
* Batch repetitive updates (don't show 50 tiny +1 animations).

'''❌ Don't'''
* Do not animate trivial updates one by one.
* Do not use looping, bouncing, or glowing animations as decoration.

→ See [https://en.doc.boardgamearena.com/BgaAnimations BGA animation library].

=== D.4 Sound effects ===

Sound is a bonus, not a requirement.

'''✔️ Do'''
* Keep volume '''below''' the BGA default.
* Keep sounds short, sharp, purposeful.
* Always pair sound with a visual cue.

'''❌ Don't'''
* Do not add long looping soundtracks.
* Do not let any action be communicated by '''sound only'''.
* Do not surprise players with loud audio.

== E — Accessibility ==

=== E.1 Design for all ===

'''✔️ Do'''
* Pair colors with icons, textures, or shapes.
* Meet contrast ratio '''4.5:1''' minimum.
* Label every button, icon, and interactive element (screen readers).
* Use bold shapes, clear outlines, strong contrast to differentiate pieces.

'''❌ Don't'''
* Do not rely on color alone.
* Do not use flashing or rapidly alternating visuals.
* Do not depend on fine details or subtle shading to differentiate components.

=== E.2 Colorblind-safe design ===

'''✔️ Do'''
* Add unique shapes/symbols/outlines per pawn or token color.
* Place small icons in card corners (or patterns) so suits are recognizable without hue.
* Meet '''WCAG AA''' for text and icons.
* Outline player-color names so yellow doesn't vanish on white.

'''❌ Don't'''
* Do not assume players perceive color differences.

=== E.3 Tap targets ===

'''✔️ Do'''
* Minimum '''32×32px''' for any interactive element.
* Aim for '''40–44px''' (greatly reduces mis-taps).
* Leave spacing between buttons, tokens, cards.
* Group many options into expandable menus or secondary panels.
* When space runs out, add scrolling — don't shrink components.

'''❌ Don't'''
* Do not cram small icons into tight clusters.
* Do not shrink components below the minimum to fit.

=== E.4 Settings & customization ===

'''✔️ Do'''
* Put all game settings in BGA's '''standard settings menu'''.
* Reuse existing BGA controls.
* Offer per-game options only where relevant: animation speed, tooltip detail, sound on/off.

'''❌ Don't'''
* Do not build custom settings UI (the platform is phasing those out).
* Do not duplicate controls already available globally.

== F — Technical ==

=== F.1 Endgame & Replays ===

'''✔️ Do'''
* Make replays flow without interruption.
* Keep animations skippable and playable at minimum speed.
* Keep logs and highlights in sync with each replayed action.
* Match the scoring pay-off to game length — long games deserve a longer reveal.
* Use synchronous notifications per scoring step and <code>this.displayScoring</code> for points animations.

'''❌ Don't'''
* Do not put blocking popups in replays.
* Do not drop the final score instantly at the end of a long game.

=== F.2 Refresh & Continuity ===

A refresh should feel invisible.

'''✔️ Do'''
* Restore the exact game state after refresh (no missing/corrupted info).
* Restore temporary UI: whose turn it is, pending actions, selected components.
* Treat the server as the source of truth for all critical state.
* Expect disconnect/reconnect as normal — BGA may do it at any time.

'''❌ Don't'''
* Do not store critical state in client-only memory.
* Do not rely on session continuity hacks.

=== F.3 Error handling ===

'''✔️ Do'''
* Handle disconnects and dropped actions without breaking flow.
* Show players short, friendly messages explaining what went wrong.
* Log precise error details to the developer console.
* Isolate the error to the affected action.

'''❌ Don't'''
* Do not crash the game on invalid input.
* Do not expose raw server logs or stack traces to players.
* Do not block the whole table because of one failed request.

== Pre-release Checklist ==

''Version 1.0.0 — May 22, 2026''

{| class="wikitable"
! # !! Check
|-
| 1 || Layout centers and scales on all devices.
|-
| 2 || Action Bar ≤ 4 buttons, never replaces components.
|-
| 3 || Tooltips: clear, translatable, useful.
|-
| 4 || Buttons follow BGA standards (blue = forward, red = cancel).
|-
| 5 || No blocking popups mid-game.
|-
| 6 || Animations: quick, smooth, informative.
|-
| 7 || All tap/click targets ≥ 32px.
|-
| 8 || Colorblind-safe icons in place.
|-
| 9 || Endgame shows breakdown + replay option.
|-
| 10 || Game state restores cleanly after refresh.
|}

== Closing thoughts ==

* '''Alpha:''' gather usability feedback.
* '''Beta:''' listen to the crowd — confusion spots = redesign spots.
* '''Iterate:''' small UX tweaks = big retention gains.
* '''Watch metrics:''' if players stall at a phase, that's your design flag.

Play other BGA games with similar mechanics — get inspired, challenge your assumptions, and treat UX as a key part of design, not an afterthought.

= BGA Studio Guidelines (Source Code) =
Make your code as easy to read and understand as possible: clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

== Front (JS) code ==

=== Generated code ===
Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

=== Templates ===
Use of .tpl file and view.php is deprecated and forbidden for new projects.

== Back (PHP) code ==
Game name and option names should be Capitalized.

=== Framework functions ===

===== Undocumented functions =====
Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

==== Function override ====
Do not override framework functions. Use a wrapper instead.

'''Bad :'''

<pre>
public function getPlayerNameById($player_id) { // same name as the framework function = override
if ($player_id == 0) {
return 'Automata';
} else {
return parent::getPlayerNameById($player_id);
}
}
</pre>

'''Better :'''
<pre>
public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
if ($player_id == 0) {
return 'Automata';
} else {
return $this->getPlayerNameById($player_id);
}
}
</pre>

==== State functions ====
States functions should be prefixed "st"

Args functions should be prefixed "arg"

Action functions should be prefixed "act"

=== Namespacing ===
The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <code><mygame>/PowerCard/PowerCardManager.php</code> and start like this :

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\<mygame>\PowerCard;
class PowerCardManager {
</pre>

=== Other ===
.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function must check any input. To avoid code duplication, they can use the arg function.

''Example :''

<pre>
$args = $this->argPlayCards();
if (!in_array($cardId, $args['selectableCardsIds'])) { throw new \BgaUserException(...); }
</pre>

Don’t use `@` to ignore the errors of a function call.

[[Category:Studio]]

File:Ux-06-wiki.jpg

2026-05-23T01:13:44Z

Victoria La:

BGA Studio Guidelines

2026-05-23T01:12:59Z

Victoria La: /* A.4 Popups */

= BGA Studio Guidelines (UX/UI) =

This page covers UX guidelines for games on Board Game Arena. Read the [[Media:Guidelines UX new compressed.pdf|official PDF]] or [https://bga.li/mRdx bga.li/mRdx] first. This page is an unofficial summary.

Goal: most games should be instantly playable on any device — desktop at midnight or phone at lunch.

Use this page to validate UX before switching your game from '''ALPHA → BETA → RELEASE'''.

== A — Layouts ==

=== A.1 Layout arrangement ===

Game should fit a square ratio and show everything the active player needs. Use vertical scroll for secondary info (other players' progress, secondary boards).

'''✔️ Do'''
* Center the play area on all devices.
* Leave a "no action" margin around the board (deselect, scroll on mobile).
* Use HTML anchors to jump between distant sections.
* Use spacers / transparent whiteblocks to group pieces clearly.
* Keep score, turn order, and objectives '''accessible''' (button/tab/panel), not always visible.
* Tuck rare abilities into tooltips.

'''❌ Don't'''
* Do not hide game components behind popups — you should see everything you'd see on a real table.
* Do not place "always accessible" info permanently on the player panels.
* Do not add in-game logos or branding that isn't part of the actual game.
* Do not scatter related info (e.g. resources) across three corners.

Note: '''Layout mantra:''' Central = shared actions. Top/Bottom = global info. Panels = private resources.

[[File:Ux-01-layouts.jpg]]

=== A.2 Action Bar ===

The Action Bar always shows the current state: turn in progress, who we're waiting for, or what the player can do.

[[File:Ux-03-action-bar-mock.jpg]]

'''✔️ Do'''
* Center '''main awaited actions''' (Play card, End turn, Confirm move).
* Place secondary/greyed-out actions next to them.
* Put '''cancel / undo / remove''' on the right, visually separated from forward actions.
* Use the Action Bar for: actions targeting another player, Pass/End turn/time-related actions, auction phases, and small resource exchanges without dedicated board space.
* Keep it to '''max 4 buttons + context''' so it doesn't overflow on mobile.

'''❌ Don't'''
* Do not replace board-component actions with Action Bar buttons — players should act on the board like in real life.
* Do not stick custom buttons next to BGA's built-in buttons (replay controls, etc.).
* Do not let cancel actions visually compete with main actions.
* Do not show "Round in progress" text inside the bar — display it on the table or as flavor text of the current action.

''Example: Wingspan shows the current round as flavor text under the action bar.''

[[File:Ux-02-action-bar-examples.jpg]]

→ See [[#C.3 Button colors and styling|C.3]] for button colors.

=== A.3 Player panels ===

Player panels let anyone glance at: who's playing, color, score, turn order, and resources gained.

'''✔️ Do'''
* Keep panels compact — a 4-player game on mobile must not occupy more than '''¼ of the screen'''.
* Offer HTML anchor shortcuts to jump to a player's main components.

'''❌ Don't'''
* Do not put settings, titles, round numbers, or other redundant info in panels.
* Do not put always-accessible info (score, objectives) ''only'' on player panels.

[[File:Ux-04-player-panel.jpg]]

=== A.4 Popups ===

'''✔️ Do'''
* Reserve automatic popups for '''tutorials only'''.
* Make any required popup skippable on click/touch/timer.
* Use the game wiki for rules, hints, scoring tips, helpers.
[[File:Ux-04-wiki.jpg]]

'''❌ Don't'''
* Do not block game flow with popups (forbidden).
* Do not use popups mid-game — only allowed for between-round/stage scoring.

[[File:Ux-05-popup.jpg]]

→ See [[#B.1 Tooltips|B.1]] for non-blocking alternatives.

=== A.5 Clarity & Zoom ===

Use vertical space and good layout instead of zoom controls.

'''✔️ Do'''
* Design so the core game is fully playable at '''100% scale'''.
* Trust browser zoom: Ctrl+wheel on desktop, pinch on mobile.

'''❌ Don't'''
* Do not add zoom buttons unless absolutely necessary (large secondary boards, very text-heavy cards like Ticket to Ride).

'''If you must add zoom buttons:'''
* '''+''' (plus): zoom in
* '''–''' (minus): zoom out
* 🏠 Home: reset to default

== B — Usability ==

=== B.1 Tooltips ===

Tooltips add insight, not duplication.

'''✔️ Do'''
* Add extra detail beyond what's on screen (translatable text, hints about when to use).
* Use them to zoom into small text/icons on large game boards.
* Close tooltips when the user taps away on mobile.

'''❌ Don't'''
* Do not show the same info twice the same way.
* Do not add a tooltip that's just a zoomed-in copy of an already-visible card — that's a sign your components are mis-sized.

''Example: Ticket to Ride hover tooltips name cards/decks without distraction.''

[[File:Ux-07-tooltip-1.jpg]]

''Example: Altered shows minimal default info, with full detail on hover.''

[[File:Ux-08-tooltip-2.jpg]]

=== B.2 Forbidden actions ===

'''✔️ Do'''
* Grey out / disable actions that exist but aren't currently available.

'''❌ Don't'''
* Do not show disabled buttons for actions that are never relevant in the current context — just hide them.

=== B.3 Undo, Reset, Restart ===

BGA philosophy: fast, fluid, intuitive. Use these controls sparingly.

'''✔️ Do'''
* Use '''Confirm''' buttons for impactful, irreversible actions (end turn, discard, commit resources).
* Prefer timed confirmation (5–8s) over undo.
* Offer one '''Restart Turn''' for the whole turn when rules allow, not per-micro-action undo.
* Allow "Undo last move" only when a turn has '''more than 2 actions'''.

'''❌ Don't'''
* Do not add an Undo button for every action — multiplies validation steps, slows the game.
* Do not layer Undo on top of Reset on top of Confirm — over-validation.
* Do not use Undo to paper over misclicks — fix the layout instead (bigger targets, clearer highlights).

== C — Design ==

=== C.1 Typography & translations ===

Clarity beats style.

'''✔️ Do'''
* Use the default BGA font.
* Use clean sans-serif if you must change.
* Maintain good line spacing.
* Make all text translatable via BGA's translation system.
* Support LTR ''and'' RTL languages — test alignment & mirroring.
* Ensure your font supports accents/diacritics (é, ñ, ü).
* Meet '''WCAG AA''' contrast.
* Test on a phone — what's readable on a 27" monitor may not be on mobile.

'''❌ Don't'''
* Do not use decorative or themed fonts (hard to read, licensing risk, missing glyphs).
* Do not mix multiple fonts for "theme."
* Do not embed text directly into images without alt-text.

=== C.2 Highlights & Glowing auras ===

Players should never wonder "what do I click?"

'''✔️ Do'''
* Highlight valid options so the awaited action is obvious.
* Show consequences visually before the player commits.

''Example of highlighting valid options on the table.''

[[File:Ux-09-active-element.jpg]]

=== C.3 Button colors and styling ===

Button colors are a shared language across BGA. Mandatory for consistency.

{| class="wikitable"
! Color !! Meaning !! <code>statusBar.addActionButton</code>
|-
| 🔵 '''Blue''' || Advance, confirm, move forward || <code>primary</code>
|-
| 🔴 '''Red''' || Cancel, undo, stop, exit || <code>alert</code>
|-
| ⚪ '''White / Transparent''' || Optional/side actions || <code>secondary</code>
|-
| ⚫ '''Grey''' || Disabled, completed, unavailable || (disabled state of any of the above)
|}

'''✔️ Do'''
* Display usernames in their assigned player color.
* Outline player-color text so it stays visible (e.g. yellow on white).
* Test player colors on both light and dark backgrounds.
* Take any extra colors from '''game components''' (cards, tiles, tokens), not UI buttons.

'''❌ Don't'''
* Do not reassign blue/red/grey for game-specific meaning.
* Do not tint UI buttons to match the game's theme.

Note: Think of button colors as '''traffic lights''': blue = go, red = stop, grey = unavailable.

=== C.4 Sizing & responsiveness ===

'''✔️ Do'''
* Keep the main play area centered on every device.
* Use fluid layouts that expand/contract to fit available space.
* Leave margins around the board (prevents mobile misclicks).
* On desktop/tablet: show the entire board when possible.
* On mobile (vertical): stack secondary elements ''below'' the main action zone.
* Make everything readable and usable at 100% scale.
* Add HTML anchors / jump-links for vertical layouts.

'''❌ Don't'''
* Do not use fixed-width designs.
* Do not rely on zoom for legibility.
* Do not let layout break when players zoom in/out.
* Do not make any interactive element smaller than '''32×32px''' (see [[#E.3 Tap targets|E.3]]).

''Reference implementation:'' [https://thoun.github.io/bga-jump-to/demo/index.html bga-jump-to demo]

=== C.5 Background & extras ===

The background is the table surface your game sits on.

'''✔️ Do'''
* Use thematic, modern backgrounds (subtle playmat look).
* Add slight texture or pattern.
* Apply a touch of blur so components remain the visual focus.
* Prioritize contrast against the game's components.

'''❌ Don't'''
* Do not use pure flat colors.
* Do not use sharp, busy, detailed backgrounds that compete with the game.
* Do not let the background reduce component visibility.

== D — Feedback ==

=== D.1 Errors & invalid actions ===

Silence is never acceptable. Every failed action must say why.

'''✔️ Do'''
* Use a short shake, grey-out, or tooltip on failure.
* Show concise plain-text errors: ''"You don't have enough resources."''
* Pair color with icons or text (don't rely on red alone).

'''❌ Don't'''
* Do not leave the player guessing.
* Do not use color alone — colorblind users won't see it.

=== D.2 Game Logs ===

Logs are the narration of the match. Critical for asynchronous games.

'''✔️ Do'''
* Log every major action: card plays, moves, resource changes, eliminations.
* Always say '''who''' acted and '''what''' changed.
* Use icons, colors, formatting for fast scanning.
* Provide alt-text for graphic components inside logs.
* Group small simultaneous actions into a one-liner.
* Log automated/forced actions too.

'''❌ Don't'''
* Do not write walls of text or use oversized images that break log flow.
* Do not hide ''who'' did the action.

''Good:''
* "Marianna placed [red tile] on [central board] (+2 points)."
* "Alex drew 2 [train cards]."

''Bad:''
* "+2 points"
* "Card drawn"

=== D.3 Animation ===

Animations explain '''what moved, where it went, why it matters'''.

'''✔️ Do'''
* Use animations for: cards entering a hand, tokens moving, score count-up.
* Keep regular animations at '''0.5s''', max '''0.8s'''.
* Batch repetitive updates (don't show 50 tiny +1 animations).

'''❌ Don't'''
* Do not animate trivial updates one by one.
* Do not use looping, bouncing, or glowing animations as decoration.

→ See [https://en.doc.boardgamearena.com/BgaAnimations BGA animation library].

=== D.4 Sound effects ===

Sound is a bonus, not a requirement.

'''✔️ Do'''
* Keep volume '''below''' the BGA default.
* Keep sounds short, sharp, purposeful.
* Always pair sound with a visual cue.

'''❌ Don't'''
* Do not add long looping soundtracks.
* Do not let any action be communicated by '''sound only'''.
* Do not surprise players with loud audio.

== E — Accessibility ==

=== E.1 Design for all ===

'''✔️ Do'''
* Pair colors with icons, textures, or shapes.
* Meet contrast ratio '''4.5:1''' minimum.
* Label every button, icon, and interactive element (screen readers).
* Use bold shapes, clear outlines, strong contrast to differentiate pieces.

'''❌ Don't'''
* Do not rely on color alone.
* Do not use flashing or rapidly alternating visuals.
* Do not depend on fine details or subtle shading to differentiate components.

=== E.2 Colorblind-safe design ===

'''✔️ Do'''
* Add unique shapes/symbols/outlines per pawn or token color.
* Place small icons in card corners (or patterns) so suits are recognizable without hue.
* Meet '''WCAG AA''' for text and icons.
* Outline player-color names so yellow doesn't vanish on white.

'''❌ Don't'''
* Do not assume players perceive color differences.

=== E.3 Tap targets ===

'''✔️ Do'''
* Minimum '''32×32px''' for any interactive element.
* Aim for '''40–44px''' (greatly reduces mis-taps).
* Leave spacing between buttons, tokens, cards.
* Group many options into expandable menus or secondary panels.
* When space runs out, add scrolling — don't shrink components.

'''❌ Don't'''
* Do not cram small icons into tight clusters.
* Do not shrink components below the minimum to fit.

=== E.4 Settings & customization ===

'''✔️ Do'''
* Put all game settings in BGA's '''standard settings menu'''.
* Reuse existing BGA controls.
* Offer per-game options only where relevant: animation speed, tooltip detail, sound on/off.

'''❌ Don't'''
* Do not build custom settings UI (the platform is phasing those out).
* Do not duplicate controls already available globally.

== F — Technical ==

=== F.1 Endgame & Replays ===

'''✔️ Do'''
* Make replays flow without interruption.
* Keep animations skippable and playable at minimum speed.
* Keep logs and highlights in sync with each replayed action.
* Match the scoring pay-off to game length — long games deserve a longer reveal.
* Use synchronous notifications per scoring step and <code>this.displayScoring</code> for points animations.

'''❌ Don't'''
* Do not put blocking popups in replays.
* Do not drop the final score instantly at the end of a long game.

=== F.2 Refresh & Continuity ===

A refresh should feel invisible.

'''✔️ Do'''
* Restore the exact game state after refresh (no missing/corrupted info).
* Restore temporary UI: whose turn it is, pending actions, selected components.
* Treat the server as the source of truth for all critical state.
* Expect disconnect/reconnect as normal — BGA may do it at any time.

'''❌ Don't'''
* Do not store critical state in client-only memory.
* Do not rely on session continuity hacks.

=== F.3 Error handling ===

'''✔️ Do'''
* Handle disconnects and dropped actions without breaking flow.
* Show players short, friendly messages explaining what went wrong.
* Log precise error details to the developer console.
* Isolate the error to the affected action.

'''❌ Don't'''
* Do not crash the game on invalid input.
* Do not expose raw server logs or stack traces to players.
* Do not block the whole table because of one failed request.

== Pre-release Checklist ==

''Version 1.0.0 — May 22, 2026''

{| class="wikitable"
! # !! Check
|-
| 1 || Layout centers and scales on all devices.
|-
| 2 || Action Bar ≤ 4 buttons, never replaces components.
|-
| 3 || Tooltips: clear, translatable, useful.
|-
| 4 || Buttons follow BGA standards (blue = forward, red = cancel).
|-
| 5 || No blocking popups mid-game.
|-
| 6 || Animations: quick, smooth, informative.
|-
| 7 || All tap/click targets ≥ 32px.
|-
| 8 || Colorblind-safe icons in place.
|-
| 9 || Endgame shows breakdown + replay option.
|-
| 10 || Game state restores cleanly after refresh.
|}

== Closing thoughts ==

* '''Alpha:''' gather usability feedback.
* '''Beta:''' listen to the crowd — confusion spots = redesign spots.
* '''Iterate:''' small UX tweaks = big retention gains.
* '''Watch metrics:''' if players stall at a phase, that's your design flag.

Play other BGA games with similar mechanics — get inspired, challenge your assumptions, and treat UX as a key part of design, not an afterthought.

= BGA Studio Guidelines (Source Code) =
Make your code as easy to read and understand as possible: clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

== Front (JS) code ==

=== Generated code ===
Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

=== Templates ===
Use of .tpl file and view.php is deprecated and forbidden for new projects.

== Back (PHP) code ==
Game name and option names should be Capitalized.

=== Framework functions ===

===== Undocumented functions =====
Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

==== Function override ====
Do not override framework functions. Use a wrapper instead.

'''Bad :'''

<pre>
public function getPlayerNameById($player_id) { // same name as the framework function = override
if ($player_id == 0) {
return 'Automata';
} else {
return parent::getPlayerNameById($player_id);
}
}
</pre>

'''Better :'''
<pre>
public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
if ($player_id == 0) {
return 'Automata';
} else {
return $this->getPlayerNameById($player_id);
}
}
</pre>

==== State functions ====
States functions should be prefixed "st"

Args functions should be prefixed "arg"

Action functions should be prefixed "act"

=== Namespacing ===
The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <code><mygame>/PowerCard/PowerCardManager.php</code> and start like this :

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\<mygame>\PowerCard;
class PowerCardManager {
</pre>

=== Other ===
.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function must check any input. To avoid code duplication, they can use the arg function.

''Example :''

<pre>
$args = $this->argPlayCards();
if (!in_array($cardId, $args['selectableCardsIds'])) { throw new \BgaUserException(...); }
</pre>

Don’t use `@` to ignore the errors of a function call.

[[Category:Studio]]

BGA Studio Guidelines

2026-05-23T01:05:44Z

Victoria La: Minor corrections

= BGA Studio Guidelines (UX/UI) =

This page covers UX guidelines for games on Board Game Arena. Read the [[Media:Guidelines UX new compressed.pdf|official PDF]] or [https://bga.li/mRdx bga.li/mRdx] first. This page is an unofficial summary.

Goal: most games should be instantly playable on any device — desktop at midnight or phone at lunch.

Use this page to validate UX before switching your game from '''ALPHA → BETA → RELEASE'''.

== A — Layouts ==

=== A.1 Layout arrangement ===

Game should fit a square ratio and show everything the active player needs. Use vertical scroll for secondary info (other players' progress, secondary boards).

'''✔️ Do'''
* Center the play area on all devices.
* Leave a "no action" margin around the board (deselect, scroll on mobile).
* Use HTML anchors to jump between distant sections.
* Use spacers / transparent whiteblocks to group pieces clearly.
* Keep score, turn order, and objectives '''accessible''' (button/tab/panel), not always visible.
* Tuck rare abilities into tooltips.

'''❌ Don't'''
* Do not hide game components behind popups — you should see everything you'd see on a real table.
* Do not place "always accessible" info permanently on the player panels.
* Do not add in-game logos or branding that isn't part of the actual game.
* Do not scatter related info (e.g. resources) across three corners.

Note: '''Layout mantra:''' Central = shared actions. Top/Bottom = global info. Panels = private resources.

[[File:Ux-01-layouts.jpg]]

=== A.2 Action Bar ===

The Action Bar always shows the current state: turn in progress, who we're waiting for, or what the player can do.

[[File:Ux-03-action-bar-mock.jpg]]

'''✔️ Do'''
* Center '''main awaited actions''' (Play card, End turn, Confirm move).
* Place secondary/greyed-out actions next to them.
* Put '''cancel / undo / remove''' on the right, visually separated from forward actions.
* Use the Action Bar for: actions targeting another player, Pass/End turn/time-related actions, auction phases, and small resource exchanges without dedicated board space.
* Keep it to '''max 4 buttons + context''' so it doesn't overflow on mobile.

'''❌ Don't'''
* Do not replace board-component actions with Action Bar buttons — players should act on the board like in real life.
* Do not stick custom buttons next to BGA's built-in buttons (replay controls, etc.).
* Do not let cancel actions visually compete with main actions.
* Do not show "Round in progress" text inside the bar — display it on the table or as flavor text of the current action.

''Example: Wingspan shows the current round as flavor text under the action bar.''

[[File:Ux-02-action-bar-examples.jpg]]

→ See [[#C.3 Button colors and styling|C.3]] for button colors.

=== A.3 Player panels ===

Player panels let anyone glance at: who's playing, color, score, turn order, and resources gained.

'''✔️ Do'''
* Keep panels compact — a 4-player game on mobile must not occupy more than '''¼ of the screen'''.
* Offer HTML anchor shortcuts to jump to a player's main components.

'''❌ Don't'''
* Do not put settings, titles, round numbers, or other redundant info in panels.
* Do not put always-accessible info (score, objectives) ''only'' on player panels.

[[File:Ux-04-player-panel.jpg]]

=== A.4 Popups ===

'''✔️ Do'''
* Reserve automatic popups for '''tutorials only'''.
* Make any required popup skippable on click/touch/timer.
* Use the wiki space below the game for rules, hints, scoring tips, helpers.

'''❌ Don't'''
* Do not block game flow with popups (forbidden).
* Do not use popups mid-game — only allowed for between-round/stage scoring.

[[File:Ux-05-popup.jpg]]

→ See [[#B.1 Tooltips|B.1]] for non-blocking alternatives.

=== A.5 Clarity & Zoom ===

Use vertical space and good layout instead of zoom controls.

'''✔️ Do'''
* Design so the core game is fully playable at '''100% scale'''.
* Trust browser zoom: Ctrl+wheel on desktop, pinch on mobile.

'''❌ Don't'''
* Do not add zoom buttons unless absolutely necessary (large secondary boards, very text-heavy cards like Ticket to Ride).

'''If you must add zoom buttons:'''
* '''+''' (plus): zoom in
* '''–''' (minus): zoom out
* 🏠 Home: reset to default

== B — Usability ==

=== B.1 Tooltips ===

Tooltips add insight, not duplication.

'''✔️ Do'''
* Add extra detail beyond what's on screen (translatable text, hints about when to use).
* Use them to zoom into small text/icons on large game boards.
* Close tooltips when the user taps away on mobile.

'''❌ Don't'''
* Do not show the same info twice the same way.
* Do not add a tooltip that's just a zoomed-in copy of an already-visible card — that's a sign your components are mis-sized.

''Example: Ticket to Ride hover tooltips name cards/decks without distraction.''

[[File:Ux-07-tooltip-1.jpg]]

''Example: Altered shows minimal default info, with full detail on hover.''

[[File:Ux-08-tooltip-2.jpg]]

=== B.2 Forbidden actions ===

'''✔️ Do'''
* Grey out / disable actions that exist but aren't currently available.

'''❌ Don't'''
* Do not show disabled buttons for actions that are never relevant in the current context — just hide them.

=== B.3 Undo, Reset, Restart ===

BGA philosophy: fast, fluid, intuitive. Use these controls sparingly.

'''✔️ Do'''
* Use '''Confirm''' buttons for impactful, irreversible actions (end turn, discard, commit resources).
* Prefer timed confirmation (5–8s) over undo.
* Offer one '''Restart Turn''' for the whole turn when rules allow, not per-micro-action undo.
* Allow "Undo last move" only when a turn has '''more than 2 actions'''.

'''❌ Don't'''
* Do not add an Undo button for every action — multiplies validation steps, slows the game.
* Do not layer Undo on top of Reset on top of Confirm — over-validation.
* Do not use Undo to paper over misclicks — fix the layout instead (bigger targets, clearer highlights).

== C — Design ==

=== C.1 Typography & translations ===

Clarity beats style.

'''✔️ Do'''
* Use the default BGA font.
* Use clean sans-serif if you must change.
* Maintain good line spacing.
* Make all text translatable via BGA's translation system.
* Support LTR ''and'' RTL languages — test alignment & mirroring.
* Ensure your font supports accents/diacritics (é, ñ, ü).
* Meet '''WCAG AA''' contrast.
* Test on a phone — what's readable on a 27" monitor may not be on mobile.

'''❌ Don't'''
* Do not use decorative or themed fonts (hard to read, licensing risk, missing glyphs).
* Do not mix multiple fonts for "theme."
* Do not embed text directly into images without alt-text.

=== C.2 Highlights & Glowing auras ===

Players should never wonder "what do I click?"

'''✔️ Do'''
* Highlight valid options so the awaited action is obvious.
* Show consequences visually before the player commits.

''Example of highlighting valid options on the table.''

[[File:Ux-09-active-element.jpg]]

=== C.3 Button colors and styling ===

Button colors are a shared language across BGA. Mandatory for consistency.

{| class="wikitable"
! Color !! Meaning !! <code>statusBar.addActionButton</code>
|-
| 🔵 '''Blue''' || Advance, confirm, move forward || <code>primary</code>
|-
| 🔴 '''Red''' || Cancel, undo, stop, exit || <code>alert</code>
|-
| ⚪ '''White / Transparent''' || Optional/side actions || <code>secondary</code>
|-
| ⚫ '''Grey''' || Disabled, completed, unavailable || (disabled state of any of the above)
|}

'''✔️ Do'''
* Display usernames in their assigned player color.
* Outline player-color text so it stays visible (e.g. yellow on white).
* Test player colors on both light and dark backgrounds.
* Take any extra colors from '''game components''' (cards, tiles, tokens), not UI buttons.

'''❌ Don't'''
* Do not reassign blue/red/grey for game-specific meaning.
* Do not tint UI buttons to match the game's theme.

Note: Think of button colors as '''traffic lights''': blue = go, red = stop, grey = unavailable.

=== C.4 Sizing & responsiveness ===

'''✔️ Do'''
* Keep the main play area centered on every device.
* Use fluid layouts that expand/contract to fit available space.
* Leave margins around the board (prevents mobile misclicks).
* On desktop/tablet: show the entire board when possible.
* On mobile (vertical): stack secondary elements ''below'' the main action zone.
* Make everything readable and usable at 100% scale.
* Add HTML anchors / jump-links for vertical layouts.

'''❌ Don't'''
* Do not use fixed-width designs.
* Do not rely on zoom for legibility.
* Do not let layout break when players zoom in/out.
* Do not make any interactive element smaller than '''32×32px''' (see [[#E.3 Tap targets|E.3]]).

''Reference implementation:'' [https://thoun.github.io/bga-jump-to/demo/index.html bga-jump-to demo]

=== C.5 Background & extras ===

The background is the table surface your game sits on.

'''✔️ Do'''
* Use thematic, modern backgrounds (subtle playmat look).
* Add slight texture or pattern.
* Apply a touch of blur so components remain the visual focus.
* Prioritize contrast against the game's components.

'''❌ Don't'''
* Do not use pure flat colors.
* Do not use sharp, busy, detailed backgrounds that compete with the game.
* Do not let the background reduce component visibility.

== D — Feedback ==

=== D.1 Errors & invalid actions ===

Silence is never acceptable. Every failed action must say why.

'''✔️ Do'''
* Use a short shake, grey-out, or tooltip on failure.
* Show concise plain-text errors: ''"You don't have enough resources."''
* Pair color with icons or text (don't rely on red alone).

'''❌ Don't'''
* Do not leave the player guessing.
* Do not use color alone — colorblind users won't see it.

=== D.2 Game Logs ===

Logs are the narration of the match. Critical for asynchronous games.

'''✔️ Do'''
* Log every major action: card plays, moves, resource changes, eliminations.
* Always say '''who''' acted and '''what''' changed.
* Use icons, colors, formatting for fast scanning.
* Provide alt-text for graphic components inside logs.
* Group small simultaneous actions into a one-liner.
* Log automated/forced actions too.

'''❌ Don't'''
* Do not write walls of text or use oversized images that break log flow.
* Do not hide ''who'' did the action.

''Good:''
* "Marianna placed [red tile] on [central board] (+2 points)."
* "Alex drew 2 [train cards]."

''Bad:''
* "+2 points"
* "Card drawn"

=== D.3 Animation ===

Animations explain '''what moved, where it went, why it matters'''.

'''✔️ Do'''
* Use animations for: cards entering a hand, tokens moving, score count-up.
* Keep regular animations at '''0.5s''', max '''0.8s'''.
* Batch repetitive updates (don't show 50 tiny +1 animations).

'''❌ Don't'''
* Do not animate trivial updates one by one.
* Do not use looping, bouncing, or glowing animations as decoration.

→ See [https://en.doc.boardgamearena.com/BgaAnimations BGA animation library].

=== D.4 Sound effects ===

Sound is a bonus, not a requirement.

'''✔️ Do'''
* Keep volume '''below''' the BGA default.
* Keep sounds short, sharp, purposeful.
* Always pair sound with a visual cue.

'''❌ Don't'''
* Do not add long looping soundtracks.
* Do not let any action be communicated by '''sound only'''.
* Do not surprise players with loud audio.

== E — Accessibility ==

=== E.1 Design for all ===

'''✔️ Do'''
* Pair colors with icons, textures, or shapes.
* Meet contrast ratio '''4.5:1''' minimum.
* Label every button, icon, and interactive element (screen readers).
* Use bold shapes, clear outlines, strong contrast to differentiate pieces.

'''❌ Don't'''
* Do not rely on color alone.
* Do not use flashing or rapidly alternating visuals.
* Do not depend on fine details or subtle shading to differentiate components.

=== E.2 Colorblind-safe design ===

'''✔️ Do'''
* Add unique shapes/symbols/outlines per pawn or token color.
* Place small icons in card corners (or patterns) so suits are recognizable without hue.
* Meet '''WCAG AA''' for text and icons.
* Outline player-color names so yellow doesn't vanish on white.

'''❌ Don't'''
* Do not assume players perceive color differences.

=== E.3 Tap targets ===

'''✔️ Do'''
* Minimum '''32×32px''' for any interactive element.
* Aim for '''40–44px''' (greatly reduces mis-taps).
* Leave spacing between buttons, tokens, cards.
* Group many options into expandable menus or secondary panels.
* When space runs out, add scrolling — don't shrink components.

'''❌ Don't'''
* Do not cram small icons into tight clusters.
* Do not shrink components below the minimum to fit.

=== E.4 Settings & customization ===

'''✔️ Do'''
* Put all game settings in BGA's '''standard settings menu'''.
* Reuse existing BGA controls.
* Offer per-game options only where relevant: animation speed, tooltip detail, sound on/off.

'''❌ Don't'''
* Do not build custom settings UI (the platform is phasing those out).
* Do not duplicate controls already available globally.

== F — Technical ==

=== F.1 Endgame & Replays ===

'''✔️ Do'''
* Make replays flow without interruption.
* Keep animations skippable and playable at minimum speed.
* Keep logs and highlights in sync with each replayed action.
* Match the scoring pay-off to game length — long games deserve a longer reveal.
* Use synchronous notifications per scoring step and <code>this.displayScoring</code> for points animations.

'''❌ Don't'''
* Do not put blocking popups in replays.
* Do not drop the final score instantly at the end of a long game.

=== F.2 Refresh & Continuity ===

A refresh should feel invisible.

'''✔️ Do'''
* Restore the exact game state after refresh (no missing/corrupted info).
* Restore temporary UI: whose turn it is, pending actions, selected components.
* Treat the server as the source of truth for all critical state.
* Expect disconnect/reconnect as normal — BGA may do it at any time.

'''❌ Don't'''
* Do not store critical state in client-only memory.
* Do not rely on session continuity hacks.

=== F.3 Error handling ===

'''✔️ Do'''
* Handle disconnects and dropped actions without breaking flow.
* Show players short, friendly messages explaining what went wrong.
* Log precise error details to the developer console.
* Isolate the error to the affected action.

'''❌ Don't'''
* Do not crash the game on invalid input.
* Do not expose raw server logs or stack traces to players.
* Do not block the whole table because of one failed request.

== Pre-release Checklist ==

''Version 1.0.0 — May 22, 2026''

{| class="wikitable"
! # !! Check
|-
| 1 || Layout centers and scales on all devices.
|-
| 2 || Action Bar ≤ 4 buttons, never replaces components.
|-
| 3 || Tooltips: clear, translatable, useful.
|-
| 4 || Buttons follow BGA standards (blue = forward, red = cancel).
|-
| 5 || No blocking popups mid-game.
|-
| 6 || Animations: quick, smooth, informative.
|-
| 7 || All tap/click targets ≥ 32px.
|-
| 8 || Colorblind-safe icons in place.
|-
| 9 || Endgame shows breakdown + replay option.
|-
| 10 || Game state restores cleanly after refresh.
|}

== Closing thoughts ==

* '''Alpha:''' gather usability feedback.
* '''Beta:''' listen to the crowd — confusion spots = redesign spots.
* '''Iterate:''' small UX tweaks = big retention gains.
* '''Watch metrics:''' if players stall at a phase, that's your design flag.

Play other BGA games with similar mechanics — get inspired, challenge your assumptions, and treat UX as a key part of design, not an afterthought.

= BGA Studio Guidelines (Source Code) =
Make your code as easy to read and understand as possible: clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

== Front (JS) code ==

=== Generated code ===
Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

=== Templates ===
Use of .tpl file and view.php is deprecated and forbidden for new projects.

== Back (PHP) code ==
Game name and option names should be Capitalized.

=== Framework functions ===

===== Undocumented functions =====
Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

==== Function override ====
Do not override framework functions. Use a wrapper instead.

'''Bad :'''

<pre>
public function getPlayerNameById($player_id) { // same name as the framework function = override
if ($player_id == 0) {
return 'Automata';
} else {
return parent::getPlayerNameById($player_id);
}
}
</pre>

'''Better :'''
<pre>
public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
if ($player_id == 0) {
return 'Automata';
} else {
return $this->getPlayerNameById($player_id);
}
}
</pre>

==== State functions ====
States functions should be prefixed "st"

Args functions should be prefixed "arg"

Action functions should be prefixed "act"

=== Namespacing ===
The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <code><mygame>/PowerCard/PowerCardManager.php</code> and start like this :

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\<mygame>\PowerCard;
class PowerCardManager {
</pre>

=== Other ===
.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function must check any input. To avoid code duplication, they can use the arg function.

''Example :''

<pre>
$args = $this->argPlayCards();
if (!in_array($cardId, $args['selectableCardsIds'])) { throw new \BgaUserException(...); }
</pre>

Don’t use `@` to ignore the errors of a function call.

[[Category:Studio]]

File:Ux-09-active-element.jpg

2026-05-23T00:40:17Z

Victoria La:

File:Ux-08-tooltip-2.jpg

2026-05-23T00:40:01Z

Victoria La:

File:Ux-07-tooltip-1.jpg

2026-05-23T00:39:43Z

Victoria La:

File:Ux-05-popup.jpg

2026-05-23T00:39:29Z

Victoria La:

File:Ux-04-player-panel.jpg

2026-05-23T00:39:16Z

Victoria La:

File:Ux-03-action-bar-mock.jpg

2026-05-23T00:39:03Z

Victoria La:

File:Ux-02-action-bar-examples.jpg

2026-05-23T00:38:51Z

Victoria La:

File:Ux-01-layouts.jpg

2026-05-23T00:38:28Z

Victoria La:

BGA Studio Guidelines

2026-05-23T00:05:32Z

Victoria La: re-align with current guidelines

= BGA Studio Guidelines (UX/UI) =

{{TOC}}

This page covers UX guidelines for games on Board Game Arena. Read the [[File:Guidelines UX new compressed.pdf]] or https://bga.li/mRdx document first. This page is just UNOFFICIAL summary.

Goal: most games should be instantly playable on any device — desktop at midnight or phone at lunch.

Use this page to validate UX before switching your game from '''ALPHA → BETA → RELEASE'''.

== A — Layouts ==

=== A.1 Layout arrangement ===

Game should fit a square ratio and show everything the active player needs. Use vertical scroll for secondary info (other players' progress, secondary boards).

'''✔️ Do'''
* Center the play area on all devices.
* Leave a "no action" margin around the board (deselect, scroll on mobile).
* Use HTML anchors to jump between distant sections.
* Use spacers / transparent whiteblocks to group pieces clearly.
* Keep score, turn order, and objectives '''accessible''' (button/tab/panel), not always visible.
* Tuck rare abilities into tooltips.

'''❌ Don't'''
* Hide game components behind popups — you should see everything you'd see on a real table.
* Place "always accessible" info permanently on the player panels.
* Add in-game logos or branding that isn't part of the actual game.
* Scatter related info (e.g. resources) across three corners.

{{Note|'''Layout mantra:''' Central = shared actions. Top/Bottom = global info. Panels = private resources. Stack for mobile, avoid endless scroll.}}

=== A.2 Action Bar ===

The Action Bar always shows the current state: turn in progress, who we're waiting for, or what the player can do.

'''✔️ Do'''
* Center '''main awaited actions''' (Play card, End turn, Confirm move).
* Place secondary/greyed-out actions next to them.
* Put '''cancel / undo / remove''' on the right, visually separated from forward actions.
* Use the Action Bar for: actions targeting another player, Pass/End turn/time-related actions, auction phases, and small resource exchanges without dedicated board space.
* Keep it to '''max 4 buttons + context''' so it doesn't overflow on mobile.

'''❌ Don't'''
* Replace board-component actions with Action Bar buttons — players should act on the board like in real life.
* Stick custom buttons next to BGA's built-in buttons (replay controls, etc.).
* Let cancel actions visually compete with main actions.
* Show "Round in progress" text inside the bar — display it on the table or as flavor text of the current action.

''Example: Wingspan shows the current round as flavor text under the action bar.'' [[File:placeholder-wingspan-actionbar.png|thumb|center]]

→ See [[#C.3 Button colors and styling|C.3]] for button colors.

=== A.3 Player panels ===

Player panels let anyone glance at: who's playing, color, score, turn order, and resources gained.

'''✔️ Do'''
* Keep panels compact — a 4-player game on mobile must not occupy more than '''¼ of the screen'''.
* Offer HTML anchor shortcuts to jump to a player's main components.

'''❌ Don't'''
* Put settings, titles, round numbers, or other redundant info in panels.
* Put always-accessible info (score, objectives) ''only'' on player panels.

=== A.4 Popups ===

'''✔️ Do'''
* Reserve automatic popups for '''tutorials only'''.
* Make any required popup skippable on click/touch/timer.
* Use the wiki space below the game for rules, hints, scoring tips, helpers.

'''❌ Don't'''
* Block game flow with popups (forbidden).
* Use popups mid-game — only allowed for between-round/stage scoring.

→ See [[#B.1 Tooltips|B.1]] for non-blocking alternatives.

=== A.5 Clarity & Zoom ===

Use vertical space and good layout instead of zoom controls.

'''✔️ Do'''
* Design so the core game is fully playable at '''100% scale'''.
* Trust browser zoom: Ctrl+wheel on desktop, pinch on mobile.

'''❌ Don't'''
* Add zoom buttons unless absolutely necessary (large secondary boards, very text-heavy cards like Ticket to Ride).

'''If you must add zoom buttons:'''
* '''+''' (plus): zoom in
* '''–''' (minus): zoom out
* 🏠 Home: reset to default
* Default view must remain perfectly playable without zoom.

== B — Usability ==

=== B.1 Tooltips ===

Tooltips add insight, not duplication.

'''✔️ Do'''
* Add extra detail beyond what's on screen (translatable text, hints about when to use).
* Use them to zoom into small text/icons on large game boards.
* Close tooltips when the user taps away on mobile.

'''❌ Don't'''
* Show the same info twice the same way.
* Add a tooltip that's just a zoomed-in copy of an already-visible card — that's a sign your components are mis-sized.

''Examples: Ticket to Ride hover tooltips name cards/decks without distraction. Altered shows minimal default info, full detail on hover.'' [[File:placeholder-tooltip-examples.png|thumb|center]]

=== B.2 Forbidden actions ===

'''✔️ Do'''
* Grey out / disable actions that exist but aren't currently available.

'''❌ Don't'''
* Show disabled buttons for actions that are never relevant in the current context — just hide them.

=== B.3 Undo, Reset, Restart ===

BGA philosophy: fast, fluid, intuitive. Use these controls sparingly.

'''✔️ Do'''
* Use '''Confirm''' buttons for impactful, irreversible actions (end turn, discard, commit resources).
* Prefer timed confirmation (5–8s) over undo.
* Offer one '''Restart Turn''' for the whole turn when rules allow, not per-micro-action undo.
* Allow "Undo last move" only when a turn has '''more than 2 actions'''.

'''❌ Don't'''
* Add an Undo button for every action — multiplies validation steps, slows the game.
* Layer Undo on top of Reset on top of Confirm — over-validation.
* Use Undo to paper over misclicks — fix the layout instead (bigger targets, clearer highlights).

== C — Design ==

=== C.1 Typography & translations ===

Clarity beats style.

'''✔️ Do'''
* Use the default BGA font.
* Use clean sans-serif if you must change.
* Maintain good line spacing.
* Make all text translatable via BGA's translation system.
* Support LTR ''and'' RTL languages — test alignment & mirroring.
* Ensure your font supports accents/diacritics (é, ñ, ü).
* Meet '''WCAG AA''' contrast.
* Test on a phone — what's readable on a 27" monitor may not be on mobile.

'''❌ Don't'''
* Use decorative or themed fonts (hard to read, licensing risk, missing glyphs).
* Mix multiple fonts for "theme."
* Embed text directly into images without alt-text.

=== C.2 Highlights & Glowing auras ===

Players should never wonder "what do I click?"

'''✔️ Do'''
* Highlight valid options so the awaited action is obvious.
* Show consequences visually before the player commits.

[[File:placeholder-highlights.png|thumb|center|''Example of highlighting valid options on the table.'']]

=== C.3 Button colors and styling ===

Button colors are a shared language across BGA. Mandatory for consistency.

{| class="wikitable"
! Color !! Meaning !! <code>statusBar.addActionButton</code>
|-
| 🔵 '''Blue''' || Advance, confirm, move forward || <code>primary</code>
|-
| 🔴 '''Red''' || Cancel, undo, stop, exit || <code>alert</code>
|-
| ⚪ '''White / Transparent''' || Optional/side actions || <code>secondary</code>
|-
| ⚫ '''Grey''' || Disabled, completed, unavailable || (disabled state of any of the above)
|}

'''✔️ Do'''
* Display usernames in their assigned player color.
* Outline player-color text so it stays visible (e.g. yellow on white).
* Test player colors on both light and dark backgrounds.
* Take any extra colors from '''game components''' (cards, tiles, tokens), not UI buttons.

'''❌ Don't'''
* Reassign blue/red/grey for game-specific meaning.
* Tint UI buttons to match the game's theme.

{{Note|Think of button colors as '''traffic lights''': blue = go, red = stop, grey = unavailable.}}

=== C.4 Sizing & responsiveness ===

'''✔️ Do'''
* Keep the main play area centered on every device.
* Use fluid layouts that expand/contract to fit available space.
* Leave margins around the board (prevents mobile misclicks).
* On desktop/tablet: show the entire board when possible.
* On mobile (vertical): stack secondary elements ''below'' the main action zone.
* Make everything readable and usable at 100% scale.
* Add HTML anchors / jump-links for vertical layouts.

'''❌ Don't'''
* Use fixed-width designs.
* Rely on zoom for legibility.
* Let layout break when players zoom in/out.
* Make any interactive element smaller than '''32×32px''' (see [[#E.3 Tap targets|E.3]]).

''Reference implementation:'' [https://thoun.github.io/bga-jump-to/demo/index.html bga-jump-to demo]

=== C.5 Background & extras ===

The background is the table surface your game sits on.

'''✔️ Do'''
* Use thematic, modern backgrounds (subtle playmat look).
* Add slight texture or pattern.
* Apply a touch of blur so components remain the visual focus.
* Prioritize contrast against the game's components.

'''❌ Don't'''
* Use pure flat colors.
* Use sharp, busy, detailed backgrounds that compete with the game.
* Let the background reduce component visibility.

== D — Feedback ==

=== D.1 Errors & invalid actions ===

Silence is never acceptable. Every failed action must say why.

'''✔️ Do'''
* Use a short shake, grey-out, or tooltip on failure.
* Show concise plain-text errors: ''"You don't have enough resources."''
* Pair color with icons or text (don't rely on red alone).

'''❌ Don't'''
* Leave the player guessing.
* Use color alone — colorblind users won't see it.

=== D.2 Game Logs ===

Logs are the narration of the match. Critical for asynchronous games.

'''✔️ Do'''
* Log every major action: card plays, moves, resource changes, eliminations.
* Always say '''who''' acted and '''what''' changed.
* Use icons, colors, formatting for fast scanning.
* Provide alt-text for graphic components inside logs.
* Group small simultaneous actions into a one-liner.
* Log automated/forced actions too.

'''❌ Don't'''
* Write walls of text or use oversized images that break log flow.
* Hide ''who'' did the action.

''Good:''
* "Marianna placed [red tile] on [central board] (+2 points)."
* "Alex drew 2 [train cards]."

''Bad:''
* "+2 points"
* "Card drawn"

=== D.3 Animation ===

Animations explain '''what moved, where it went, why it matters'''.

'''✔️ Do'''
* Use animations for: cards entering a hand, tokens moving, score count-up.
* Keep regular animations at '''0.5s''', max '''0.8s'''.
* Batch repetitive updates (don't show 50 tiny +1 animations).

'''❌ Don't'''
* Animate trivial updates one by one.
* Use looping, bouncing, or glowing animations as decoration.

→ See [https://en.doc.boardgamearena.com/BgaAnimations BGA animation library].

=== D.4 Sound effects ===

Sound is a bonus, not a requirement.

'''✔️ Do'''
* Keep volume '''below''' the BGA default.
* Keep sounds short, sharp, purposeful.
* Always pair sound with a visual cue.

'''❌ Don't'''
* Add long looping soundtracks.
* Let any action be communicated by '''sound only'''.
* Surprise players with loud audio.

== E — Accessibility ==

=== E.1 Design for all ===

'''✔️ Do'''
* Pair colors with icons, textures, or shapes.
* Meet contrast ratio '''4.5:1''' minimum.
* Label every button, icon, and interactive element (screen readers).
* Use bold shapes, clear outlines, strong contrast to differentiate pieces.

'''❌ Don't'''
* Rely on color alone.
* Use flashing or rapidly alternating visuals.
* Depend on fine details or subtle shading to differentiate components.

=== E.2 Colorblind-safe design ===

'''✔️ Do'''
* Add unique shapes/symbols/outlines per pawn or token color.
* Place small icons in card corners (or patterns) so suits are recognizable without hue.
* Meet '''WCAG AA''' for text and icons.
* Outline player-color names so yellow doesn't vanish on white.

'''❌ Don't'''
* Assume players perceive color differences.

=== E.3 Tap targets ===

'''✔️ Do'''
* Minimum '''32×32px''' for any interactive element.
* Aim for '''40–44px''' (greatly reduces mis-taps).
* Leave spacing between buttons, tokens, cards.
* Group many options into expandable menus or secondary panels.
* When space runs out, add scrolling — don't shrink components.

'''❌ Don't'''
* Cram small icons into tight clusters.
* Shrink components below the minimum to fit.

=== E.4 Settings & customization ===

'''✔️ Do'''
* Put all game settings in BGA's '''standard settings menu'''.
* Reuse existing BGA controls.
* Offer per-game options only where relevant: animation speed, tooltip detail, sound on/off.

'''❌ Don't'''
* Build custom settings UI (the platform is phasing those out).
* Duplicate controls already available globally.

== F — Technical ==

=== F.1 Endgame & Replays ===

'''✔️ Do'''
* Make replays flow without interruption.
* Keep animations skippable and playable at minimum speed.
* Keep logs and highlights in sync with each replayed action.
* Match the scoring pay-off to game length — long games deserve a longer reveal.
* Use synchronous notifications per scoring step and <code>this.displayScoring</code> for points animations.

'''❌ Don't'''
* Put blocking popups in replays.
* Drop the final score instantly at the end of a long game.

=== F.2 Refresh & Continuity ===

A refresh should feel invisible.

'''✔️ Do'''
* Restore the exact game state after refresh (no missing/corrupted info).
* Restore temporary UI: whose turn it is, pending actions, selected components.
* Treat the server as the source of truth for all critical state.
* Expect disconnect/reconnect as normal — BGA may do it at any time.

'''❌ Don't'''
* Store critical state in client-only memory.
* Rely on session continuity hacks.

=== F.3 Error handling ===

'''✔️ Do'''
* Handle disconnects and dropped actions without breaking flow.
* Show players short, friendly messages explaining what went wrong.
* Log precise error details to the developer console.
* Isolate the error to the affected action.

'''❌ Don't'''
* Crash the game on invalid input.
* Expose raw server logs or stack traces to players.
* Block the whole table because of one failed request.

== Pre-release Checklist ==

''Version 1.0.0 — Oct 10, 2025''

{| class="wikitable"
! # !! Check
|-
| 1 || Layout centers and scales on all devices.
|-
| 2 || Action Bar ≤ 4 buttons, never replaces components.
|-
| 3 || Tooltips: clear, translatable, useful.
|-
| 4 || Buttons follow BGA standards (blue = forward, red = cancel).
|-
| 5 || No blocking popups mid-game.
|-
| 6 || Animations: quick, smooth, informative.
|-
| 7 || All tap/click targets ≥ 32px.
|-
| 8 || Colorblind-safe icons in place.
|-
| 9 || Endgame shows breakdown + replay option.
|-
| 10 || Game state restores cleanly after refresh.
|}

== Closing thoughts ==

* '''Alpha:''' gather usability feedback.
* '''Beta:''' listen to the crowd — confusion spots = redesign spots.
* '''Iterate:''' small UX tweaks = big retention gains.
* '''Watch metrics:''' if players stall at a phase, that's your design flag.

Play other BGA games with similar mechanics — get inspired, challenge your assumptions, and treat UX as a key part of design, not an afterthought.

= BGA Studio Guidelines (Source Code) =
Make your code as easy to read and understand as possible: clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

== Front (JS) code ==

=== Generated code ===
Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

=== Templates ===
Use of .tpl file and view.php is deprecated and forbidden for new projects.

== Back (PHP) code ==
Game name and option names should be Capitalized.

=== Framework functions ===

===== Undocumented functions =====
Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

==== Function override ====
Do not override framework functions. Use a wrapper instead.

'''Bad :'''

<pre>
public function getPlayerNameById($player_id) { // same name as the framework function = override
if ($player_id == 0) {
return 'Automata';
} else {
return parent::getPlayerNameById($player_id);
}
}
</pre>

'''Better :'''
<pre>
public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
if ($player_id == 0) {
return 'Automata';
} else {
return $this->getPlayerNameById($player_id);
}
}
</pre>

==== State functions ====
States functions should be prefixed “st”

Args functions should be prefixed “arg”

Action functions should be prefixed “act”

=== Namespacing ===
The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <code><mygame>/PowerCard/PowerCardManager.php</code> and start like this :

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\<mygame\PowerCard;
class PowerCardManager {
</pre>

=== Other ===
.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function must check any input. To avoid code duplication, they can use the arg function.

''Example :''

<pre>
$args = $this->argPlayCards();
if (!in_array($cardId, $args[‘selectableCardsIds’]) { throw new \BgaUserException(...); }
</pre>

Don’t use `@` to ignore the errors of a function call.

[[Category:Studio]]

Testing by developer

2026-04-19T14:38:48Z

Victoria La: stub example was wrong - was copy of autoloader, just replace with link for now will ask Thoun

When you develop a game you obviously have to test it, this page collects the info about testing in one place

== Manual Testing on BGA ==

For manual testing the most important things to know are:
* how to start/stop game in one click
* how to switch between players in one click
* how to save/restore the game state
* how to construct the game state automatically
All of these described here https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio

There is also HUGE checklist of things you need to test manually which you may not even think about, defined here https://en.doc.boardgamearena.com/Pre-release_checklist

== Manual Testing locally ==

'''HTML/CSS'''
At this era the file sync is almost instant so you do not save much by doing this locally, however if internet is a challenge - here are some tips
https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout

'''PHP'''
You can run and debug php locally using tip https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally

== Automated Testing ==
===JavaScript===

I did not try for pure java script, it works for typescript.
You need dev dependency on mocha, jsdom and sinon and some other build tools.
Typescript code lives in src/.
Test code lives in src/tests/.
Tests have their own src/tests/tsconfig.json
File src/tests/setup.ts contains framework and global stubs that tests need.
The config is very verbose so I did not copy it here, if interested check project "dojoless" or bga-dojoless on github (https://github.com/elaskavaia/bga-dojoless).

===PHP===

====Install PHPunit====

Install PHPunit via composer somewhere in home directory, i.e.
cd /home/<yourusername>/php-composer
composer require --dev phpunit/phpunit ^13

We don't want the phpunit cache to be sync/commited, so add <code>".phpunit.cache"</code> to sftp.json ignore list. You can push the unit tests to the FTP, no need to ignore them. If someone maintains your game in the future, he willl be able to use them to make sure nothing breaks on an update!
If you have a .gitignore, add <code>.phpunit.cache</code> to it.

Then add this to your .bashrc (alias function to be able to test phpunit easily)
phpunit() {
/home/<yourusername>/php-composer/vendor/bin/phpunit \
-c "$PWD/phpunit.xml.dist" \
--bootstrap "$PWD/tests/bootstrap.php" \
"$@"
}

With that, on a new terminal you will be able to run the tests with one of the following commands at the root of your project :
phpunit
phpunit tests/BoardManagerTest.php
phpunit --filter testGivesExtraTime

====Setup minimal files====
Create these files:

'''phpunit.xml.dist'''
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="tests/bootstrap.php"
colors="true"
cacheDirectory=".phpunit.cache">
<testsuites>
<testsuite name="Reversi">
<directory>tests</directory>
</testsuite>
</testsuites>
</phpunit>
</pre>
(replace Reversi by your project name)

'''tests/bootstrap.php'''
<pre>
<?php

declare(strict_types=1);

require_once __DIR__ . '/stubs/BgaFrameworkStubs.php';

$autoload = __DIR__ . '/../vendor/autoload.php';
if (file_exists($autoload)) {
require_once $autoload;
}

spl_autoload_register(static function (string $class): void {
$prefix = 'Bga\\Games\\Reversi\\';

if (!str_starts_with($class, $prefix)) {
return;
}

$relativeClass = substr($class, strlen($prefix));
$path = __DIR__ . '/../modules/php/' . str_replace('\\', '/', $relativeClass) . '.php';

if (file_exists($path)) {
require_once $path;
}
});
</pre>
(replace Reversi by your project name)

'''tests/stubs/BgaFrameworkStubs.php'''

That is where you stub framework classes and methods, example here
[https://github.com/elaskavaia/bga-sharedcode/blob/master/misc/php/stubs/BgaFrameworkStubs.php BgaFrameworkStubs.php]

====Create first tests====
Example of tests for Reversi:

'''tests/BoardManagerTest.php'''
<pre>
<?php

declare(strict_types=1);

namespace Tests;

use Bga\Games\Reversi\BoardManager;
use Bga\Games\Reversi\Game;
use PHPUnit\Framework\TestCase;

final class BoardManagerTest extends TestCase
{
public function testGetPossibleMovesOnInitialBoardForBlackPlayer(): void
{
$board = $this->createEmptyBoard(8);
$board[4][4] = 2;
$board[5][5] = 2;
$board[4][5] = 1;
$board[5][4] = 1;

$game = $this->createGame(8);
$boardManager = $this->createBoardManager($game, $board);

$moves = $boardManager->getPossibleMoves(1);

self::assertSame(
[
3 => [4 => true],
4 => [3 => true],
5 => [6 => true],
6 => [5 => true],
],
$moves,
);
}

public function testGetPossibleMovesReturnsEmptyArrayWhenNoMoveExists(): void
{
$board = $this->createEmptyBoard(4);
for ($x = 1; $x <= 4; $x++) {
for ($y = 1; $y <= 4; $y++) {
$board[$x][$y] = 1;
}
}

$game = $this->createGame(4);
$boardManager = $this->createBoardManager($game, $board);

self::assertSame([], $boardManager->getPossibleMoves(2));
}

private function createGame(int $boardSize): Game
{
$game = $this->createStub(Game::class);
$game->method('getBoardSize')->willReturn($boardSize);

return $game;
}

private function createBoardManager(Game $game, array $board): BoardManager
{
return new class ($game, $board) extends BoardManager {
public function __construct(Game $game, private array $board)
{
parent::__construct($game);
}

public function getBoard(): array
{
return $this->board;
}
};
}

private function createEmptyBoard(int $size): array
{
$board = [];
for ($x = 1; $x <= $size; $x++) {
$board[$x] = [];
for ($y = 1; $y <= $size; $y++) {
$board[$x][$y] = null;
}
}

return $board;
}
}
</pre>

'''tests/States/NextPlayerTest.php'''
<pre>
<?php

declare(strict_types=1);

namespace Tests\States;

use Bga\Games\Reversi\BoardManager;
use Bga\Games\Reversi\Game;
use Bga\Games\Reversi\States\NextPlayer;
use PHPUnit\Framework\TestCase;

final class NextPlayerTest extends TestCase
{
public function testReturnsEndScoreWhenNoFreeSquareLeft(): void
{
$game = $this->createGame();
$this->attachBoardManager($game, $this->createBoardManagerStub(0, []));

$state = new NextPlayer($game);

self::assertSame('Bga\\Games\\Reversi\\States\\EndScore', $state->onEnteringState());
}

public function testGivesExtraTimeAndReturnsPlayDiscWhenPlayerCanMove(): void
{
$game = $this->createGameMock();
$game->expects(self::once())
->method('giveExtraTime')
->with(1, null);
$this->attachBoardManager($game, $this->createBoardManagerStub(5, [1 => 4, 2 => 4], [1 => [4 => [3 => true]]]));

$state = new NextPlayer($game);

self::assertSame('Bga\\Games\\Reversi\\States\\PlayDisc', $state->onEnteringState());
}

private function createGame(int $activePlayerId = 1, int $playerAfterId = 2): Game
{
$game = $this->createStub(Game::class);
$game->method('activeNextPlayer')->willReturn($activePlayerId);
$game->method('getPlayerAfter')->willReturn($playerAfterId);

return $game;
}

private function createGameMock(int $activePlayerId = 1, int $playerAfterId = 2): Game
{
$game = $this->getMockBuilder(Game::class)
->disableOriginalConstructor()
->onlyMethods(['activeNextPlayer', 'getPlayerAfter', 'giveExtraTime'])
->getMock();
$game->method('activeNextPlayer')->willReturn($activePlayerId);
$game->method('getPlayerAfter')->willReturn($playerAfterId);

return $game;
}

private function createBoardManagerStub(int $freeSquares, array $discsByPlayer, array $possibleMovesByPlayer = []): BoardManager
{
$boardManager = $this->createStub(BoardManager::class);
$boardManager->method('countFreeSquares')->willReturn($freeSquares);
$boardManager->method('getDiscCountsByPlayer')->willReturn($discsByPlayer);
$boardManager->method('getPossibleMoves')->willReturnCallback(
static fn (int $playerId): array => $possibleMovesByPlayer[$playerId] ?? []
);

return $boardManager;
}

private function attachBoardManager(Game $game, BoardManager $boardManager): void
{
$game->boardManager = $boardManager;
}
}
</pre>

====Running the tests====
Run the tests using
phpunit

If you want to run a single test file
phpunit tests/BoardManagerTest.php

If you want to run a single test
phpunit --filter testGivesExtraTime

<i>If you came here from Reversi Tutorial, go back to it https://en.doc.boardgamearena.com/Tutorial_reversi#Optional:_add_unit_tests</i>

== Play testing on studio ==

To play test on studio you can use your test accounts dev0... dev9. You can give some of these account to other people just make sure you change the password.
You should not encourage other people who are not developers to create studio account, this is against bga policy.

Template:Studio Framework Navigation

2026-04-09T23:44:43Z

Victoria La:

<div class="studio-framework-navigation" style="float: right; width: 300px; border: solid #000 1px; padding: 1em; margin-left: 1em; background: #fff;">

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game File Reference'''</center></div>

<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''[[Studio file reference|Overview]]'''</center></div>

* [[Game database model: dbmodel.sql|<b>dbmodel.sql</b>]] - database model
* [[Game fonts: fonts directory|<b>fonts/</b>]] - game fonts
* [[Game meta-information: gameinfos.inc.php|<b>gameinfos.inc.php</b>]] - meta-information
* [[Options and preferences: gameoptions.json, gamepreferences.json|<b>gameoptions.json</b>]] - game options & user preferences
* [[Game art: img directory|<b>img/</b>]] - game art
* [[Game_metadata_manager|<b>Game Metadata Manager</b>]] - tags and metadata media
* [[Game material description: material.inc.php|<b>material.inc.php</b>]] - static data
* <b>misc/</b> - studio-only storage
* <b>modules/</b> - additional game code
* [[Game sounds: sounds directory|<b>sounds/</b>]] - game sounds
* [[State classes: State directory|<b>States/</b>]] - State classes
* [[Your game state machine: states.inc.php|<b>states.inc.php</b>]] - state machine
* [[Game statistics: stats.json|<b>stats.json</b>]] - statistics
* [[Players actions: yourgamename.action.php|X.<b>action.php</b>]] - player actions
* [[Game interface stylesheet: yourgamename.css|X<b>.css</b>]] - interface stylesheet
* [[Main game logic: Game.php|<b>Game.php</b>]] - main logic
* [[Game interface logic: Game.js|<b>Game.js</b>]] - interface logic
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X.<b>view.php</b>]] - dynamic game layout
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl|X_X.<b>tpl</b>]] - static game layout
<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Useful Components'''</center></div>

'''Official'''

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[PlayerCounter_and_TableCounter|PlayerCounter and TableCounter]]: PHP components to manage counters.
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
* [[BgaAnimations|bga-animations]] : a JS component for animations.
* [[BgaCards|bga-cards]] : a JS component for cards.
* [[BgaDice|bga-dice]] : a JS component for dice.
* [[BgaAutofit|bga-autofit]] : a JS component to make text fit on a fixed size div.
* [[BgaScoreSheet|bga-score-sheet]] : a JS component to help you display an animated score sheet at the end of the game.

'''Unofficial'''

* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
* [[Common board game elements image resources]]
* [[Using AI for BGA game development]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Game Development Process'''</center></div>

* [[First steps with BGA Studio]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Tutorial reversi]]
* [[Tutorial hearts]]
* [[BGA Studio Guidelines]]
* [[BGA game Lifecycle]]
* [[Pre-release checklist]]
* [[Post-release phase]]
* [[Help|Player Resources]] - add player help/rules to your game page

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Guides for Common Topics'''</center></div>

* [[Translations]] - make your game translatable
* [[Game replay|Game Replay]]
* [[Your game mobile version|Mobile Users]]
* [[Compatibility]]

<br>
-----
<div style="font-weight:bold;font-size:1.2em;margin-top:0.3em;line-height:1.6;padding-top:0.5em;"><center>'''Miscellaneous Resources'''</center></div>

* [[Studio FAQ]]
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
* [[Studio logs]] - Instructions for log access
* [[Practical debugging]] - Tips focused on debugging
* [[Troubleshooting]] - Most common "I am really stuck" situations
* [https://studio.boardgamearena.com/bugs Studio Bugs] - Reports against Studio itself (not BGA!)
</div>

Using AI for BGA game development

2026-04-09T23:44:32Z

Victoria La:

Using AI for BGA game development

2026-04-07T14:11:46Z

Victoria La:

Studio

2026-04-07T13:54:38Z

Victoria La: /* BGA Studio user guide */

{{Studio_Framework_Navigation}}

[[File:Bga_studio_small.jpg|frameless|300px]]

Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the latest information available.

__TOC__

== What is Board Game Arena Studio? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptations using the Board Game Arena platform.

It is open to any gamer with software development skills :)

BGA Studio website: https://studio.boardgamearena.com

Original announcement on BGA forum: https://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

Why, how, what... to start discovering BGA Studio, we prepared 5 "powerpoint" presentations for you:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game] (or [http://en.doc.boardgamearena.com/images/5/58/1-why-developing.pdf ‎Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena] (or [http://en.doc.boardgamearena.com/images/1/1e/2-8-steps-to-realize.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] (or [http://en.doc.boardgamearena.com/images/7/79/3-thebgaframework.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine] (or [http://en.doc.boardgamearena.com/images/9/98/4-gamestates.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] (or [http://en.doc.boardgamearena.com/images/7/76/5-guidelines.pdf ‎Download as PDF])

== How to join the BGA developer team? ==

Please see this page: [[How to join BGA developer team?]]

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

Then, you should checkout the [[First steps with BGA Studio]] to make sure that runs fine.

After that, we strongly advise you to take one of these game creation tutorials:
* [[Tutorial reversi]] ('''recommended''', closest to the actual BGA implementation and maintained by the BGA team) - an abstract strategy game played on an 8×8 uncheckered board for 2 players
* [[Tutorial hearts]] - a card game for 4 players

Then start editing files and see what happens! ;)

Once you're done with tutorials, you can start a real game (or join existing project)
* [[Create a game in BGA Studio: Complete Walkthrough]]

If you have any questions, please check out the [[Studio FAQ]] or [[Contact BGA Studio]].

To search wiki pages on studio enter this text in search bar:
"Category:Studio" white rabbit
That is if you want to search for white rabbit

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

This part of the documentation focuses on the development framework itself: functions and methods available to build your game.

[[Studio file reference|File structure of a BGA game]]

==== Game logic (Server side) ====

* [[Main game logic: yourgamename.game.php|Main game logic: Game.php]]
* [[State classes: State directory|Your game state classes: States directory]]
* [[Game database model: dbmodel.sql]]
* [[Game material description: material.inc.php]]
* [[Game statistics: stats.inc.php|Game statistics: stats.json]]

==== Game interface (Client side) ====

* [[Game interface logic: Game.js]]
* [[Game art: img directory]]
* [[Game interface stylesheet: yourgamename.css]]
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]
* [[Your game mobile version]]

==== Other components ====

* [[Translations]] (how to make your game translatable)
* [[Options_and_preferences:_gameoptions.json,_gamepreferences.json|Game Options and Preferences]]
* [[Game meta-information: gameinfos.inc.php]]
* [[Game replay]]

=== BGA Studio game components reference ===

Game components are useful tools you can use in your game adaptations.

JS:

* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Anti-Stock]]: Code snippets in vanilla JS/HTML5 to do what stock does (that is if you cannot beat Stock into submission)
* [[BgaAnimations|bga-animations]]: a JS component for animations.
* [[BgaCards|bga-cards]]: a JS component for cards.
* [[BgaDice|bga-dice]]: a JS component for dice.
* [[BgaAutofit|bga-autofit]]: a JS component to make text fit on a fixed size div.
* [[BgaScoreSheet|bga-score-sheet]]: a JS component to help you display an animated score sheet at the end of the game.

PHP:
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...)
* [[PlayerCounter and TableCounter]]: php component to manager counters

=== BGA Studio user guide ===

This part of the documentation is a user guide for the BGA Studio online development environment.

Lifecycle

* [[BGA game Lifecycle]]
* [[BGA Game licenses]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Pre-release checklist]] - Go throught this list if you think you done development
* [[Post-release phase]]

Tools and Advice
* [[BGA Studio Guidelines]]
* [[Tutorials checklist]]
* [[I wish I knew this when I started]] - one liners on most common missed features, mistakes, etc with further doc references
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
** [[Setting up BGA Development environment using VSCode]]
** [[Practical debugging]] - Tips focused on debugging
** [[Testing by developer]]
** [[Studio logs]] - Instructions for log access
** [[Troubleshooting]] - Most common "I am really stuck" situations
* [[Production issues reporting|Production issues reporting tool]]
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
** [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
** [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner
** [[Bots and Artificial Intelligence]] - How to add AI/Bots to the game
** [[Using AI for BGA game development]] - Shared resources about setting up AI agents
* [[BGA Studio Migration Guide]] - Migration tips from older version of studio framework
* [[Studio FAQ]]

Sharing
* [[Common board game elements image resources]] - Dice, meeples, cubes, etc
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links

== Software Versions ==

Versions currently used by BGA framework:

* Dojo Toolkit 1.15 - deprecated, avoid at all cost
* PHP: 8.4
* SQL: MySQL 5.7 (prod) - on studio 8.0
* JS/CSS/HTML: limited by what minimization tools support: [[Game_interface_logic:_yourgamename.js#Javascript_minimization_.28after_July_2020.29|JS minimization]]
* Font Awesome: 4.7 https://fontawesome.com/v4.7/icons/ (available as <code><nowiki><i class="fa fa-clock" /></nowiki></code>)
* Font Awesome: 6.4.0 https://fontawesome.com/v6/search?o=r&m=free (available as <code><nowiki><i class="fa6 fa6-clock" /></nowiki></code>)

=== PHP Extensions Used ===

The following PHP extensions are - as of Apr 1, 2026 - in use in BGA Studio:

Core date libxml openssl pcre sqlite3 zlib ctype curl dom fileinfo filter hash iconv json mbstring SPL session PDO pdo_sqlite standard posix random readline Reflection Phar SimpleXML tokenizer xml xmlreader xmlwriter mysqlnd cgi-fcgi apcu gd gettext gmp mysqli pcntl redis sodium zip memcached Zend OPcache

== Other resources ==

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]

DISCORD chat server/room invite link https://discord.gg/YxEUacY if it does not work check this topic https://forum.boardgamearena.com/viewtopic.php?f=12&t=17403&hilit=discord

Developer BLOGS https://bga-devs.github.io/blog/

BGA Mainsite releases https://en.boardgamearena.com/forum/viewtopic.php?t=23289&start=100

[[Contact BGA Studio]]

[[Category:Studio]]

Using AI for BGA game development

2026-04-07T13:54:28Z

Victoria La: Created page with "tbd"

tbd

Studio

2026-04-07T13:52:14Z

Victoria La: /* Software Versions */

{{Studio_Framework_Navigation}}

[[File:Bga_studio_small.jpg|frameless|300px]]

Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the latest information available.

__TOC__

== What is Board Game Arena Studio? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptations using the Board Game Arena platform.

It is open to any gamer with software development skills :)

BGA Studio website: https://studio.boardgamearena.com

Original announcement on BGA forum: https://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

Why, how, what... to start discovering BGA Studio, we prepared 5 "powerpoint" presentations for you:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game] (or [http://en.doc.boardgamearena.com/images/5/58/1-why-developing.pdf ‎Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena] (or [http://en.doc.boardgamearena.com/images/1/1e/2-8-steps-to-realize.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] (or [http://en.doc.boardgamearena.com/images/7/79/3-thebgaframework.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine] (or [http://en.doc.boardgamearena.com/images/9/98/4-gamestates.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] (or [http://en.doc.boardgamearena.com/images/7/76/5-guidelines.pdf ‎Download as PDF])

== How to join the BGA developer team? ==

Please see this page: [[How to join BGA developer team?]]

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

Then, you should checkout the [[First steps with BGA Studio]] to make sure that runs fine.

After that, we strongly advise you to take one of these game creation tutorials:
* [[Tutorial reversi]] ('''recommended''', closest to the actual BGA implementation and maintained by the BGA team) - an abstract strategy game played on an 8×8 uncheckered board for 2 players
* [[Tutorial hearts]] - a card game for 4 players

Then start editing files and see what happens! ;)

Once you're done with tutorials, you can start a real game (or join existing project)
* [[Create a game in BGA Studio: Complete Walkthrough]]

If you have any questions, please check out the [[Studio FAQ]] or [[Contact BGA Studio]].

To search wiki pages on studio enter this text in search bar:
"Category:Studio" white rabbit
That is if you want to search for white rabbit

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

This part of the documentation focuses on the development framework itself: functions and methods available to build your game.

[[Studio file reference|File structure of a BGA game]]

==== Game logic (Server side) ====

* [[Main game logic: yourgamename.game.php|Main game logic: Game.php]]
* [[State classes: State directory|Your game state classes: States directory]]
* [[Game database model: dbmodel.sql]]
* [[Game material description: material.inc.php]]
* [[Game statistics: stats.inc.php|Game statistics: stats.json]]

==== Game interface (Client side) ====

* [[Game interface logic: Game.js]]
* [[Game art: img directory]]
* [[Game interface stylesheet: yourgamename.css]]
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]
* [[Your game mobile version]]

==== Other components ====

* [[Translations]] (how to make your game translatable)
* [[Options_and_preferences:_gameoptions.json,_gamepreferences.json|Game Options and Preferences]]
* [[Game meta-information: gameinfos.inc.php]]
* [[Game replay]]

=== BGA Studio game components reference ===

Game components are useful tools you can use in your game adaptations.

JS:

* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Anti-Stock]]: Code snippets in vanilla JS/HTML5 to do what stock does (that is if you cannot beat Stock into submission)
* [[BgaAnimations|bga-animations]]: a JS component for animations.
* [[BgaCards|bga-cards]]: a JS component for cards.
* [[BgaDice|bga-dice]]: a JS component for dice.
* [[BgaAutofit|bga-autofit]]: a JS component to make text fit on a fixed size div.
* [[BgaScoreSheet|bga-score-sheet]]: a JS component to help you display an animated score sheet at the end of the game.

PHP:
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...)
* [[PlayerCounter and TableCounter]]: php component to manager counters

=== BGA Studio user guide ===

This part of the documentation is a user guide for the BGA Studio online development environment.

Lifecycle

* [[BGA game Lifecycle]]
* [[BGA Game licenses]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Pre-release checklist]] - Go throught this list if you think you done development
* [[Post-release phase]]

Tools and Advice
* [[BGA Studio Guidelines]]
* [[Tutorials checklist]]
* [[I wish I knew this when I started]] - one liners on most common missed features, mistakes, etc with further doc references
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
** [[Setting up BGA Development environment using VSCode]]
** [[Practical debugging]] - Tips focused on debugging
** [[Testing by developer]]
** [[Studio logs]] - Instructions for log access
** [[Troubleshooting]] - Most common "I am really stuck" situations
* [[Production issues reporting|Production issues reporting tool]]
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
** [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
** [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner
** [[Bots and Artificial Intelligence]] - How to add AI/Bots to the game
* [[BGA Studio Migration Guide]] - Migration tips from older version of studio framework
* [[Studio FAQ]]

Sharing
* [[Common board game elements image resources]] - Dice, meeples, cubes, etc
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links

== Software Versions ==

Versions currently used by BGA framework:

* Dojo Toolkit 1.15 - deprecated, avoid at all cost
* PHP: 8.4
* SQL: MySQL 5.7 (prod) - on studio 8.0
* JS/CSS/HTML: limited by what minimization tools support: [[Game_interface_logic:_yourgamename.js#Javascript_minimization_.28after_July_2020.29|JS minimization]]
* Font Awesome: 4.7 https://fontawesome.com/v4.7/icons/ (available as <code><nowiki><i class="fa fa-clock" /></nowiki></code>)
* Font Awesome: 6.4.0 https://fontawesome.com/v6/search?o=r&m=free (available as <code><nowiki><i class="fa6 fa6-clock" /></nowiki></code>)

=== PHP Extensions Used ===

The following PHP extensions are - as of Apr 1, 2026 - in use in BGA Studio:

Core date libxml openssl pcre sqlite3 zlib ctype curl dom fileinfo filter hash iconv json mbstring SPL session PDO pdo_sqlite standard posix random readline Reflection Phar SimpleXML tokenizer xml xmlreader xmlwriter mysqlnd cgi-fcgi apcu gd gettext gmp mysqli pcntl redis sodium zip memcached Zend OPcache

== Other resources ==

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]

DISCORD chat server/room invite link https://discord.gg/YxEUacY if it does not work check this topic https://forum.boardgamearena.com/viewtopic.php?f=12&t=17403&hilit=discord

Developer BLOGS https://bga-devs.github.io/blog/

BGA Mainsite releases https://en.boardgamearena.com/forum/viewtopic.php?t=23289&start=100

[[Contact BGA Studio]]

[[Category:Studio]]

Bugsclarification galacticcruise

2026-04-07T13:48:52Z

Victoria La:

Please make sure you understand the rules before filing the bug reports.

There are some special limitation of digital adaptation described here
https://en.doc.boardgamearena.com/Gamehelpgalacticcruise#BGA_Limitations_and_special_rules

The following bugs/issues are part of BGA framework and cannot be fixed in the game (so you can submit them as "mainsite" bug reports, but not game reports)
* ELO points
* Rule on when you can concede the game
* Negative score for solo mode
* Networking issues or BGA servers down
* Graphics files that cannot be loaded or partially loaded (this is actually your internet provider)
* Turn un-synchronization (your think its not your turn but other people think it is)

BGA Studio Guidelines

2026-04-06T17:55:56Z

Victoria La:

{{Studio_Framework_Navigation}}

= BGA Studio Guidelines (UX/UI) =

Originally From: https://www.slideshare.net/boardgamearena/bga-studio-guidelines

New Guidelines (Draft): https://bga.li/Vfd9 but we're still improving it as devs gives us a lot of feedbacks. Don't hesitate to do so to studio@boardgamearena.com

== Summary ==
These guidelines are here to help you to make sure that the players, the game publisher and the game author are going to enjoy your adaptation of the game. We created these guidelines based on our personal experience (which includes many mistakes along the way) implementing a lot of games on BGA platform. Don't hesitate to contact us if you feel uncomfortable with one of these guidelines in some particular context with your game: these guidelines are here to help and not to prevent you to do smart things, and have fun while programing your game ;)

== Why guidelines? ==
More and more game publishers are choosing Board Game Arena for their game adaptations because the quality of these adaptations is high.
If we want to continue to have nice games in the future, we have to make sure that every game published in the BGA platform is matching the quality standards of BGA.
These guidelines are here to help you to make your game easy to use by BGA players, and to make sure its going to be validated by the game publisher.

Can this guidelines be violated/not followed? Yes, but the more you diverge the more chances this game won't be approved by publisher of BGA. Both BGA team and publisher would have a veto on the posting game to production, so you should think twice about this.

== General guidelines ==
The 3 main important guidelines
* If a player knows the real board game, they should be able to play your adaptation with no learning.
* Fidelity to the original game is an absolute requirement.
* Don't try to create a video game: make your game interface as close as possible to how the original board game looks like.

== Game layout ==
[[File:Bgalayout.png|frameless|900x900px]]

=== Game layout elements ===

The game develop must obey the basic rules on bga game layout
* BGA header, BGA footer and chat area are reserved for framework use - game developer shall never place any design elements there nor hide or relocate them.
* Studio tools area only appears in studio. Game shall never place any extra dev tools visible to player in production (anywhere), but this area can and used for extra tools when game runs on studio servers. For the sake of game testers its best to avoid placing studio only tools anywhere else (i.e. when bga review game in studio before granting alpha status)
* Game must use game area to place main game elements there
* Game may modify status bar, player panels and gamelog area with some restrictions (but they never can be hidden or relocated by the game)

=== L-1 Layout arrangement ===

* Game should work on any aspect ratio, showing all information the active player needs for their current turn (New: 2026.01)
* Center the game for all devices, ensuring it fits on large screens (New: 2026.01)
* Leave a "no action" margin zone around the game area (allows users to deselect, scroll on phones) (New: 2026.01)
* No in-game branding: do not include logos or branding components not explicitly part of the game (New: 2026.01)
* Layout mantra: Central = shared actions, Top/Bottom = global info, Panels = private resources (New: 2026.01)
* Stack elements vertically for mobile, avoid endless horizontal scroll (New: 2026.01)
* Always accessible without popups: Score, whose turn, objectives (New: 2026.01)

=== L-2 Don't hide game elements ===

Many board games have a lot of material to display, and computer screens are sometimes too small.
But you are lucky: your game will be on a webpage with a scrolling functionality.
Basically, you always have some more space available.
Don't hide game elements behind menus, submenus, dialogs, etc, but display them directly on the main page.

Tips: you can use HTML anchor link to jump between the different elements of the page if the page height is very big.

Examples:

In Amyitis, characters cards are elements you don't have to check all the time. Thus, we placed them at the bottom of the page and you have to scroll to see them.

In Madeira, additional game board are shown at the bottom, but when player needs to use it it moved up.

Rule:
* If real game has visible elements on the table it should be visible on the main screen or player panels on the right

Exceptions:
* Showing counts of same elements is sufficient for elements like resources, trackers, vp, etc.
* For decks which can be inspected it permitted to show them on demand
* If some games you can cut off score track and replace with BGA scoring (stars), but keeping it will look nicer (but you have to keep track of score on it as well)
* Its not necessary to show helper cards such as turn overview or scoring overview. It is nice if you can incorporate that as well, but in most cases, '''such elements should not be displayed by default''' (as space should be given in priority to the game itself), and should be made available by '''a gray "Player aid" button (or help icon)''' displaying a popup when clicked, like for example in Marco Polo or Terra Mystica.
* This rule does not apply to additional player controls such as settings and prefrences.

=== L-3 Make it fluid ===

BGA game interface is "fluid". It means the interface width can vary in order to use extra space on the screen when available.
HTML and CSS give us a lot of possibilities to adapt a web content to a given browser width.
You have to use HTML and CSS:
* To allow players owning a big screen to enjoy the game comfortably without scrolling the page.
* To allow players with a screen of just 1024px

Tips: for each element of the game, answer this question "how many times during a game do I need to check/use this element?". Less frequently used elements can be placed below.
You can listen on display resize in JS to do more sophisticated layouts.

Examples:

Caylus: when we have a 1024px small width to play the game – even if they have to screen, available buildings are placed scroll on the the right and below the board.
On larger screen, these tiles are placed on the right of the board. This is a very basic usage of "float:left" CSS property.

=== L-4 Use whiteblocks ===
White blocks are '''div''' HTML element with the '''whiteblock''' class (white and transparent background). This is the recommended way to gather game elements together in your game interface when they are not directly on a board. Whiteblocks helps you to organize the space in order it can be easily understood by players.

If game contains individual player boards with distinct colors or marking you don't need these boards inside the whiteblock.

''Tips: you can use a '''h3''' title inside the whiteblock to help players to understand what is inside or to who it belongs.''

In The Year of the Dragon game interface, with whiteblocks and h3 titles /picture/

=== L-5 Use player panels ===

BGA players are used to look at player panels when they need an information about a player.
Using player panels can allow you to save a lot of space on the main game space. In general, the following information is placed in the player panel:
* Players resources (i.e. small game elements the player is keeping in front of him in the real game).
* Summary information about player (i.e. number of cards in hand, number of cards played...).
* "First player" token.
* Score.

Player panels in Seasons. /picture/ A lot of useful information can fit into these small spaces :)

Rule:
* You must always use the standard BGA score counter (with the star) to show score. Players are used to check this counter to see who is winning the game.

Exception:
* In some cases score is not revealed during the game by design, in this case its permitted to show ? or - (minus) in the place of score.
* In some cases its permitted to replace star icon with icon representing VP in this game

Player panel limits (New: 2026.01):
* For a 4-player game on mobile, player panels should not occupy more than 1/4 of the screen
* Panels should NOT contain extra settings, redundant info, or side information
* Panels may offer HTML anchor shortcuts to other components on the main screen

=== L-6 Use status bar actions ===

Its a good practice is to use a status bar action buttons. For example if one of the player actions to pick up the cards, there is no really a place to click in game are, so just add button "Pick up cards".
Don't try to place some artificial action icon in your game area that will be useless 95% of the time: it takes space and makes the interface more complex to understand.

Status bar actions in Tobago /picture/

Rule:
* If there is no game element you can "click" on to perform an action, place action button on the status bar

Exception:
* On the other hand some games have "At anytime actions", such as "At any time you can trade 2 seals for one resource of any kind". If you place it on the status bar - it will be always there which will clutter it. It is best to either find a game element you can attach it to or place it on "current" player panel (its a reserved area at the bottom of main player panel).
* You can add button to the status bar even there is active element on the board - that simplifies the user actions
* Avoid too many buttons on the status bar. If you have 10 buttons it is probably pushing it...

Rule:
* Do not use exotic colors for buttons. Use default colors such as blue, while and red (defined by API)

Action bar limits (New: 2026.01):
* Limit action bar to maximum 4 buttons + context to prevent overflow on mobile
* Action bar should NOT replace board component actions - prioritize clicking on game elements
* Main awaited actions should be centered in the action bar
* Cancel/undo/remove actions belong on the right side of the action bar
* Impossible or unauthorized actions (greyed out) can be shown as secondary elements
* "Round in progress" information should be displayed on the table itself, not in action bar

=== L-7 Popups (New: 2026.01) ===

* Automatic popups are forbidden (reserve for tutorials only)
* Any popup blocking the game flow is forbidden
* If popups must be used, they must be skippable (click, touch, or timed)
* Turn confirmation and such should be handled as states
* Extra data be just added at the bottom of the page and you can provide extra navigation. Or if this is data on demand like display the discard content can show on top the board but button to hide

=== L-8 Zoom controls (New: 2026.01) ===

* Avoid custom zoom buttons - browsers already provide zoom (Ctrl+mousewheel, pinch-to-zoom)
* Zoom buttons often indicate a deeper layout problem - design so zoom isn't needed
* If zoom is necessary (large boards, text-heavy cards): use +/- buttons and a home/reset button
* The default view must be perfectly playable without zoom
* Think of zoom as last resort, not a requirement

== Game usability ==

=== U-1 Use tooltips ===

With BGA Studio its very easy to associate a tooltip on any element of the game. Each time this is possible: add a tooltip to explain to the players:
* What is this game element?
* What happens if I click on it?
However, tooltips should NOT be used to display dynamic information about the current game to save space on the game interface.
Typically, regular players should be able to play with no tooltips.
However you can display some dynamic stuff if it's available otherwise but just annoying to calculate. For example in Lewis and Clark author asked to put
tooltips of how many river space available ahead of explorer.
If you need to show user why they cannot interact with element show errors instead (when clicking on it).

Tips: you can place any HTML element in tooltips. So you can make them as rich and beautiful as you need :)

* Rule: Do not use exact same image of card or token in tooltip, you can make it bigger for readability or remove the image and just leave the text
* Rule: Do not use same iconography as in original object - use TEXT describing what icon means (they already see the icon on the board, no need to show the icon again)

=== U-2 Use left click only ===
Rule:
* The whole game should be playable with only simple left button mouse click.
* Exception: Word based games can use keyboard/text input

Rule:
* Context menus should not be used (no exceptons)

Rule:
* Drag-n-drop should be avoided
* Exceptions:
** Permitted if same can be achieved without it (make a click based alternative)
** Permitted for non-essential functionality (like re-arranging cards in hand)

Rule:
* Mouse icon must change on clickable elements (''cursor:pointer'' CSS property).

=== U-3 Make your interface intuitive ===
If your testers have different opinions about how to trigger some game action, maybe
the best is to make several options possible for this game action. In the case there is a complex action to do by the player (i.e. select some cards, then click on an action button), design your error messages in order they can guide the player (i.e. "select some cards first").

Tips: For complex games, it is simple and useful to highlight the area of the interface where player should focus his attention (using onEnteringState/onLeavingState and CSS class, i.e. 'active_slot').

The Boss: when a player clicks on a card with no selected cubes, the interface tells us to select some cube first.

=== U-4 Use the gamelog ===

Use the game log to output information about the move.
Players are not always in front of the game page when their opponents are making their moves.
In addition, the computer manipulates game elements faster than you usually do with the real board game and even regular players can get behind of what happened sometimes.
You should be able to understand the "game story" by reading the game log.

Rule:
* Every important move should be reflected in gamelog

Gamelog best practices (New: 2026.01):
* Show every major action (card plays, moves, resource changes, eliminations)
* Use icons, colors, or formatting so actions can be scanned quickly
* Any graphic components in logs must have alternative text
* Reduce visual noise: group small simultaneous actions into one-liners
* Always specify who acted and what changed (e.g., "Raphaël drew 2 cards" not just "2 cards drawn")
* Automated actions should be clearly displayed in logs too
* For async games, logs are essential - they let returning players catch up instantly

=== U-5 Tell players about automatic actions ===
Very often, during a game you are in a situation where:
* Only one action is possible for the activeplayer, or
* A series of action has to be done (according to the rules) without any players actions.
In these situation, you must or you may trigger these actions automatically.
In any case, you must make sure that players understand what is happening, otherwise they will probably report a bug.

Stone Age: people are fed automatically at the end of the turn, but players can always see what happened exactly in the gamelog.

* Use the game log to trace all actions performed automatically.
* Use synchronous notifications handlers to slow down the execution of automatic actions, so that players can understand what is happening.
* Use preferences to opt-in or opt-out of auto-actions (some may be very important such as Pass)

=== U-6 Confirmations, cancel and undo ===

==== Avoid move confirmations ====
As a rule of thumb, don't require move confirmation. Confirming a move slows down the user interface and thus, the game flow. You can allow a player to confirm a move if this is a very critical step in a game, and if it is possible to trigger an action by accident. If client interactions are very complex and allow cancellation, the final move can be confirmed with a "Done" button.

''Hawaii'': Ending a turn is a critical action that happens only 5 times per player in a game. In this case, it is acceptable (and a good idea) to have a confirmation dialog.

''Hive'': Each move has to be confirmed with click on the location because it is very easy to click by accident.

''Russian Railroads'': Each move involves multiple interactions and can contains dozens of subactions. When the player is done "planning" they presses a "Done" button to submit the move to the server.

''Race for the Galaxy'': There is a card that allows players to draw two cards and discard one card before the Development phase. This requires confirmation when the player selects a development card to discard, as they often means to build that development card instead.

==== Cancel a move ====
Most players want to have moves cancelled or undone. Use the following rules to implement it:
* If any information is revealed which was not known before the action is completed - You CANNOT cancel it.
* If this is the end of active player action, and it is another player's turn - You CANNOT cancel it
** Exception: You can undo action of one player if this is multiactive state and not all players are done
* If during a player's turn multiple actions are required but don't violate the above two rules - You CAN cancel/undo it. i.e. A user picks cubes and drops on a building. Selecting the cubes and building - are two actions, so user should be able to cancel taking cube.
This can be implemented using client side states, so cancelling is easy by restoring last server state.

==== Undo philosophy (New: 2026.01) ====
* Avoid unnecessary undo buttons - they often signal a confusing or error-prone interface
* Undo multiplies validation steps (select, confirm, undo, confirm again) slowing the game
* Prefer timed confirmation buttons (5-8 seconds) over allowing undos at every step
* Prefer a single "Restart Turn" option over multiple undo buttons for each micro-action
* Only propose "Undo" when a player's turn consists of more than 2 actions
* If players regularly misclick, improve the layout or interaction design instead of adding undo
* Undo should be a last-resort safety net, not a primary mechanic

=== U-7 Translatable interface ===
With BGA its very easy to translate your game in any language, using BGA collaborative translation system. Check [[Translations]] to learn how to declare your strings so that every message in your code can be managed by the internationalization system.

Rule:
* All language specific strings must be translatable.

=== U-8 Use interactive elements ===

Interactive elements are tiles, cubes or board areas user can click on to perform an action. The following guidance apply:
* If user click on interactive element either action happens or user get a error message. Try to process error message of client side and not send to server for simple errors, such as player is not active. Please be very specific why user cannot interact with element, i.e.
** This is not your turn
** You cannot build this building because you don't have enough resources
** To select this card you have to select resource first
If you cannot make errors for all elements at least tooltip should explaining when it interactive vs not

Rule: Every game element should give an explicit error message if clicked at the wrong moment rather than staying silent

Rule: When user can click on element during their turn it should be highlighted if possible (or non-active element de-highlighted in some way)

Forbidden actions display (New: 2026.01):
* Actions that cannot currently be performed should be shown as greyed out/disabled
* This lets players see the action exists but understand it's not available now
* However: if an action is never relevant in the current context, do not show a disabled button
* Balance: let players know which actions are part of the game without UI clutter

Error feedback best practices (New: 2026.01):
* Use visual feedback for failed actions: short shake animation, grey-out effect, or tooltip
* Provide concise plain-text explanations like "You don't have enough resources"
* Use accessible indicators - do not rely on color alone (pair with icons or text)
* Every failed action must give a reason immediately

Hightlighting guidelines:
* Apply a class to all active/selectable element, i.e. class can be "selectable", "active_slot", "interactive"
* An CSS element with this class can have special rules, i.e
** outline (use outline, do not use "border" as this changes sizing)
** OR shadow/glow - use box-shadow or filter: drop-shadow for non-standard tokens
** recommended color - white, yellow or blue. Do not use red - this is indication of error rather than prompt for action
** change mouse cursor to action cursor, i.e. cursor: pointer

De-highlighting guidelines:
* Only use this strategy when there are less inactive element than active
* Apply a class to all non-interactive element, such as "non-interactive"
* In css set special rules
** opacity:0.7
** OR filter:contrast(0.6) or grayscale
* change cursor, i.e. cursor: not-allowed

Rule: If state prompt replaces the interaction with a game element but elements are also visible in the game area its better to let player use either button or element (i.e. player can press a button OR they can click on element on the board)
** Example: In Lewis & Clark game offers gain resources via buttons on state prompt, but user can also click on cubes in supply to do the same action

== Feedback ==

=== F-1 Animate moving elements ===
If real game have some elements moving during the game it should also animate in your adaptation
* User gets a resource - move a resource from main board to user mini board
* User buys a card - move card from main display to user board
* User draw a card which is revealed on the display - move card from deck to display, maybe add flippy animation to turn it face up (that requires 3d transformations - that is bonus)

It is also nice to animation points or coin collection from specific region of the board (even points collection is not normally visible).

Don't need to overdo animation - its not first player shooter

Animation timing (New: 2026.01):
* Regular animation duration: 0.5 seconds - fast enough to be seen but not blocking flow
* Maximum animation duration: 0.8 seconds - keeps the pace quick, prevents frustration in long games
* Don't animate trivial or repetitive updates - batch multiple small gains into one clear effect
* Avoid excessive bouncing, glowing, or looping animations that distract from game state
* Use animation as visual explanation: show what moved, where it went, why it matters

=== F-2 Sound effects (New: 2026.01) ===

* Use volume lower than BGA default - never surprise players with loud audio
* Keep sounds short, sharp, and purposeful - no long looping soundtracks during gameplay
* Sound effects must always be paired with a visual cue (animation, highlight, etc.)
* No action should rely solely on audio to be understood
* Sound is a bonus layer of clarity, not a requirement - game must be fully understandable in silence

=== F-3 Slow down the end of game scoring ===

This is the climax of the game, building up suspense before revealing the winner... Don't make it too quick! :)

It's also very helpful if some end of game scoring animations can show where the points are gained, to help players understand (and trust) the scoring.

To achieve this, you can use synchronous notifications for each step of the scoring to slow down the process, and use this.displayScoring ([[Game_interface_logic:_yourgamename.js#Scoring_animated_display]]) to display a nice points animation in the color of the player over the element of the game granting points for this step of the scoring.

For a practical example of a game adaptation where scoring has been done with this idea in mind, you can check a game replay of Terra Mystica for the final scoring (this link will fast forward you right there: [https://boardgamearena.com/archive/replay/200901-1002/?table=112192856&player=84819187&comments=426;&goto=341 replay scoring])

End game scoring (New: 2026.01):
* Scale end scoring animation to game length (elaborate for long games, quick for short luck-based games)

== Design ==

=== D-1 Typography and fonts (New: 2026.01) ===

* Avoid fancy/decorative fonts - use the default BGA font
* Use clean sans-serif fonts with good line spacing
* Ensure minimum font sizes are readable on small phone screens
* Support screen readers: most interactive elements should have proper text equivalents
* Do not put critical information inside images without alt-text
* All text must be translatable using BGA's translation system - never embed words into graphics
* Support both LTR (left-to-right) and RTL (right-to-left) languages
* Ensure fonts support accents and diacritics (é, ñ, ü, etc.)
* Font colors must meet WCAG AA minimum contrast ratio

=== D-2 Button color standards (New: 2026.01) ===

Rule: Use standard BGA button colors consistently:
* Blue (primary) = Advance the action, confirm, move forward
* Red (alert) = Cancel, undo, stop, or exit
* White/Transparent (secondary) = Optional or side actions not critical to progress
* Grey = Disabled, already completed, or unavailable actions

This color scheme is mandatory for UX consistency across all BGA games.

=== D-3 Sizing and responsiveness (New: 2026.01) ===

* Main play area must remain centered on all devices
* Avoid fixed-width designs - layouts should expand or contract gracefully
* Leave margins around the board for comfort and to avoid misclicks on mobile
* Desktop/tablet: prioritize showing the entire board at once
* Mobile (vertical): stack secondary elements below the main action zone
* Prevent layout breakage when players zoom in/out
* No interactive element (button, token, card, tile) should be smaller than 32x32px
* Ideal tap target size: 40-44px for touchscreens

=== D-4 Background design (New: 2026.01) ===

* Use thematic/modern backgrounds (e.g., a subtle playing mat look) instead of the old wooden floor texture
* Background must never reduce the visibility of game components - prioritize contrast
* Avoid pure flat colors - use slight textures or patterns
* Apply a touch of blur to backgrounds so components remain the visual focus
* Think of the background as the table surface your game lives on - natural, thematic, but not distracting

== Original game representation ==

=== R-1 Use the original art===
The less you are modifying the original art of the game, the better.
Its important for publishers that a board game adaptation looks like the real board game. Sometimes it can be useful to modify some elements of the game to save some space on the screen – but try to avoid it.
Tips: if you have not enough space on the screen, reduce the size of the game elements.
Try to make sure they are recognizable for players who played regularly, and add a tooltip to help beginners to figure out what they are.
Gosu : the original cards are used, with tooltips.

=== R-2 Be careful about player assistance ===
As a rule of thumb, in order to respect the original board games, you should not introduce any player assistance feature.
An assistance must not be introduced if it directly helps the player to figure out if his move is good or bad.
An assistance may be introduced if it can help the player to figure out what moves are available.

Gygès: the assistance shows you available moves, but is not alerting you about stupid moves (like the upper left one).

Note: You can however do a single choice move for a player, i.e passing on a turn if there is nothing a user can do; It's quite annoying to wait on a player to pass, while it's the only action that they can do anyways.

=== R-3 Available information ===
Every information visible by players in the real game should be accessible in the adaptation. Pay attention to some information like the number of cards in the opponents hand, or the number of remaining cards in the deck.
If it is explicitly forbidden to count cards in the discard pile, this information is not available.

== Accessibility ==

=== A-1 Design for all (New: 2026.01) ===

* Don't rely on color alone - pair colors with icons, textures, or shapes for players with color vision deficiencies
* Use proper contrast - minimum ratio of 4.5:1 for text readability
* Keep animations safe - avoid flashing or rapidly alternating visuals
* Label everything - buttons, icons, and interactive elements should include clear text labels or tooltips for screen readers
* Make differences obvious - use bold shapes, clear outlines, and strong contrast rather than subtle shading or color variations

=== A-2 Colorblind-safe design (New: 2026.01) ===

* Add unique shapes, symbols, or outlines to each player color on pawns/tokens
* Place small icons in card corners or add patterns so cards can be recognized without relying on hue
* All text and icons must meet WCAG AA contrast levels
* Use outlines, borders, or contrasting strokes for player colors
* Test player colors against both light and dark backgrounds (avoid yellow text on white)

=== A-3 Tap targets for mobile (New: 2026.01) ===

* Minimum interactive element size: 32×32px
* Ideal size: 40-44px (greatly reduces mis-taps on touchscreens)
* Leave enough spacing between buttons/tokens/cards to prevent accidental hits
* Avoid cramming small icons together - group many options into expandable menus or secondary panels
* When space runs out, allow scrolling areas instead of shrinking components until unusable

=== A-4 Settings and customization (New: 2026.01) ===

* All game settings must be placed in the standard BGA settings menu (not custom menus)
* Provide per-game options only where relevant:
** Animation speed (activated/none)
** Tooltip detail (compact/full)
** Sound effects (on/off)
* Reuse existing BGA controls - never duplicate custom UI for settings

== Game technical quality ==

=== T-1 Don't use exotic stuff ===
BGA Studio provides a set of useful tools to build board games adaptations (i.e. card management, confirmation dialog, tooltips,…).
Use them, and don't use exotic libraries, plugins or tricks.
Why? Because BGA Framework will evolve in the future to provide new features to players, and it could make your game incompatible with the new version.
On the contrary, if you are using standard Haggis using BGA standard card stuff, you will enjoy these enhancements without any effort.
If you feel that you really need some exotic thing: don't hesitate to ask us.

=== T-2 Make sure you can use what you use ===

In particular, do not build your game on top of a technical library without checking that licensing allows you (and BGA) to use it.
If you use a library, make sure first that its license is really open (MIT style). Otherwise, we may have to ask you to rework your code to use another library.
In general, please consider that it's always better to minimize dependencies, so if you can avoid using external libraries, all the better.

=== T-3 Write in (simple) English ===
Some other person may have to look at your code, such as:
* We (the BGA team), who are here to help you if you need us.
* Some other BGA developer wanting to help you.
For all these reasons, your code must be written in English (variables, methods, comments...).
If English is not your mother tongue don't be afraid: the whole idea here is to be understood, not to write an essay :)

=== T-4 Page refresh ===
A page refresh (F5) must allow players to reset the game interface to a stable state at any moment of the game.
BGA Studio framework allows you to do this with the « getAllDatas » PHP method and the « setup » Javascript method.
Note: this « refresh » feature is also quite useful during the development process:)

Refresh continuity (New: 2026.01):
* After refresh, the game must return to the exact same state with no missing or corrupted information
* Restore temporary UI indicators (whose turn it is, pending actions, selected components)
* Server is the source of truth - never rely on client-only memory for critical state
* Do not depend on "session continuity hacks" - BGA servers may disconnect/reconnect players at any time
* A refresh should feel invisible to the player

=== T-5 Private information ===
A private game element must be visible only to the player owning it. It must not be visible by his opponents, by any means.
In particular:
* getAllDatas PHP method must not return any element that are hidden from current player, even if the Javascript « setup » method ignores them.
* you must not send via the « notify->all » function some information that is hidden from one player (use « notify->player » instead).

Hearts: each player is alerted about his new cards using notify->player, and cards from the other players remains secret

=== T-6 Game progression ===
Game progression should be as accurate as possible.
Of course, its not always easy (or even possible) to compute game progression, but a vague approximation is better than nothing.
Stone Age: there are 2 different end game conditions (building cards and civilization cards).
Both are taken into account to increase the accuracy of the game progression.

=== T-7 Game statistics ===
Using BGA Studio you can define a set of statistics for your game. Statistics will be displayed at the end of the game, and help players to figure out why they win/lose a game,
and what they should improve. Try to choose interesting statistics that distinguish the different strategies for your game, in order it can help players to understand their game.

Seasons : statistics

=== T-8 Error handling (New: 2026.01) ===

* Handle disconnects smoothly - anticipate delays and dropped actions without breaking game flow
* Invalid inputs must never crash the game or leave it in a corrupted state
* For developers: provide precise error details in the console
* For players: display short, friendly messages explaining what went wrong and what to do next
* Never expose raw server logs or technical stack traces to end users
* Isolate errors to the affected action - never block the entire table because of one failed request

=== T-9 Endgame and replays (New: 2026.01) ===

* Endgame logs must clearly summarize all major actions that led to the outcome
* Replay mode must feel as clear as the live session
* No blocking popups during replays - they should flow smoothly
* Animations must be compatible with replays - playable at minimum speed and skippable
* Logs and highlights must stay in sync with each replayed action

=== T-10 Namespace recommendations ===
Your game is not working in complete isolation, it's included in a page with a lot of elements around (header, footer, logs, chat, player panels, rankings...)

So you should pay attention to naming your DOM elements, CSS classes and PHP constants / classes in a way specific to your game in order to avoid namespace collisions (for example you use a selector for a "selected" class in your .js, and there is also an element of the framework outside of your game with a selected class).

It's recommended to have:
* a wrapper div around your game zone with an id specific to your game ('yourgamename_playzone' for example) and to use it in any xpath selector of your .js
* a prefix for example a trigram for your game that you append to all the css classes of your game ('yrg_selected' for example).
* a prefix or a namespace for your PHP constants or classes.

Even if everything is working fine today, otherwise your game may break in the future when the framework is updated.

You should not use any global variables (window scope) in your Javascript files. If you need something to be accessible globally, then you should use <code>window.gameui</code>. You could even make a <code>window.gameui.globals = {}</code> object to contain any global variables.

= BGA Studio Guidelines (Source Code) =
Make your code as easy to read and understand as possible : clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

== Front (JS) code ==

=== Generated code ===
Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

=== Templates ===
Use of .tpl file and view.php is deprecated and forbidden for new projects.

== Back (PHP) code ==
Game name and option names should be Capitalized.

=== Framework functions ===

===== Undocumented functions =====
Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

==== Function override ====
Do not override framework functions. Use a wrapper instead.

'''Bad :'''

<pre>
public function getPlayerNameById($player_id) { // same name as the framework function = override
if ($player_id == 0) {
return 'Automata';
} else {
return parent::getPlayerNameById($player_id);
}
}
</pre>

'''Better :'''
<pre>
public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
if ($player_id == 0) {
return 'Automata';
} else {
return $this->getPlayerNameById($player_id);
}
}
</pre>

==== State functions ====
States functions should be prefixed “st”

Args functions should be prefixed “arg”

Action functions should be prefixed “act”

=== Namespacing ===
The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <code><mygame>/PowerCard/PowerCardManager.php</code> and start like this :

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\<mygame\PowerCard;
class PowerCardManager {
</pre>

=== Other ===
.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function must check any input. To avoid code duplication, they can use the arg function.

''Example :''

<pre>
$args = $this->argPlayCards();
if (!in_array($cardId, $args[‘selectableCardsIds’]) { throw new \BgaUserException(...); }
</pre>

Don’t use `@` to ignore the errors of a function call.

[[Category:Studio]]

BGA Studio Guidelines

2026-04-06T17:44:00Z

Victoria La: /* L-1 Layout arrangement */

{{Studio_Framework_Navigation}}

= BGA Studio Guidelines (UX/UI) =

Originally From: https://www.slideshare.net/boardgamearena/bga-studio-guidelines

New Guidelines (Draft): https://bga.li/Vfd9 but we're still improving it as devs gives us a lot of feedbacks. Don't hesitate to do so to studio@boardgamearena.com

== Why guidelines? ==
More and more game publishers are choosing Board Game Arena for their game adaptations because the quality of these adaptations is high.
If we want to continue to have nice games in the future, we have to make sure that every game published in the BGA platform is matching the quality standards of BGA.
These guidelines are here to help you to make your game easy to use by BGA players, and to make sure its going to be validated by the game publisher.

Can this guidelines be violated/not followed? Yes, but the more you diverge the more chances this game won't be approved by publisher of BGA. Both BGA team and publisher would have a veto on the posting game to production, so you should think twice about this.

== General guidelines ==
The 3 main important guidelines
* If a player knows the real board game, they should be able to play your adaptation with no learning.
* Fidelity to the original game is an absolute requirement.
* Don't try to create a video game: make your game interface as close as possible to how the original board game looks like.

== Game layout ==
[[File:Bgalayout.png|frameless|900x900px]]

=== Game layout elements ===

The game develop must obey the basic rules on bga game layout
* BGA header, BGA footer and chat area are reserved for framework use - game developer shall never place any design elements there nor hide or relocate them.
* Studio tools area only appears in studio. Game shall never place any extra dev tools visible to player in production (anywhere), but this area can and used for extra tools when game runs on studio servers. For the sake of game testers its best to avoid placing studio only tools anywhere else (i.e. when bga review game in studio before granting alpha status)
* Game must use game area to place main game elements there
* Game may modify status bar, player panels and gamelog area with some restrictions (but they never can be hidden or relocated by the game)

=== L-1 Layout arrangement ===

* Game should work on any aspect ratio, showing all information the active player needs for their current turn (New: 2026.01)
* Center the game for all devices, ensuring it fits on large screens (New: 2026.01)
* Leave a "no action" margin zone around the game area (allows users to deselect, scroll on phones) (New: 2026.01)
* No in-game branding: do not include logos or branding components not explicitly part of the game (New: 2026.01)
* Layout mantra: Central = shared actions, Top/Bottom = global info, Panels = private resources (New: 2026.01)
* Stack elements vertically for mobile, avoid endless horizontal scroll (New: 2026.01)
* Always accessible without popups: Score, whose turn, objectives (New: 2026.01)

=== L-2 Don't hide game elements ===

Many board games have a lot of material to display, and computer screens are sometimes too small.
But you are lucky: your game will be on a webpage with a scrolling functionality.
Basically, you always have some more space available.
Don't hide game elements behind menus, submenus, dialogs, etc, but display them directly on the main page.

Tips: you can use HTML anchor link to jump between the different elements of the page if the page height is very big.

Examples:

In Amyitis, characters cards are elements you don't have to check all the time. Thus, we placed them at the bottom of the page and you have to scroll to see them.

In Madeira, additional game board are shown at the bottom, but when player needs to use it it moved up.

Rule:
* If real game has visible elements on the table it should be visible on the main screen or player panels on the right

Exceptions:
* Showing counts of same elements is sufficient for elements like resources, trackers, vp, etc.
* For decks which can be inspected it permitted to show them on demand
* If some games you can cut off score track and replace with BGA scoring (stars), but keeping it will look nicer (but you have to keep track of score on it as well)
* Its not necessary to show helper cards such as turn overview or scoring overview. It is nice if you can incorporate that as well, but in most cases, '''such elements should not be displayed by default''' (as space should be given in priority to the game itself), and should be made available by '''a gray "Player aid" button (or help icon)''' displaying a popup when clicked, like for example in Marco Polo or Terra Mystica.
* This rule does not apply to additional player controls such as settings and prefrences.

=== L-3 Make it fluid ===

BGA game interface is "fluid". It means the interface width can vary in order to use extra space on the screen when available.
HTML and CSS give us a lot of possibilities to adapt a web content to a given browser width.
You have to use HTML and CSS:
* To allow players owning a big screen to enjoy the game comfortably without scrolling the page.
* To allow players with a screen of just 1024px

Tips: for each element of the game, answer this question "how many times during a game do I need to check/use this element?". Less frequently used elements can be placed below.
You can listen on display resize in JS to do more sophisticated layouts.

Examples:

Caylus: when we have a 1024px small width to play the game – even if they have to screen, available buildings are placed scroll on the the right and below the board.
On larger screen, these tiles are placed on the right of the board. This is a very basic usage of "float:left" CSS property.

=== L-4 Use whiteblocks ===
White blocks are '''div''' HTML element with the '''whiteblock''' class (white and transparent background). This is the recommended way to gather game elements together in your game interface when they are not directly on a board. Whiteblocks helps you to organize the space in order it can be easily understood by players.

If game contains individual player boards with distinct colors or marking you don't need these boards inside the whiteblock.

''Tips: you can use a '''h3''' title inside the whiteblock to help players to understand what is inside or to who it belongs.''

In The Year of the Dragon game interface, with whiteblocks and h3 titles /picture/

=== L-5 Use player panels ===

BGA players are used to look at player panels when they need an information about a player.
Using player panels can allow you to save a lot of space on the main game space. In general, the following information is placed in the player panel:
* Players resources (i.e. small game elements the player is keeping in front of him in the real game).
* Summary information about player (i.e. number of cards in hand, number of cards played...).
* "First player" token.
* Score.

Player panels in Seasons. /picture/ A lot of useful information can fit into these small spaces :)

Rule:
* You must always use the standard BGA score counter (with the star) to show score. Players are used to check this counter to see who is winning the game.

Exception:
* In some cases score is not revealed during the game by design, in this case its permitted to show ? or - (minus) in the place of score.
* In some cases its permitted to replace star icon with icon representing VP in this game

Player panel limits (New: 2026.01):
* For a 4-player game on mobile, player panels should not occupy more than 1/4 of the screen
* Panels should NOT contain extra settings, redundant info, or side information
* Panels may offer HTML anchor shortcuts to other components on the main screen

=== L-6 Use status bar actions ===

Its a good practice is to use a status bar action buttons. For example if one of the player actions to pick up the cards, there is no really a place to click in game are, so just add button "Pick up cards".
Don't try to place some artificial action icon in your game area that will be useless 95% of the time: it takes space and makes the interface more complex to understand.

Status bar actions in Tobago /picture/

Rule:
* If there is no game element you can "click" on to perform an action, place action button on the status bar

Exception:
* On the other hand some games have "At anytime actions", such as "At any time you can trade 2 seals for one resource of any kind". If you place it on the status bar - it will be always there which will clutter it. It is best to either find a game element you can attach it to or place it on "current" player panel (its a reserved area at the bottom of main player panel).
* You can add button to the status bar even there is active element on the board - that simplifies the user actions
* Avoid too many buttons on the status bar. If you have 10 buttons it is probably pushing it...

Rule:
* Do not use exotic colors for buttons. Use default colors such as blue, while and red (defined by API)

Action bar limits (New: 2026.01):
* Limit action bar to maximum 4 buttons + context to prevent overflow on mobile
* Action bar should NOT replace board component actions - prioritize clicking on game elements
* Main awaited actions should be centered in the action bar
* Cancel/undo/remove actions belong on the right side of the action bar
* Impossible or unauthorized actions (greyed out) can be shown as secondary elements
* "Round in progress" information should be displayed on the table itself, not in action bar

=== L-7 Popups (New: 2026.01) ===

* Automatic popups are forbidden (reserve for tutorials only)
* Any popup blocking the game flow is forbidden
* If popups must be used, they must be skippable (click, touch, or timed)
* Turn confirmation and such should be handled as states
* Extra data be just added at the bottom of the page and you can provide extra navigation. Or if this is data on demand like display the discard content can show on top the board but button to hide

=== L-8 Zoom controls (New: 2026.01) ===

* Avoid custom zoom buttons - browsers already provide zoom (Ctrl+mousewheel, pinch-to-zoom)
* Zoom buttons often indicate a deeper layout problem - design so zoom isn't needed
* If zoom is necessary (large boards, text-heavy cards): use +/- buttons and a home/reset button
* The default view must be perfectly playable without zoom
* Think of zoom as last resort, not a requirement

== Game usability ==

=== U-1 Use tooltips ===

With BGA Studio its very easy to associate a tooltip on any element of the game. Each time this is possible: add a tooltip to explain to the players:
* What is this game element?
* What happens if I click on it?
However, tooltips should NOT be used to display dynamic information about the current game to save space on the game interface.
Typically, regular players should be able to play with no tooltips.
However you can display some dynamic stuff if it's available otherwise but just annoying to calculate. For example in Lewis and Clark author asked to put
tooltips of how many river space available ahead of explorer.
If you need to show user why they cannot interact with element show errors instead (when clicking on it).

Tips: you can place any HTML element in tooltips. So you can make them as rich and beautiful as you need :)

* Rule: Do not use exact same image of card or token in tooltip, you can make it bigger for readability or remove the image and just leave the text
* Rule: Do not use same iconography as in original object - use TEXT describing what icon means (they already see the icon on the board, no need to show the icon again)

=== U-2 Use left click only ===
Rule:
* The whole game should be playable with only simple left button mouse click.
* Exception: Word based games can use keyboard/text input

Rule:
* Context menus should not be used (no exceptons)

Rule:
* Drag-n-drop should be avoided
* Exceptions:
** Permitted if same can be achieved without it (make a click based alternative)
** Permitted for non-essential functionality (like re-arranging cards in hand)

Rule:
* Mouse icon must change on clickable elements (''cursor:pointer'' CSS property).

=== U-3 Make your interface intuitive ===
If your testers have different opinions about how to trigger some game action, maybe
the best is to make several options possible for this game action. In the case there is a complex action to do by the player (i.e. select some cards, then click on an action button), design your error messages in order they can guide the player (i.e. "select some cards first").

Tips: For complex games, it is simple and useful to highlight the area of the interface where player should focus his attention (using onEnteringState/onLeavingState and CSS class, i.e. 'active_slot').

The Boss: when a player clicks on a card with no selected cubes, the interface tells us to select some cube first.

=== U-4 Use the gamelog ===

Use the game log to output information about the move.
Players are not always in front of the game page when their opponents are making their moves.
In addition, the computer manipulates game elements faster than you usually do with the real board game and even regular players can get behind of what happened sometimes.
You should be able to understand the "game story" by reading the game log.

Rule:
* Every important move should be reflected in gamelog

Gamelog best practices (New: 2026.01):
* Show every major action (card plays, moves, resource changes, eliminations)
* Use icons, colors, or formatting so actions can be scanned quickly
* Any graphic components in logs must have alternative text
* Reduce visual noise: group small simultaneous actions into one-liners
* Always specify who acted and what changed (e.g., "Raphaël drew 2 cards" not just "2 cards drawn")
* Automated actions should be clearly displayed in logs too
* For async games, logs are essential - they let returning players catch up instantly

=== U-5 Tell players about automatic actions ===
Very often, during a game you are in a situation where:
* Only one action is possible for the activeplayer, or
* A series of action has to be done (according to the rules) without any players actions.
In these situation, you must or you may trigger these actions automatically.
In any case, you must make sure that players understand what is happening, otherwise they will probably report a bug.

Stone Age: people are fed automatically at the end of the turn, but players can always see what happened exactly in the gamelog.

* Use the game log to trace all actions performed automatically.
* Use synchronous notifications handlers to slow down the execution of automatic actions, so that players can understand what is happening.
* Use preferences to opt-in or opt-out of auto-actions (some may be very important such as Pass)

=== U-6 Confirmations, cancel and undo ===

==== Avoid move confirmations ====
As a rule of thumb, don't require move confirmation. Confirming a move slows down the user interface and thus, the game flow. You can allow a player to confirm a move if this is a very critical step in a game, and if it is possible to trigger an action by accident. If client interactions are very complex and allow cancellation, the final move can be confirmed with a "Done" button.

''Hawaii'': Ending a turn is a critical action that happens only 5 times per player in a game. In this case, it is acceptable (and a good idea) to have a confirmation dialog.

''Hive'': Each move has to be confirmed with click on the location because it is very easy to click by accident.

''Russian Railroads'': Each move involves multiple interactions and can contains dozens of subactions. When the player is done "planning" they presses a "Done" button to submit the move to the server.

''Race for the Galaxy'': There is a card that allows players to draw two cards and discard one card before the Development phase. This requires confirmation when the player selects a development card to discard, as they often means to build that development card instead.

==== Cancel a move ====
Most players want to have moves cancelled or undone. Use the following rules to implement it:
* If any information is revealed which was not known before the action is completed - You CANNOT cancel it.
* If this is the end of active player action, and it is another player's turn - You CANNOT cancel it
** Exception: You can undo action of one player if this is multiactive state and not all players are done
* If during a player's turn multiple actions are required but don't violate the above two rules - You CAN cancel/undo it. i.e. A user picks cubes and drops on a building. Selecting the cubes and building - are two actions, so user should be able to cancel taking cube.
This can be implemented using client side states, so cancelling is easy by restoring last server state.

==== Undo philosophy (New: 2026.01) ====
* Avoid unnecessary undo buttons - they often signal a confusing or error-prone interface
* Undo multiplies validation steps (select, confirm, undo, confirm again) slowing the game
* Prefer timed confirmation buttons (5-8 seconds) over allowing undos at every step
* Prefer a single "Restart Turn" option over multiple undo buttons for each micro-action
* Only propose "Undo" when a player's turn consists of more than 2 actions
* If players regularly misclick, improve the layout or interaction design instead of adding undo
* Undo should be a last-resort safety net, not a primary mechanic

=== U-7 Translatable interface ===
With BGA its very easy to translate your game in any language, using BGA collaborative translation system. Check [[Translations]] to learn how to declare your strings so that every message in your code can be managed by the internationalization system.

Rule:
* All language specific strings must be translatable.

=== U-8 Use interactive elements ===

Interactive elements are tiles, cubes or board areas user can click on to perform an action. The following guidance apply:
* If user click on interactive element either action happens or user get a error message. Try to process error message of client side and not send to server for simple errors, such as player is not active. Please be very specific why user cannot interact with element, i.e.
** This is not your turn
** You cannot build this building because you don't have enough resources
** To select this card you have to select resource first
If you cannot make errors for all elements at least tooltip should explaining when it interactive vs not

Rule: Every game element should give an explicit error message if clicked at the wrong moment rather than staying silent

Rule: When user can click on element during their turn it should be highlighted if possible (or non-active element de-highlighted in some way)

Forbidden actions display (New: 2026.01):
* Actions that cannot currently be performed should be shown as greyed out/disabled
* This lets players see the action exists but understand it's not available now
* However: if an action is never relevant in the current context, do not show a disabled button
* Balance: let players know which actions are part of the game without UI clutter

Error feedback best practices (New: 2026.01):
* Use visual feedback for failed actions: short shake animation, grey-out effect, or tooltip
* Provide concise plain-text explanations like "You don't have enough resources"
* Use accessible indicators - do not rely on color alone (pair with icons or text)
* Every failed action must give a reason immediately

Hightlighting guidelines:
* Apply a class to all active/selectable element, i.e. class can be "selectable", "active_slot", "interactive"
* An CSS element with this class can have special rules, i.e
** outline (use outline, do not use "border" as this changes sizing)
** OR shadow/glow - use box-shadow or filter: drop-shadow for non-standard tokens
** recommended color - white, yellow or blue. Do not use red - this is indication of error rather than prompt for action
** change mouse cursor to action cursor, i.e. cursor: pointer

De-highlighting guidelines:
* Only use this strategy when there are less inactive element than active
* Apply a class to all non-interactive element, such as "non-interactive"
* In css set special rules
** opacity:0.7
** OR filter:contrast(0.6) or grayscale
* change cursor, i.e. cursor: not-allowed

Rule: If state prompt replaces the interaction with a game element but elements are also visible in the game area its better to let player use either button or element (i.e. player can press a button OR they can click on element on the board)
** Example: In Lewis & Clark game offers gain resources via buttons on state prompt, but user can also click on cubes in supply to do the same action

== Feedback ==

=== F-1 Animate moving elements ===
If real game have some elements moving during the game it should also animate in your adaptation
* User gets a resource - move a resource from main board to user mini board
* User buys a card - move card from main display to user board
* User draw a card which is revealed on the display - move card from deck to display, maybe add flippy animation to turn it face up (that requires 3d transformations - that is bonus)

It is also nice to animation points or coin collection from specific region of the board (even points collection is not normally visible).

Don't need to overdo animation - its not first player shooter

Animation timing (New: 2026.01):
* Regular animation duration: 0.5 seconds - fast enough to be seen but not blocking flow
* Maximum animation duration: 0.8 seconds - keeps the pace quick, prevents frustration in long games
* Don't animate trivial or repetitive updates - batch multiple small gains into one clear effect
* Avoid excessive bouncing, glowing, or looping animations that distract from game state
* Use animation as visual explanation: show what moved, where it went, why it matters

=== F-2 Sound effects (New: 2026.01) ===

* Use volume lower than BGA default - never surprise players with loud audio
* Keep sounds short, sharp, and purposeful - no long looping soundtracks during gameplay
* Sound effects must always be paired with a visual cue (animation, highlight, etc.)
* No action should rely solely on audio to be understood
* Sound is a bonus layer of clarity, not a requirement - game must be fully understandable in silence

=== F-3 Slow down the end of game scoring ===

This is the climax of the game, building up suspense before revealing the winner... Don't make it too quick! :)

It's also very helpful if some end of game scoring animations can show where the points are gained, to help players understand (and trust) the scoring.

To achieve this, you can use synchronous notifications for each step of the scoring to slow down the process, and use this.displayScoring ([[Game_interface_logic:_yourgamename.js#Scoring_animated_display]]) to display a nice points animation in the color of the player over the element of the game granting points for this step of the scoring.

For a practical example of a game adaptation where scoring has been done with this idea in mind, you can check a game replay of Terra Mystica for the final scoring (this link will fast forward you right there: [https://boardgamearena.com/archive/replay/200901-1002/?table=112192856&player=84819187&comments=426;&goto=341 replay scoring])

End game scoring (New: 2026.01):
* Scale end scoring animation to game length (elaborate for long games, quick for short luck-based games)

== Design ==

=== D-1 Typography and fonts (New: 2026.01) ===

* Avoid fancy/decorative fonts - use the default BGA font
* Use clean sans-serif fonts with good line spacing
* Ensure minimum font sizes are readable on small phone screens
* Support screen readers: most interactive elements should have proper text equivalents
* Do not put critical information inside images without alt-text
* All text must be translatable using BGA's translation system - never embed words into graphics
* Support both LTR (left-to-right) and RTL (right-to-left) languages
* Ensure fonts support accents and diacritics (é, ñ, ü, etc.)
* Font colors must meet WCAG AA minimum contrast ratio

=== D-2 Button color standards (New: 2026.01) ===

Rule: Use standard BGA button colors consistently:
* Blue (primary) = Advance the action, confirm, move forward
* Red (alert) = Cancel, undo, stop, or exit
* White/Transparent (secondary) = Optional or side actions not critical to progress
* Grey = Disabled, already completed, or unavailable actions

This color scheme is mandatory for UX consistency across all BGA games.

=== D-3 Sizing and responsiveness (New: 2026.01) ===

* Main play area must remain centered on all devices
* Avoid fixed-width designs - layouts should expand or contract gracefully
* Leave margins around the board for comfort and to avoid misclicks on mobile
* Desktop/tablet: prioritize showing the entire board at once
* Mobile (vertical): stack secondary elements below the main action zone
* Prevent layout breakage when players zoom in/out
* No interactive element (button, token, card, tile) should be smaller than 32x32px
* Ideal tap target size: 40-44px for touchscreens

=== D-4 Background design (New: 2026.01) ===

* Use thematic/modern backgrounds (e.g., a subtle playing mat look) instead of the old wooden floor texture
* Background must never reduce the visibility of game components - prioritize contrast
* Avoid pure flat colors - use slight textures or patterns
* Apply a touch of blur to backgrounds so components remain the visual focus
* Think of the background as the table surface your game lives on - natural, thematic, but not distracting

== Original game representation ==

=== R-1 Use the original art===
The less you are modifying the original art of the game, the better.
Its important for publishers that a board game adaptation looks like the real board game. Sometimes it can be useful to modify some elements of the game to save some space on the screen – but try to avoid it.
Tips: if you have not enough space on the screen, reduce the size of the game elements.
Try to make sure they are recognizable for players who played regularly, and add a tooltip to help beginners to figure out what they are.
Gosu : the original cards are used, with tooltips.

=== R-2 Be careful about player assistance ===
As a rule of thumb, in order to respect the original board games, you should not introduce any player assistance feature.
An assistance must not be introduced if it directly helps the player to figure out if his move is good or bad.
An assistance may be introduced if it can help the player to figure out what moves are available.

Gygès: the assistance shows you available moves, but is not alerting you about stupid moves (like the upper left one).

Note: You can however do a single choice move for a player, i.e passing on a turn if there is nothing a user can do; It's quite annoying to wait on a player to pass, while it's the only action that they can do anyways.

=== R-3 Available information ===
Every information visible by players in the real game should be accessible in the adaptation. Pay attention to some information like the number of cards in the opponents hand, or the number of remaining cards in the deck.
If it is explicitly forbidden to count cards in the discard pile, this information is not available.

== Accessibility ==

=== A-1 Design for all (New: 2026.01) ===

* Don't rely on color alone - pair colors with icons, textures, or shapes for players with color vision deficiencies
* Use proper contrast - minimum ratio of 4.5:1 for text readability
* Keep animations safe - avoid flashing or rapidly alternating visuals
* Label everything - buttons, icons, and interactive elements should include clear text labels or tooltips for screen readers
* Make differences obvious - use bold shapes, clear outlines, and strong contrast rather than subtle shading or color variations

=== A-2 Colorblind-safe design (New: 2026.01) ===

* Add unique shapes, symbols, or outlines to each player color on pawns/tokens
* Place small icons in card corners or add patterns so cards can be recognized without relying on hue
* All text and icons must meet WCAG AA contrast levels
* Use outlines, borders, or contrasting strokes for player colors
* Test player colors against both light and dark backgrounds (avoid yellow text on white)

=== A-3 Tap targets for mobile (New: 2026.01) ===

* Minimum interactive element size: 32×32px
* Ideal size: 40-44px (greatly reduces mis-taps on touchscreens)
* Leave enough spacing between buttons/tokens/cards to prevent accidental hits
* Avoid cramming small icons together - group many options into expandable menus or secondary panels
* When space runs out, allow scrolling areas instead of shrinking components until unusable

=== A-4 Settings and customization (New: 2026.01) ===

* All game settings must be placed in the standard BGA settings menu (not custom menus)
* Provide per-game options only where relevant:
** Animation speed (activated/none)
** Tooltip detail (compact/full)
** Sound effects (on/off)
* Reuse existing BGA controls - never duplicate custom UI for settings

== Game technical quality ==

=== T-1 Don't use exotic stuff ===
BGA Studio provides a set of useful tools to build board games adaptations (i.e. card management, confirmation dialog, tooltips,…).
Use them, and don't use exotic libraries, plugins or tricks.
Why? Because BGA Framework will evolve in the future to provide new features to players, and it could make your game incompatible with the new version.
On the contrary, if you are using standard Haggis using BGA standard card stuff, you will enjoy these enhancements without any effort.
If you feel that you really need some exotic thing: don't hesitate to ask us.

=== T-2 Make sure you can use what you use ===

In particular, do not build your game on top of a technical library without checking that licensing allows you (and BGA) to use it.
If you use a library, make sure first that its license is really open (MIT style). Otherwise, we may have to ask you to rework your code to use another library.
In general, please consider that it's always better to minimize dependencies, so if you can avoid using external libraries, all the better.

=== T-3 Write in (simple) English ===
Some other person may have to look at your code, such as:
* We (the BGA team), who are here to help you if you need us.
* Some other BGA developer wanting to help you.
For all these reasons, your code must be written in English (variables, methods, comments...).
If English is not your mother tongue don't be afraid: the whole idea here is to be understood, not to write an essay :)

=== T-4 Page refresh ===
A page refresh (F5) must allow players to reset the game interface to a stable state at any moment of the game.
BGA Studio framework allows you to do this with the « getAllDatas » PHP method and the « setup » Javascript method.
Note: this « refresh » feature is also quite useful during the development process:)

Refresh continuity (New: 2026.01):
* After refresh, the game must return to the exact same state with no missing or corrupted information
* Restore temporary UI indicators (whose turn it is, pending actions, selected components)
* Server is the source of truth - never rely on client-only memory for critical state
* Do not depend on "session continuity hacks" - BGA servers may disconnect/reconnect players at any time
* A refresh should feel invisible to the player

=== T-5 Private information ===
A private game element must be visible only to the player owning it. It must not be visible by his opponents, by any means.
In particular:
* getAllDatas PHP method must not return any element that are hidden from current player, even if the Javascript « setup » method ignores them.
* you must not send via the « notify->all » function some information that is hidden from one player (use « notify->player » instead).

Hearts: each player is alerted about his new cards using notify->player, and cards from the other players remains secret

=== T-6 Game progression ===
Game progression should be as accurate as possible.
Of course, its not always easy (or even possible) to compute game progression, but a vague approximation is better than nothing.
Stone Age: there are 2 different end game conditions (building cards and civilization cards).
Both are taken into account to increase the accuracy of the game progression.

=== T-7 Game statistics ===
Using BGA Studio you can define a set of statistics for your game. Statistics will be displayed at the end of the game, and help players to figure out why they win/lose a game,
and what they should improve. Try to choose interesting statistics that distinguish the different strategies for your game, in order it can help players to understand their game.

Seasons : statistics

=== T-8 Error handling (New: 2026.01) ===

* Handle disconnects smoothly - anticipate delays and dropped actions without breaking game flow
* Invalid inputs must never crash the game or leave it in a corrupted state
* For developers: provide precise error details in the console
* For players: display short, friendly messages explaining what went wrong and what to do next
* Never expose raw server logs or technical stack traces to end users
* Isolate errors to the affected action - never block the entire table because of one failed request

=== T-9 Endgame and replays (New: 2026.01) ===

* Endgame logs must clearly summarize all major actions that led to the outcome
* Replay mode must feel as clear as the live session
* No blocking popups during replays - they should flow smoothly
* Animations must be compatible with replays - playable at minimum speed and skippable
* Logs and highlights must stay in sync with each replayed action

=== T-10 Namespace recommendations ===
Your game is not working in complete isolation, it's included in a page with a lot of elements around (header, footer, logs, chat, player panels, rankings...)

So you should pay attention to naming your DOM elements, CSS classes and PHP constants / classes in a way specific to your game in order to avoid namespace collisions (for example you use a selector for a "selected" class in your .js, and there is also an element of the framework outside of your game with a selected class).

It's recommended to have:
* a wrapper div around your game zone with an id specific to your game ('yourgamename_playzone' for example) and to use it in any xpath selector of your .js
* a prefix for example a trigram for your game that you append to all the css classes of your game ('yrg_selected' for example).
* a prefix or a namespace for your PHP constants or classes.

Even if everything is working fine today, otherwise your game may break in the future when the framework is updated.

You should not use any global variables (window scope) in your Javascript files. If you need something to be accessible globally, then you should use <code>window.gameui</code>. You could even make a <code>window.gameui.globals = {}</code> object to contain any global variables.

== Summary ==
These guidelines are here to help you to make sure that the players, the game publisher and the game author are going to enjoy your adaptation of the game. We created these guidelines based on our personal experience (which includes many mistakes along the way) implementing a lot of games on BGA platform. Don't hesitate to contact us if you feel uncomfortable with one of these guidelines in some particular context with your game: these guidelines are here to help and not to prevent you to do smart things, and have fun while programing your game ;)

= BGA Studio Guidelines =
Make your code as easy to read and understand as possible : clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

== Front (JS) code ==

=== Generated code ===
Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

=== Templates ===
Use JS template strings instead of .tpl file.

Tpl file should only contain a single div, or be deleted. View.php file shouldn’t be used anymore.

== Back (PHP) code ==
Game name & options should be Capitalized.

=== Framework functions ===

===== Undocumented functions =====
Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

==== Function override ====
Do not override framework functions. Use a wrapper instead.

'''Bad :'''

<pre>
public function getPlayerNameById($player_id) { // same name as the framework function = override
if ($player_id == 0) {
return 'Automata';
} else {
return parent::getPlayerNameById($player_id);
}
}
</pre>

'''Better :'''
<pre>
public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
if ($player_id == 0) {
return 'Automata';
} else {
return $this->getPlayerNameById($player_id);
}
}
</pre>

==== State functions ====
States functions should be prefixed “st”

Args functions should be prefixed “arg”

Action functions should be prefixed “act”

=== Namespacing ===
The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <code><mygame>/PowerCard/PowerCardManager.php</code> and start like this :

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\<mygame\PowerCard;
class PowerCardManager {
</pre>

=== Other ===
.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function should check any input. To avoid code duplication, they can use the arg function.

''Example :''

<pre>
$args = $this->argPlayCards();
if (!in_array($cardId, $args[‘selectableCardsIds’]) { throw new \BgaUserException(...); }
</pre>

Don’t use `@` to ignore the errors of a function call.

[[Category:Studio]]

Pre-release checklist

2026-04-06T17:40:40Z

Victoria La:

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first

=== Move from Dev to Alpha ===
# ''' License '''
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.
# ''' Metadata and game assets '''
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game.
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
## You have added the requested images in the Game Metadata Manager to make the game page pretty
## There are no images in the img directory that are not needed anymore
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
## Each image should not exceed 4Mb
## Total size should not exceed 15Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 15Mb (i.e. expansions), you have to make a note of that when requesting move to alpha
## If you use extra fonts, they should be freeware (please include a .txt with the license information in addition to the font files). Fonts should be placed to "fonts" directory
## Sounds should be placed to "sounds" directory
# ''' Server side '''
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function
## Game progression is implemented (getGameProgression() in php)
## Zombie turn is implemented (zombieTurn() in php). For more details about how the Zombie code should work and be tested, see [[Zombie Mode|Zombie mode]].
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expansions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)
# ''' Client side '''
## Check that you use ajaxcall/bgaPerformAction only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automatically (i.e. during replay)''
# ''' User Interface '''
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
## If your game elements become blurry or pixelated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
## Non-self explanatory graphic elements should have tool tips
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
# ''' Special testing '''
## Click "Use minified JS" and "Use minified CSS" buttons on the game management page, then test your game. This will prevent you from having a panic attack when the game releases in alpha and it is stuck in "Connecting to game".
## Game is tested with spectator (non player observer): click the red arrow next to Test spectator, under player panels. As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
## Game is tested with in-game replay from last move feature (by clicking on notification log items).
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
# ''' Cleanup '''
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)
## Remove all unnecessary debug logging from your php code
## Copyright headers in all source files have your name
## Remove unnecessary files from main folder (can move some to misc folder)
## If using TypeScript and Scss - move them to "src" folder from "modules", if not there already (modules deployed to prod, only transposed files are needed)
# ''' Static Analysis '''
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Dry run build"
## There is also "Check project" button (it will open like a game table, and you can type your project and click on Start button to run analysis) - but it may be obsolete

=== Finally move to Alpha status ===
# We want the correct formal name of the game to be used for the project (i.e. '''agricola''', not '''myagricolaproject'''). If you DO NOT have the correct formal name of the game for your project, then
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it. In this case, after you request the alpha deployment, please reply to the automatic reply with the correct name.
## If you DO have the correct formal name of the game for your project, or completed the above steps, create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
# Are you really ready?
## Click on the '''Request ALPHA status''' button available above your just built version. You cannot deploy yourself from the "manage game" page until this first ALPHA deploy has been done by the admins. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed. Note: you can also ask for moving your project to "private Alpha" - in this case you will invite people manually rather than having your game immediately visible to the whole BGA reviewers community. When you press you button you should receive acknowledgement email, reply to this email with more details.
# Reply to alpha request e-mail with following information
## Is this final project name or need renaming
## What is your production BGA user name
## If private alpha requested - BGA user names of other admins - usually publisher/designer
## If you have license or/and alpha approval, include approval email (form publisher)
## If you have exceptions for items from this checklist (i.e. size of assets, custom fonts, etc) add explanations
# Wait
## When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps. If you waiting for 2 weeks+ you can ping them again.

=== Move from Alpha to Beta ===
# The implementation '''must be approved by the publisher''' (if not a public domain game)
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals
# Click on the '''Request BETA status''' button available above your latest build. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed.

[[Category:Studio]]

Pre-release checklist

2026-04-06T17:40:16Z

Victoria La: note about fonts and sounds

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first

=== Move from Dev to Alpha ===
# ''' License '''
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.
# ''' Metadata and graphics '''
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game.
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
## You have added the requested images in the Game Metadata Manager to make the game page pretty
## There are no images in the img directory that are not needed anymore
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
## Each image should not exceed 4Mb
## Total size should not exceed 15Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 15Mb (i.e. expansions), you have to make a note of that when requesting move to alpha
## If you use extra fonts, they should be freeware (please include a .txt with the license information in addition to the font files). Fonts should be placed to "fonts" directory
## Sounds should be placed to "sounds" directory
# ''' Server side '''
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function
## Game progression is implemented (getGameProgression() in php)
## Zombie turn is implemented (zombieTurn() in php). For more details about how the Zombie code should work and be tested, see [[Zombie Mode|Zombie mode]].
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expansions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)
# ''' Client side '''
## Check that you use ajaxcall/bgaPerformAction only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automatically (i.e. during replay)''
# ''' User Interface '''
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
## If your game elements become blurry or pixelated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
## Non-self explanatory graphic elements should have tool tips
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
# ''' Special testing '''
## Click "Use minified JS" and "Use minified CSS" buttons on the game management page, then test your game. This will prevent you from having a panic attack when the game releases in alpha and it is stuck in "Connecting to game".
## Game is tested with spectator (non player observer): click the red arrow next to Test spectator, under player panels. As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
## Game is tested with in-game replay from last move feature (by clicking on notification log items).
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
# ''' Cleanup '''
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)
## Remove all unnecessary debug logging from your php code
## Copyright headers in all source files have your name
## Remove unnecessary files from main folder (can move some to misc folder)
## If using TypeScript and Scss - move them to "src" folder from "modules", if not there already (modules deployed to prod, only transposed files are needed)
# ''' Static Analysis '''
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Dry run build"
## There is also "Check project" button (it will open like a game table, and you can type your project and click on Start button to run analysis) - but it may be obsolete

=== Finally move to Alpha status ===
# We want the correct formal name of the game to be used for the project (i.e. '''agricola''', not '''myagricolaproject'''). If you DO NOT have the correct formal name of the game for your project, then
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it. In this case, after you request the alpha deployment, please reply to the automatic reply with the correct name.
## If you DO have the correct formal name of the game for your project, or completed the above steps, create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
# Are you really ready?
## Click on the '''Request ALPHA status''' button available above your just built version. You cannot deploy yourself from the "manage game" page until this first ALPHA deploy has been done by the admins. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed. Note: you can also ask for moving your project to "private Alpha" - in this case you will invite people manually rather than having your game immediately visible to the whole BGA reviewers community. When you press you button you should receive acknowledgement email, reply to this email with more details.
# Reply to alpha request e-mail with following information
## Is this final project name or need renaming
## What is your production BGA user name
## If private alpha requested - BGA user names of other admins - usually publisher/designer
## If you have license or/and alpha approval, include approval email (form publisher)
## If you have exceptions for items from this checklist (i.e. size of assets, custom fonts, etc) add explanations
# Wait
## When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps. If you waiting for 2 weeks+ you can ping them again.

=== Move from Alpha to Beta ===
# The implementation '''must be approved by the publisher''' (if not a public domain game)
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals
# Click on the '''Request BETA status''' button available above your latest build. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed.

[[Category:Studio]]

Studio

2026-04-01T20:46:39Z

Victoria La: /* PHP Extensions Used */

{{Studio_Framework_Navigation}}

[[File:Bga_studio_small.jpg|frameless|300px]]

Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the latest information available.

__TOC__

== What is Board Game Arena Studio? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptations using the Board Game Arena platform.

It is open to any gamer with software development skills :)

BGA Studio website: https://studio.boardgamearena.com

Original announcement on BGA forum: https://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

Why, how, what... to start discovering BGA Studio, we prepared 5 "powerpoint" presentations for you:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game] (or [http://en.doc.boardgamearena.com/images/5/58/1-why-developing.pdf ‎Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena] (or [http://en.doc.boardgamearena.com/images/1/1e/2-8-steps-to-realize.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] (or [http://en.doc.boardgamearena.com/images/7/79/3-thebgaframework.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine] (or [http://en.doc.boardgamearena.com/images/9/98/4-gamestates.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] (or [http://en.doc.boardgamearena.com/images/7/76/5-guidelines.pdf ‎Download as PDF])

== How to join the BGA developer team? ==

Please see this page: [[How to join BGA developer team?]]

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

Then, you should checkout the [[First steps with BGA Studio]] to make sure that runs fine.

After that, we strongly advise you to take one of these game creation tutorials:
* [[Tutorial reversi]] ('''recommended''', closest to the actual BGA implementation and maintained by the BGA team) - an abstract strategy game played on an 8×8 uncheckered board for 2 players
* [[Tutorial hearts]] - a card game for 4 players

Then start editing files and see what happens! ;)

Once you're done with tutorials, you can start a real game (or join existing project)
* [[Create a game in BGA Studio: Complete Walkthrough]]

If you have any questions, please check out the [[Studio FAQ]] or [[Contact BGA Studio]].

To search wiki pages on studio enter this text in search bar:
"Category:Studio" white rabbit
That is if you want to search for white rabbit

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

This part of the documentation focuses on the development framework itself: functions and methods available to build your game.

[[Studio file reference|File structure of a BGA game]]

==== Game logic (Server side) ====

* [[Main game logic: yourgamename.game.php|Main game logic: Game.php]]
* [[State classes: State directory|Your game state classes: States directory]]
* [[Game database model: dbmodel.sql]]
* [[Game material description: material.inc.php]]
* [[Game statistics: stats.inc.php|Game statistics: stats.json]]

==== Game interface (Client side) ====

* [[Game interface logic: Game.js]]
* [[Game art: img directory]]
* [[Game interface stylesheet: yourgamename.css]]
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]
* [[Your game mobile version]]

==== Other components ====

* [[Translations]] (how to make your game translatable)
* [[Options_and_preferences:_gameoptions.json,_gamepreferences.json|Game Options and Preferences]]
* [[Game meta-information: gameinfos.inc.php]]
* [[Game replay]]

=== BGA Studio game components reference ===

Game components are useful tools you can use in your game adaptations.

JS:

* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Anti-Stock]]: Code snippets in vanilla JS/HTML5 to do what stock does (that is if you cannot beat Stock into submission)
* [[BgaAnimations|bga-animations]]: a JS component for animations.
* [[BgaCards|bga-cards]]: a JS component for cards.
* [[BgaDice|bga-dice]]: a JS component for dice.
* [[BgaAutofit|bga-autofit]]: a JS component to make text fit on a fixed size div.
* [[BgaScoreSheet|bga-score-sheet]]: a JS component to help you display an animated score sheet at the end of the game.

PHP:
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...)
* [[PlayerCounter and TableCounter]]: php component to manager counters

=== BGA Studio user guide ===

This part of the documentation is a user guide for the BGA Studio online development environment.

Lifecycle

* [[BGA game Lifecycle]]
* [[BGA Game licenses]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Pre-release checklist]] - Go throught this list if you think you done development
* [[Post-release phase]]

Tools and Advice
* [[BGA Studio Guidelines]]
* [[Tutorials checklist]]
* [[I wish I knew this when I started]] - one liners on most common missed features, mistakes, etc with further doc references
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
** [[Setting up BGA Development environment using VSCode]]
** [[Practical debugging]] - Tips focused on debugging
** [[Testing by developer]]
** [[Studio logs]] - Instructions for log access
** [[Troubleshooting]] - Most common "I am really stuck" situations
* [[Production issues reporting|Production issues reporting tool]]
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
** [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
** [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner
** [[Bots and Artificial Intelligence]] - How to add AI/Bots to the game
* [[BGA Studio Migration Guide]] - Migration tips from older version of studio framework
* [[Studio FAQ]]

Sharing
* [[Common board game elements image resources]] - Dice, meeples, cubes, etc
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links

== Software Versions ==

Versions currently used by BGA framework:

* Dojo Toolkit 1.15
* PHP: 8.4
* SQL: MySQL 5.7
* JS/CSS/HTML: limited by what minimization tools support: [[Game_interface_logic:_yourgamename.js#Javascript_minimization_.28after_July_2020.29|JS minimization]]
* Font Awesome: 4.7 https://fontawesome.com/v4.7/icons/ (available as <code><nowiki><i class="fa fa-clock" /></nowiki></code>)
* Font Awesome: 6.4.0 https://fontawesome.com/v6/search?o=r&m=free (available as <code><nowiki><i class="fa6 fa6-clock" /></nowiki></code>)

=== PHP Extensions Used ===

The following PHP extensions are - as of Apr 1, 2026 - in use in BGA Studio:

Core date libxml openssl pcre sqlite3 zlib ctype curl dom fileinfo filter hash iconv json mbstring SPL session PDO pdo_sqlite standard posix random readline Reflection Phar SimpleXML tokenizer xml xmlreader xmlwriter mysqlnd cgi-fcgi apcu gd gettext gmp mysqli pcntl redis sodium zip memcached Zend OPcache

== Other resources ==

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]

DISCORD chat server/room invite link https://discord.gg/YxEUacY if it does not work check this topic https://forum.boardgamearena.com/viewtopic.php?f=12&t=17403&hilit=discord

Developer BLOGS https://bga-devs.github.io/blog/

BGA Mainsite releases https://en.boardgamearena.com/forum/viewtopic.php?t=23289&start=100

[[Contact BGA Studio]]

[[Category:Studio]]

Bugsclarification wayfarers

2026-03-31T23:26:22Z

Victoria La: intial page

== Screenshots ==
You can upload screenshot here and share link on the bug
https://snipboard.io/

== Rules ==
If you think its a rule bug:
* State name name of the card (or number like Land #122) if cards are involved
* State the rule that you think is violated

== Check the bugs ==
Vote on existing bug instead of filing a new bug, I am sorting by number of votes.

Pre-release checklist

2026-03-15T19:19:48Z

Victoria La:

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first

=== Move from Dev to Alpha ===
# ''' License '''
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.
# ''' Metadata and graphics '''
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game.
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
## You have added the requested images in the Game Metadata Manager to make the game page pretty
## There are no images in the img directory that are not needed anymore
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
## Each image should not exceed 4Mb
## Total size should not exceed 15Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 15Mb (i.e. expansions), you have to make a note of that when requesting move to alpha
## If you use extra fonts, they should be freeware (please include a .txt with the licence information in addition to the font files)
# ''' Server side '''
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function
## Game progression is implemented (getGameProgression() in php)
## Zombie turn is implemented (zombieTurn() in php). For more details about how the Zombie code should work and be tested, see [[Zombie Mode|Zombie mode]].
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expantions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)
# ''' Client side '''
## Check that you use ajaxcall/bgaPerformAction only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automaticaly (i.e. during replay)''
# ''' User Interface '''
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
## If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
## Non-self explanatory graphic elements should have tooltips
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
# ''' Special testing '''
## Click "Use minified JS" and "Use minified CSS" buttons on the game management page, then test your game. This will prevent you from having a panic attack when the game releases in alpha and it is stuck in "Connecting to game".
## Game is tested with spectator (non player observer): click the red arrow next to Test spectator, under player panels. As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
## Game is tested with in-game replay from last move feature (by clicking on notification log items).
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
# ''' Cleanup '''
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)
## Remove all unnecessary debug logging from your php code
## Copyright headers in all source files have your name
## Remove unnecessary files from main folder (can move some to misc folder)
## If using TypeScript and Scss - move them to "src" folder from "modules", if not there already (modules deployed to prod, only transposed files are needed)
# ''' Static Analysis '''
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Dry run build"
## There is also "Check project" button (it will open like a game table, and you can type your project and click on Start button to run analysis) - but it may be obsolete

=== Finally move to Alpha status ===
# We want the correct formal name of the game to be used for the project (i.e. '''agricola''', not '''myagricolaproject'''). If you DO NOT have the correct formal name of the game for your project, then
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it. In this case, after you request the alpha deployment, please reply to the automatic reply with the correct name.
## If you DO have the correct formal name of the game for your project, or completed the above steps, create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
# Are you really ready?
## Click on the '''Request ALPHA status''' button available above your just built version. You cannot deploy yourself from the "manage game" page until this first ALPHA deploy has been done by the admins. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed. Note: you can also ask for moving your project to "private Alpha" - in this case you will invite people manually rather than having your game immediately visible to the whole BGA reviewers community. When you press you button you should receive acknowledgement email, reply to this email with more details.
# Reply to alpha request e-mail with following information
## Is this final project name or need renaming
## What is your production BGA user name
## If private alpha requested - BGA user names of other admins - usually publisher/designer
## If you have license or/and alpha approval, include approval email (form publisher)
## If you have exceptions for items from this checklist (i.e. size of assets, custom fonts, etc) add explanations
# Wait
## When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps. If you waiting for 2 weeks+ you can ping them again.

=== Move from Alpha to Beta ===
# The implementation '''must be approved by the publisher''' (if not a public domain game)
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals
# Click on the '''Request BETA status''' button available above your latest build. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed.

[[Category:Studio]]

Pre-release checklist

2026-03-15T19:16:12Z

Victoria La: added info on what to include in alpha request

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first

=== Move from Dev to Alpha ===
# ''' License '''
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.
# ''' Metadata and graphics '''
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game.
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
## You have added the requested images in the Game Metadata Manager to make the game page pretty
## There are no images in the img directory that are not needed anymore
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
## Each image should not exceed 4Mb
## Total size should not exceed 15Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 15Mb (i.e. expansions), you have to make a note of that when requesting move to alpha
## If you use extra fonts, they should be freeware (please include a .txt with the licence information in addition to the font files)
# ''' Server side '''
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function
## Game progression is implemented (getGameProgression() in php)
## Zombie turn is implemented (zombieTurn() in php). For more details about how the Zombie code should work and be tested, see [[Zombie Mode|Zombie mode]].
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expantions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)
# ''' Client side '''
## Check that you use ajaxcall/bgaPerformAction only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automaticaly (i.e. during replay)''
# ''' User Interface '''
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
## If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
## Non-self explanatory graphic elements should have tooltips
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
# ''' Special testing '''
## Click "Use minified JS" and "Use minified CSS" buttons on the game management page, then test your game. This will prevent you from having a panic attack when the game releases in alpha and it is stuck in "Connecting to game".
## Game is tested with spectator (non player observer): click the red arrow next to Test spectator, under player panels. As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
## Game is tested with in-game replay from last move feature (by clicking on notification log items).
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
# ''' Cleanup '''
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)
## Remove all unnecessary debug logging from your php code
## Copyright headers in all source files have your name
## Remove unnecessary files from main folder (can move some to misc folder)
## If using TypeScript and Scss - move them to "src" folder from "modules", if not there already (modules deployed to prod, only transposed files are needed)
# ''' Static Analysis '''
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Dry run build"
## There is also "Check project" button (it will open like a game table, and you can type your project and click on Start button to run analysis) - but it may be obsolete

# ''' Finally move to Alpha status '''
## We want the correct formal name of the game to be used for the project (i.e. '''agricola''', not '''myagricolaproject'''). If you DO NOT have the correct formal name of the game for your project, then
### If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it. In this case, after you request the alpha deployment, please reply to the automatic reply with the correct name.
## If you DO have the correct formal name of the game for your project, or completed the above steps, create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
## Are you really ready? Click on the '''Request ALPHA status''' button available above your just built version. You cannot deploy yourself from the "manage game" page until this first ALPHA deploy has been done by the admins. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed. Note: you can also ask for moving your project to "private Alpha" - in this case you will invite people manually rather than having your game immediately visible to the whole BGA reviewers community. When you press you button you should receive acknowledgement email, reply to this email with more details.
* ''' Add Information '''
Reply to alpha request e-mail with following information
** Is this final project name or need renaming
** What is your production BGA user name
** If private alpha requested - BGA user names of other admins - usually publisher/designer
** If you have license or/and alpha approval, include approval email (form publisher)
** If you have exceptions for items from this checklist (i.e. size of assets, custom fonts, etc) add explanations
* ''' Wait '''
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.

=== Move from Alpha to Beta ===
# The implementation '''must be approved by the publisher''' (if not a public domain game)
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals
# Click on the '''Request BETA status''' button available above your latest build. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed.

[[Category:Studio]]

Using Typescript and Scss

2026-03-14T15:21:18Z

Victoria La: /* Referenced Projects */

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

The following document is geared towards setting up a custom project where you will be in charge of typing all components that you want to use.

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''
<pre>
{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "modules/js/Game.js",
"scripts": {
"build:ts": "rollup -c",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "rollup -c -w",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"@rollup/plugin-typescript": "^12.3.0",
"rollup": "^4.53.3",
"sass": "^1.71.0",
"tslib": "^2.8.1",
"typescript": "^5.3.3"
}
}
</pre>

Note: if you not using scss - remove corresponding scripts and deps.

IMPORTANT: Change the file! You have to replace yourgamename, yourname and license

IMPORTANT: exclude node_modules/ subfolder from auto-sync to remote folder (whatever system you use for that). Before next step!

IMPORTANT: When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

For Typescript compilation we also need to set up <code>rollup.config.mjs</code> and <code>tsconfig.json</code> on the root folder.

'''rollup.config.mjs'''
<pre>
import typescript from '@rollup/plugin-typescript';

export default {
input: 'src/Game.ts',
output: {
file: 'modules/js/Game.js',
format: 'es',
sourcemap: false,
inlineDynamicImports: true,
},
plugins: [
typescript({
tsconfig: './tsconfig.json',
outDir: 'modules/js',
}),
],
treeshake: false,
};
</pre>

'''tsconfig.json'''
<pre>
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2022",
"moduleResolution": "node",
"lib": ["dom", "esnext"],
"sourceMap": false,
"rootDir": "."
},
"include": [
"*.d.ts",
"src/**/*.d.ts",
"src/**/*.ts"
]
}
</pre>

Note: The rootDir must be set to "." (not "src") otherwise TypeScript won't see *.d.ts files in the project root (such as bga-framework.d.ts). The outDir must also be set in the rollup plugin (not in tsconfig.json) because the rollup plugin requires outDir to be inside the same directory as the rollup output file.

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

Note: if you're using SFTP and have "bga-framework.d.ts" in the ignore list - remove it and resync. You will need this file.

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look at [https://studio.boardgamearena.com/projects castlecombo] code for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/types.d.ts'''
<pre>
interface YourGameNamePlayer extends Player {
cards: Card[]; // any information you add on each result['players']
}

interface YourGameNameGamedatas extends Gamedatas<YourGameNamePlayer> {
// Add here variables you set up in getAllDatas
discardedCards: { [row: number]: Card[] };
remainingCardsInDecks: { [row: number]: number };
tableCards: { [row: number]: Card[] };
}
</pre>
Note: the Generic typing is optional.
Note 2: types.d.ts cannot be called Game.d.ts as it has different types, not related Game class

'''src/Game.ts'''

<pre>
export class Game {

public bga: Bga<YourGameNameGamedatas>;
private gamedatas: YourGameNameGamedatas;

constructor(bga: Bga<YourGameNameGamedatas>) {
this.bga = bga;
}

public setup(gamedatas: YourGameNameGamedatas) {
this.gamedatas = gamedatas;
this.setupNotifications();
}
public setupNotifications() {}
}
</pre>

Don't forget to sync the bga-framework.d.ts from your FTP folder regularly to get the last version.

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.

Example:
<pre>
@use 'variables' as v;

/* the other files */
@use "./Animations";
@use "./Board";

#ebd-body {
background-image: url(img/woodbg.jpg);
background-repeat: repeat;
}
@each $key, $val in v.$colors-list {
.fgcolor#{$key} {
color: #{$val};
}
}

</pre>

Your SCSS code can be (should be) splitted in multiple files, for example:

'''variables.scss'''
<pre>
$colors-list: (
_6cd0f6: #6cd0f6, // blue
_ef58a2: #ef58a2, // pink
_ffcc02: #ffcc02, // yellow
_a0d28c: #a0d28c // green
);
</pre>

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continuously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup standard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Make sure that your sftp.json file has a "watcher" section to detect and upload changes made outside of the VSCode IDE.

<pre>
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
</pre>

=== Exclusions from auto-upload ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To have a code completion for framework classes, dojo, stock, etc, you'll need to make sure bga-framework.d.ts file is added to your tsconfig.

== Using the new libs ==
To use the new front libs (bga-autofit, bga-score-sheet, ...), it's recommended to created a dedicated file that will be responsible of all imports, than you'll import when you need it

'''libs.ts'''
<pre>
import type { BgaAnimations as BgaAnimationsType } from "../bga-animations";
import type { BgaCards as BgaCardsType } from "../bga-cards";

const BgaAnimations: typeof BgaAnimationsType = await globalThis.importEsmLib('bga-animations', '1.x');
const BgaCards: typeof BgaCardsType = await globalThis.importEsmLib('bga-cards', '1.x');

export { BgaAnimations, BgaCards };
</pre>

Then you can use them in your files using import:
<pre>
import { BgaCards } from './libs';
export class MyCardManager extends BgaCards.Manager<Card> { ... }
</pre>

For class property typings, use:
<pre>
public animationManager: InstanceType<typeof BgaAnimations.Manager>;

// in your setup:
this.animationManager = new BgaAnimations.Manager({ ... });
</pre>

If you need to load old libs, you can do it this way:
<pre>
const [Counter, Stock] = await importDojoLibs(["ebg/counter", "ebg/stock"]);

export { Counter, Stock };
</pre>

== Migrating from old way (ES5 build to gamename.js) ==

the new setup described in this page use explicit import/export that were not used before. But we don't need to explicitely list all files anymore.

For example, if you have a file for MyCardManager and a file for MyGame, you'll need to do this:

'''MyCardManager.ts'''
<pre>
export class MyCardManager { ... }
</pre>

'''MyGame.ts'''
<pre>
import { MyCardManager } from "./MyCardManager";

export class Game {
public cardManager: MyCardManager;
</pre>

== Browser console info ==

Using ES modules, your game object is no longer merged into the <code>gameui</code> global. Instead, your game object is available as <code>gameui.GameModule</code>.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/elaskavaia/bga-dojoless - complete setup, new template Typescript/Scss, unit tests for typescript

[[Category:Studio]]

Testing by developer

2026-03-14T15:20:18Z

Victoria La:

When you develop a game you obviously have to test it, this page collects the info about testing in one place

== Manual Testing on BGA ==

For manual testing the most important things to know are:
* how to start/stop game in one click
* how to switch between players in one click
* how to save/restore the game state
* how to construct the game state automatically
All of these described here https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio

There is also HUGE checklist of things you need to test manually which you may not even think about, defined here https://en.doc.boardgamearena.com/Pre-release_checklist

== Manual Testing locally ==

'''HTML/CSS'''
At this era the file sync is almost instant so you do not save much by doing this locally, however if internet is a challenge - here are some tips
https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout

'''PHP'''
You can run and debug php locally using tip https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally

== Automated Testing ==
===JavaScript===

I did not try for pure java script, it works for typescript.
You need dev dependency on mocha, jsdom and sinon and some other build tools.
Typescript code lives in src/.
Test code lives in src/tests/.
Tests have their own src/tests/tsconfig.json
File src/tests/setup.ts contains framework and global stubs that tests need.
The config is very verbose so I did not copy it here, if interested check project "dojoless" or bga-dojoless on github (https://github.com/elaskavaia/bga-dojoless).

===PHP===

====Install PHPunit====

Install PHPunit via composer somewhere in home directory, i.e.
cd /home/<yourusername>/php-composer
composer require --dev phpunit/phpunit ^13

We don't want the phpunit cache to be sync/commited, so add <code>".phpunit.cache"</code> to sftp.json ignore list. You can push the unit tests to the FTP, no need to ignore them. If someone maintains your game in the future, he willl be able to use them to make sure nothing breaks on an update!
If you have a .gitignore, add <code>.phpunit.cache</code> to it.

Then add this to your .bashrc (alias function to be able to test phpunit easily)
phpunit() {
/home/<yourusername>/php-composer/vendor/bin/phpunit \
-c "$PWD/phpunit.xml.dist" \
--bootstrap "$PWD/tests/bootstrap.php" \
"$@"
}

With that, on a new terminal you will be able to run the tests with one of the following commands at the root of your project :
phpunit
phpunit tests/BoardManagerTest.php
phpunit --filter testGivesExtraTime

====Setup minimal files====
Create these files:

'''phpunit.xml.dist'''
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="tests/bootstrap.php"
colors="true"
cacheDirectory=".phpunit.cache">
<testsuites>
<testsuite name="Reversi">
<directory>tests</directory>
</testsuite>
</testsuites>
</phpunit>
</pre>
(replace Reversi by your project name)

'''tests/bootstrap.php'''
<pre>
<?php

declare(strict_types=1);

require_once __DIR__ . '/stubs/BgaFrameworkStubs.php';

$autoload = __DIR__ . '/../vendor/autoload.php';
if (file_exists($autoload)) {
require_once $autoload;
}

spl_autoload_register(static function (string $class): void {
$prefix = 'Bga\\Games\\Reversi\\';

if (!str_starts_with($class, $prefix)) {
return;
}

$relativeClass = substr($class, strlen($prefix));
$path = __DIR__ . '/../modules/php/' . str_replace('\\', '/', $relativeClass) . '.php';

if (file_exists($path)) {
require_once $path;
}
});
</pre>
(replace Reversi by your project name)

'''tests/stubs/BgaFrameworkStubs.php'''
<pre>
<?php

declare(strict_types=1);

require_once __DIR__ . '/stubs/BgaFrameworkStubs.php';

$autoload = __DIR__ . '/../vendor/autoload.php';
if (file_exists($autoload)) {
require_once $autoload;
}

spl_autoload_register(static function (string $class): void {
$prefix = 'Bga\\Games\\Reversi\\';

if (!str_starts_with($class, $prefix)) {
return;
}

$relativeClass = substr($class, strlen($prefix));
$path = __DIR__ . '/../modules/php/' . str_replace('\\', '/', $relativeClass) . '.php';

if (file_exists($path)) {
require_once $path;
}
});
</pre>

====Create first tests====
Example of tests for Reversi:

'''tests/BoardManagerTest.php'''
<pre>
<?php

declare(strict_types=1);

namespace Tests;

use Bga\Games\Reversi\BoardManager;
use Bga\Games\Reversi\Game;
use PHPUnit\Framework\TestCase;

final class BoardManagerTest extends TestCase
{
public function testGetPossibleMovesOnInitialBoardForBlackPlayer(): void
{
$board = $this->createEmptyBoard(8);
$board[4][4] = 2;
$board[5][5] = 2;
$board[4][5] = 1;
$board[5][4] = 1;

$game = $this->createGame(8);
$boardManager = $this->createBoardManager($game, $board);

$moves = $boardManager->getPossibleMoves(1);

self::assertSame(
[
3 => [4 => true],
4 => [3 => true],
5 => [6 => true],
6 => [5 => true],
],
$moves,
);
}

public function testGetPossibleMovesReturnsEmptyArrayWhenNoMoveExists(): void
{
$board = $this->createEmptyBoard(4);
for ($x = 1; $x <= 4; $x++) {
for ($y = 1; $y <= 4; $y++) {
$board[$x][$y] = 1;
}
}

$game = $this->createGame(4);
$boardManager = $this->createBoardManager($game, $board);

self::assertSame([], $boardManager->getPossibleMoves(2));
}

private function createGame(int $boardSize): Game
{
$game = $this->createStub(Game::class);
$game->method('getBoardSize')->willReturn($boardSize);

return $game;
}

private function createBoardManager(Game $game, array $board): BoardManager
{
return new class ($game, $board) extends BoardManager {
public function __construct(Game $game, private array $board)
{
parent::__construct($game);
}

public function getBoard(): array
{
return $this->board;
}
};
}

private function createEmptyBoard(int $size): array
{
$board = [];
for ($x = 1; $x <= $size; $x++) {
$board[$x] = [];
for ($y = 1; $y <= $size; $y++) {
$board[$x][$y] = null;
}
}

return $board;
}
}
</pre>

'''tests/States/NextPlayerTest.php'''
<pre>
<?php

declare(strict_types=1);

namespace Tests\States;

use Bga\Games\Reversi\BoardManager;
use Bga\Games\Reversi\Game;
use Bga\Games\Reversi\States\NextPlayer;
use PHPUnit\Framework\TestCase;

final class NextPlayerTest extends TestCase
{
public function testReturnsEndScoreWhenNoFreeSquareLeft(): void
{
$game = $this->createGame();
$this->attachBoardManager($game, $this->createBoardManagerStub(0, []));

$state = new NextPlayer($game);

self::assertSame('Bga\\Games\\Reversi\\States\\EndScore', $state->onEnteringState());
}

public function testGivesExtraTimeAndReturnsPlayDiscWhenPlayerCanMove(): void
{
$game = $this->createGameMock();
$game->expects(self::once())
->method('giveExtraTime')
->with(1, null);
$this->attachBoardManager($game, $this->createBoardManagerStub(5, [1 => 4, 2 => 4], [1 => [4 => [3 => true]]]));

$state = new NextPlayer($game);

self::assertSame('Bga\\Games\\Reversi\\States\\PlayDisc', $state->onEnteringState());
}

private function createGame(int $activePlayerId = 1, int $playerAfterId = 2): Game
{
$game = $this->createStub(Game::class);
$game->method('activeNextPlayer')->willReturn($activePlayerId);
$game->method('getPlayerAfter')->willReturn($playerAfterId);

return $game;
}

private function createGameMock(int $activePlayerId = 1, int $playerAfterId = 2): Game
{
$game = $this->getMockBuilder(Game::class)
->disableOriginalConstructor()
->onlyMethods(['activeNextPlayer', 'getPlayerAfter', 'giveExtraTime'])
->getMock();
$game->method('activeNextPlayer')->willReturn($activePlayerId);
$game->method('getPlayerAfter')->willReturn($playerAfterId);

return $game;
}

private function createBoardManagerStub(int $freeSquares, array $discsByPlayer, array $possibleMovesByPlayer = []): BoardManager
{
$boardManager = $this->createStub(BoardManager::class);
$boardManager->method('countFreeSquares')->willReturn($freeSquares);
$boardManager->method('getDiscCountsByPlayer')->willReturn($discsByPlayer);
$boardManager->method('getPossibleMoves')->willReturnCallback(
static fn (int $playerId): array => $possibleMovesByPlayer[$playerId] ?? []
);

return $boardManager;
}

private function attachBoardManager(Game $game, BoardManager $boardManager): void
{
$game->boardManager = $boardManager;
}
}
</pre>

====Running the tests====
Run the tests using
phpunit

If you want to run a single test file
phpunit tests/BoardManagerTest.php

If you want to run a single test
phpunit --filter testGivesExtraTime

<i>If you came here from Reversi Tutorial, go back to it https://en.doc.boardgamearena.com/Tutorial_reversi#Optional:_add_unit_tests</i>

== Play testing on studio ==

To play test on studio you can use your test accounts dev0... dev9. You can give some of these account to other people just make sure you change the password.
You should not encourage other people who are not developers to create studio account, this is against bga policy.

Testing by developer

2026-03-14T13:07:15Z

Victoria La: js testing

When you develop a game you obviously have to test it, this page collects the info about testing in one place

== Manual Testing on BGA ==

For manual testing the most important things to know are:
* how to start/stop game in one click
* how to switch between players in one click
* how to save/restore the game state
* how to construct the game state automatically
All of these described here https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio

There is also HUGE checklist of things you need to test manually which you may not even think about, defined here https://en.doc.boardgamearena.com/Pre-release_checklist

== Manual Testing locally ==

'''HTML/CSS'''
At this era the file sync is almost instant so you do not save much by doing this locally, however if internet is a challenge - here are some tips
https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout

'''PHP'''
You can run and debug php locally using tip https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally

== Automated Testing ==
===JavaScript===

I did not try for pure java script, it works for typescript.
You need dev dependency on mocha, jsdom and sinon and some other build tools.
Typescript code lives in src/.
Test code lives in src/tests/.
Tests have their own src/tests/tsconfig.json
File src/tests/setup.ts contains framework and global stubs that tests need.
The config is very verbose so I did not copy it here, if interested check project "fate" or bga-fate on github.

===PHP===

====Install PHPunit====

Install PHPunit via composer somewhere in home directory, i.e.
cd /home/<yourusername>/php-composer
composer require --dev phpunit/phpunit ^13

We don't want the phpunit cache to be sync/commited, so add <code>".phpunit.cache"</code> to sftp.json ignore list. You can push the unit tests to the FTP, no need to ignore them. If someone maintains your game in the future, he willl be able to use them to make sure nothing breaks on an update!
If you have a .gitignore, add <code>.phpunit.cache</code> to it.

Then add this to your .bashrc (alias function to be able to test phpunit easily)
phpunit() {
/home/<yourusername>/php-composer/vendor/bin/phpunit \
-c "$PWD/phpunit.xml.dist" \
--bootstrap "$PWD/tests/bootstrap.php" \
"$@"
}

With that, on a new terminal you will be able to run the tests with one of the following commands at the root of your project :
phpunit
phpunit tests/BoardManagerTest.php
phpunit --filter testGivesExtraTime

====Setup minimal files====
Create these files:

'''phpunit.xml.dist'''
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="tests/bootstrap.php"
colors="true"
cacheDirectory=".phpunit.cache">
<testsuites>
<testsuite name="Reversi">
<directory>tests</directory>
</testsuite>
</testsuites>
</phpunit>
</pre>
(replace Reversi by your project name)

'''tests/bootstrap.php'''
<pre>
<?php

declare(strict_types=1);

require_once __DIR__ . '/stubs/BgaFrameworkStubs.php';

$autoload = __DIR__ . '/../vendor/autoload.php';
if (file_exists($autoload)) {
require_once $autoload;
}

spl_autoload_register(static function (string $class): void {
$prefix = 'Bga\\Games\\Reversi\\';

if (!str_starts_with($class, $prefix)) {
return;
}

$relativeClass = substr($class, strlen($prefix));
$path = __DIR__ . '/../modules/php/' . str_replace('\\', '/', $relativeClass) . '.php';

if (file_exists($path)) {
require_once $path;
}
});
</pre>
(replace Reversi by your project name)

'''tests/stubs/BgaFrameworkStubs.php'''
<pre>
<?php

declare(strict_types=1);

require_once __DIR__ . '/stubs/BgaFrameworkStubs.php';

$autoload = __DIR__ . '/../vendor/autoload.php';
if (file_exists($autoload)) {
require_once $autoload;
}

spl_autoload_register(static function (string $class): void {
$prefix = 'Bga\\Games\\Reversi\\';

if (!str_starts_with($class, $prefix)) {
return;
}

$relativeClass = substr($class, strlen($prefix));
$path = __DIR__ . '/../modules/php/' . str_replace('\\', '/', $relativeClass) . '.php';

if (file_exists($path)) {
require_once $path;
}
});
</pre>

====Create first tests====
Example of tests for Reversi:

'''tests/BoardManagerTest.php'''
<pre>
<?php

declare(strict_types=1);

namespace Tests;

use Bga\Games\Reversi\BoardManager;
use Bga\Games\Reversi\Game;
use PHPUnit\Framework\TestCase;

final class BoardManagerTest extends TestCase
{
public function testGetPossibleMovesOnInitialBoardForBlackPlayer(): void
{
$board = $this->createEmptyBoard(8);
$board[4][4] = 2;
$board[5][5] = 2;
$board[4][5] = 1;
$board[5][4] = 1;

$game = $this->createGame(8);
$boardManager = $this->createBoardManager($game, $board);

$moves = $boardManager->getPossibleMoves(1);

self::assertSame(
[
3 => [4 => true],
4 => [3 => true],
5 => [6 => true],
6 => [5 => true],
],
$moves,
);
}

public function testGetPossibleMovesReturnsEmptyArrayWhenNoMoveExists(): void
{
$board = $this->createEmptyBoard(4);
for ($x = 1; $x <= 4; $x++) {
for ($y = 1; $y <= 4; $y++) {
$board[$x][$y] = 1;
}
}

$game = $this->createGame(4);
$boardManager = $this->createBoardManager($game, $board);

self::assertSame([], $boardManager->getPossibleMoves(2));
}

private function createGame(int $boardSize): Game
{
$game = $this->createStub(Game::class);
$game->method('getBoardSize')->willReturn($boardSize);

return $game;
}

private function createBoardManager(Game $game, array $board): BoardManager
{
return new class ($game, $board) extends BoardManager {
public function __construct(Game $game, private array $board)
{
parent::__construct($game);
}

public function getBoard(): array
{
return $this->board;
}
};
}

private function createEmptyBoard(int $size): array
{
$board = [];
for ($x = 1; $x <= $size; $x++) {
$board[$x] = [];
for ($y = 1; $y <= $size; $y++) {
$board[$x][$y] = null;
}
}

return $board;
}
}
</pre>

'''tests/States/NextPlayerTest.php'''
<pre>
<?php

declare(strict_types=1);

namespace Tests\States;

use Bga\Games\Reversi\BoardManager;
use Bga\Games\Reversi\Game;
use Bga\Games\Reversi\States\NextPlayer;
use PHPUnit\Framework\TestCase;

final class NextPlayerTest extends TestCase
{
public function testReturnsEndScoreWhenNoFreeSquareLeft(): void
{
$game = $this->createGame();
$this->attachBoardManager($game, $this->createBoardManagerStub(0, []));

$state = new NextPlayer($game);

self::assertSame('Bga\\Games\\Reversi\\States\\EndScore', $state->onEnteringState());
}

public function testGivesExtraTimeAndReturnsPlayDiscWhenPlayerCanMove(): void
{
$game = $this->createGameMock();
$game->expects(self::once())
->method('giveExtraTime')
->with(1, null);
$this->attachBoardManager($game, $this->createBoardManagerStub(5, [1 => 4, 2 => 4], [1 => [4 => [3 => true]]]));

$state = new NextPlayer($game);

self::assertSame('Bga\\Games\\Reversi\\States\\PlayDisc', $state->onEnteringState());
}

private function createGame(int $activePlayerId = 1, int $playerAfterId = 2): Game
{
$game = $this->createStub(Game::class);
$game->method('activeNextPlayer')->willReturn($activePlayerId);
$game->method('getPlayerAfter')->willReturn($playerAfterId);

return $game;
}

private function createGameMock(int $activePlayerId = 1, int $playerAfterId = 2): Game
{
$game = $this->getMockBuilder(Game::class)
->disableOriginalConstructor()
->onlyMethods(['activeNextPlayer', 'getPlayerAfter', 'giveExtraTime'])
->getMock();
$game->method('activeNextPlayer')->willReturn($activePlayerId);
$game->method('getPlayerAfter')->willReturn($playerAfterId);

return $game;
}

private function createBoardManagerStub(int $freeSquares, array $discsByPlayer, array $possibleMovesByPlayer = []): BoardManager
{
$boardManager = $this->createStub(BoardManager::class);
$boardManager->method('countFreeSquares')->willReturn($freeSquares);
$boardManager->method('getDiscCountsByPlayer')->willReturn($discsByPlayer);
$boardManager->method('getPossibleMoves')->willReturnCallback(
static fn (int $playerId): array => $possibleMovesByPlayer[$playerId] ?? []
);

return $boardManager;
}

private function attachBoardManager(Game $game, BoardManager $boardManager): void
{
$game->boardManager = $boardManager;
}
}
</pre>

====Running the tests====
Run the tests using
phpunit

If you want to run a single test file
phpunit tests/BoardManagerTest.php

If you want to run a single test
phpunit --filter testGivesExtraTime

<i>If you came here from Reversi Tutorial, go back to it https://en.doc.boardgamearena.com/Tutorial_reversi#Optional:_add_unit_tests</i>

== Play testing on studio ==

To play test on studio you can use your test accounts dev0... dev9. You can give some of these account to other people just make sure you change the password.
You should not encourage other people who are not developers to create studio account, this is against bga policy.

Setting up BGA Development environment using VSCode

2026-03-14T12:54:15Z

Victoria La: /* User templates */

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==
* Download and install vscode from https://code.visualstudio.com
* Download and install php (8.4) command line interface (for local tests and debugging - optional)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===

* Since BGA framework ditched dojo in 2025 we can rejoice and enjoy full ide support. If you try it for old dojo projects - it does not really work.

* A good way to improve auto-complete and such is to use Typescript and SCSS, this is not for the beginners.
** Original wiki: https://en.doc.boardgamearena.com/Using_Typescript_and_Scss

===PHP Intellisense===

The "_ide_helper.php" file, included in every project, will help your IDE know the available functions of the framework. This file may be updated automatically on your FTP folder, so don't hesitate to pull it back if it misses something, it might have been updated!

To solve the warning about the material file class members (warning only appears if you use legacy material file)

Option 1) You can define them as class attributes, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private array $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

===Unit testing===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/<yourusername>/php-composer
composer require --dev phpunit/phpunit ^13

Then add this path to include paths in settings

"intelephense.environment.includePaths": [
"/home/<yourusername>/php-composer"
],

See more about unit testing in [[Testing by developer]]

== File Sync==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

*'''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

*'''Open VSCode on an empty folder''' that will be the local root of your project.

*Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store",
"package-lock.json",
"yarn.lock",
"misc",
"node_modules",
"_ide_helper.php",
"bga-framework.d.ts",
"* *",
"sync-helpers.sh",
"vendor",
".phpunit.cache"
],
"syncOption": {
"skipCreate": false,
"delete": true
}
}
</pre>

* syncOption delete: true - means you want to delete remote file if deleted locally
* syncOption skipCreate: false - means you want to add new files when added locally (false because its reverse option)
* remotePath - do not remove slashes, it is part of the path

===One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

After initially downloading the project, you can add _ide_helper.php to the "ignore" list. Even though it is needed locally for the IDE to understand BGA-related php code, you will never need to update it.
=== Daily use===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.
=== Split settings for version control===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

==Code Formatter==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.22",
"prettier": "^3.6"
},
"prettier": {
"plugins": ["@prettier/plugin-php"],
"braceStyle": "1tbs",
"printWidth": 140,
"trailingComma": "none"
}

== Code generators==
If you want to run code generators for example for typescript or scss you can install this extension:
*https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>
[[Category:Studio]]

Setting up BGA Development environment using VSCode

2026-03-14T12:52:48Z

Victoria La: /* PHP Intellisense */

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==
* Download and install vscode from https://code.visualstudio.com
* Download and install php (8.4) command line interface (for local tests and debugging - optional)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===

* Since BGA framework ditched dojo in 2025 we can rejoice and enjoy full ide support. If you try it for old dojo projects - it does not really work.

* A good way to improve auto-complete and such is to use Typescript and SCSS, this is not for the beginners.
** Original wiki: https://en.doc.boardgamearena.com/Using_Typescript_and_Scss

===PHP Intellisense===

The "_ide_helper.php" file, included in every project, will help your IDE know the available functions of the framework. This file may be updated automatically on your FTP folder, so don't hesitate to pull it back if it misses something, it might have been updated!

To solve the warning about the material file class members (warning only appears if you use legacy material file)

Option 1) You can define them as class attributes, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private array $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

===Unit testing===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/<yourusername>/php-composer
composer require --dev phpunit/phpunit ^13

Then add this path to include paths in settings

"intelephense.environment.includePaths": [
"/home/<yourusername>/php-composer"
],

See more about unit testing in [[Testing by developer]]

== File Sync==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

*'''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

*'''Open VSCode on an empty folder''' that will be the local root of your project.

*Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store",
"package-lock.json",
"yarn.lock",
"misc",
"node_modules",
"_ide_helper.php",
"bga-framework.d.ts",
"* *",
"sync-helpers.sh",
"vendor",
".phpunit.cache"
],
"syncOption": {
"skipCreate": false,
"delete": true
}
}
</pre>

* syncOption delete: true - means you want to delete remote file if deleted locally
* syncOption skipCreate: false - means you want to add new files when added locally (false because its reverse option)
* remotePath - do not remove slashes, it is part of the path

===One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

After initially downloading the project, you can add _ide_helper.php to the "ignore" list. Even though it is needed locally for the IDE to understand BGA-related php code, you will never need to update it.
=== Daily use===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.
=== Split settings for version control===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

==Code Formatter==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.22",
"prettier": "^3.6"
},
"prettier": {
"plugins": ["@prettier/plugin-php"],
"braceStyle": "1tbs",
"printWidth": 140,
"trailingComma": "none"
}

== Code generators==
If you want to run code generators for example for typescript or scss you can install this extension:
*https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Single player state": {
"prefix": ["state", "playerstate"],

"body": [
"$LINE_COMMENT playerTurn${1:something}",
"${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'playerTurn${1:something}',",
"'description' => clienttranslate('\\${actplayer} must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'activeplayer',",
"'args'=>'arg_playerTurn${1:something}',",
"'action'=>'st_playerTurn${1:something}',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_PLAYER,",
"'loopback' => ${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create single player state defition, use tab to fill template parameters"
},

"Multiple player state": {
"prefix": ["mstate", "multiplayerstate"],

"body": [
"$LINE_COMMENT mplayerTurn${1:something}",
"${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'mplayerTurn${1:something}',",
"'description' => clienttranslate('Other players must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'multipleactiveplayer',",
"'args'=>'arg_mplayerTurn${1:something}',",
"'action'=>'stMakeEveryoneActive',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_MPLAYER,",
"'loopback' => ${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create multi player state defition, use tab to fill template parameters"
},
"Action in action.php": {
"prefix": ["action"],
"body": [
"public function ${1:actionName}() {",
"\tself::setAjaxMode();",
"\t\\$${2:arg} = self::getArg('${2:arg}', AT_posint, false, 0);",
"\t\\$this->game->action_${1:actionName}(\\$${2:arg});",
"\tself::ajaxResponse();",
"}"
]
},
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>
[[Category:Studio]]

Setting up BGA Development environment using VSCode

2026-03-14T12:51:35Z

Victoria La: /* JavaScript Intellisense */

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==
* Download and install vscode from https://code.visualstudio.com
* Download and install php (8.4) command line interface (for local tests and debugging - optional)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===

* Since BGA framework ditched dojo in 2025 we can rejoice and enjoy full ide support. If you try it for old dojo projects - it does not really work.

* A good way to improve auto-complete and such is to use Typescript and SCSS, this is not for the beginners.
** Original wiki: https://en.doc.boardgamearena.com/Using_Typescript_and_Scss

===PHP Intellisense===

The ide_helper file, included in every project, will help your IDE know the available functions of the framework. This file may be updated automatically on your FTP folder, so don't hesitate to pull it back if it misses something, it might have been updated!

To solve the warning about the material file class members (warning only appears if you use legacy material file)

Option 1) You can define them as class attributes, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private array $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

===Unit testing===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/<yourusername>/php-composer
composer require --dev phpunit/phpunit ^13

Then add this path to include paths in settings

"intelephense.environment.includePaths": [
"/home/<yourusername>/php-composer"
],

See more about unit testing in [[Testing by developer]]

== File Sync==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

*'''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

*'''Open VSCode on an empty folder''' that will be the local root of your project.

*Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store",
"package-lock.json",
"yarn.lock",
"misc",
"node_modules",
"_ide_helper.php",
"bga-framework.d.ts",
"* *",
"sync-helpers.sh",
"vendor",
".phpunit.cache"
],
"syncOption": {
"skipCreate": false,
"delete": true
}
}
</pre>

* syncOption delete: true - means you want to delete remote file if deleted locally
* syncOption skipCreate: false - means you want to add new files when added locally (false because its reverse option)
* remotePath - do not remove slashes, it is part of the path

===One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

After initially downloading the project, you can add _ide_helper.php to the "ignore" list. Even though it is needed locally for the IDE to understand BGA-related php code, you will never need to update it.
=== Daily use===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.
=== Split settings for version control===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

==Code Formatter==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.22",
"prettier": "^3.6"
},
"prettier": {
"plugins": ["@prettier/plugin-php"],
"braceStyle": "1tbs",
"printWidth": 140,
"trailingComma": "none"
}

== Code generators==
If you want to run code generators for example for typescript or scss you can install this extension:
*https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Single player state": {
"prefix": ["state", "playerstate"],

"body": [
"$LINE_COMMENT playerTurn${1:something}",
"${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'playerTurn${1:something}',",
"'description' => clienttranslate('\\${actplayer} must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'activeplayer',",
"'args'=>'arg_playerTurn${1:something}',",
"'action'=>'st_playerTurn${1:something}',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_PLAYER,",
"'loopback' => ${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create single player state defition, use tab to fill template parameters"
},

"Multiple player state": {
"prefix": ["mstate", "multiplayerstate"],

"body": [
"$LINE_COMMENT mplayerTurn${1:something}",
"${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'mplayerTurn${1:something}',",
"'description' => clienttranslate('Other players must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'multipleactiveplayer',",
"'args'=>'arg_mplayerTurn${1:something}',",
"'action'=>'stMakeEveryoneActive',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_MPLAYER,",
"'loopback' => ${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create multi player state defition, use tab to fill template parameters"
},
"Action in action.php": {
"prefix": ["action"],
"body": [
"public function ${1:actionName}() {",
"\tself::setAjaxMode();",
"\t\\$${2:arg} = self::getArg('${2:arg}', AT_posint, false, 0);",
"\t\\$this->game->action_${1:actionName}(\\$${2:arg});",
"\tself::ajaxResponse();",
"}"
]
},
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>
[[Category:Studio]]

Setting up BGA Development environment using VSCode

2026-03-14T12:51:06Z

Victoria La: /* Intellisense - Navigation/Auto-complete */

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==
* Download and install vscode from https://code.visualstudio.com
* Download and install php (8.4) command line interface (for local tests and debugging - optional)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===

* Since BGA framework ditched dojo in 2025 we can rejoice and enjoy full ide support. If try it for old dojo projects - it does not really work.

* A good way to improve auto-complete and such is to use Typescript and SCSS, this is not for the beginners.
** Original wiki: https://en.doc.boardgamearena.com/Using_Typescript_and_Scss

===PHP Intellisense===

The ide_helper file, included in every project, will help your IDE know the available functions of the framework. This file may be updated automatically on your FTP folder, so don't hesitate to pull it back if it misses something, it might have been updated!

To solve the warning about the material file class members (warning only appears if you use legacy material file)

Option 1) You can define them as class attributes, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private array $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

===Unit testing===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/<yourusername>/php-composer
composer require --dev phpunit/phpunit ^13

Then add this path to include paths in settings

"intelephense.environment.includePaths": [
"/home/<yourusername>/php-composer"
],

See more about unit testing in [[Testing by developer]]

== File Sync==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

*'''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

*'''Open VSCode on an empty folder''' that will be the local root of your project.

*Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store",
"package-lock.json",
"yarn.lock",
"misc",
"node_modules",
"_ide_helper.php",
"bga-framework.d.ts",
"* *",
"sync-helpers.sh",
"vendor",
".phpunit.cache"
],
"syncOption": {
"skipCreate": false,
"delete": true
}
}
</pre>

* syncOption delete: true - means you want to delete remote file if deleted locally
* syncOption skipCreate: false - means you want to add new files when added locally (false because its reverse option)
* remotePath - do not remove slashes, it is part of the path

===One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

After initially downloading the project, you can add _ide_helper.php to the "ignore" list. Even though it is needed locally for the IDE to understand BGA-related php code, you will never need to update it.
=== Daily use===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.
=== Split settings for version control===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

==Code Formatter==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.22",
"prettier": "^3.6"
},
"prettier": {
"plugins": ["@prettier/plugin-php"],
"braceStyle": "1tbs",
"printWidth": 140,
"trailingComma": "none"
}

== Code generators==
If you want to run code generators for example for typescript or scss you can install this extension:
*https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Single player state": {
"prefix": ["state", "playerstate"],

"body": [
"$LINE_COMMENT playerTurn${1:something}",
"${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'playerTurn${1:something}',",
"'description' => clienttranslate('\\${actplayer} must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'activeplayer',",
"'args'=>'arg_playerTurn${1:something}',",
"'action'=>'st_playerTurn${1:something}',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_PLAYER,",
"'loopback' => ${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create single player state defition, use tab to fill template parameters"
},

"Multiple player state": {
"prefix": ["mstate", "multiplayerstate"],

"body": [
"$LINE_COMMENT mplayerTurn${1:something}",
"${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'mplayerTurn${1:something}',",
"'description' => clienttranslate('Other players must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'multipleactiveplayer',",
"'args'=>'arg_mplayerTurn${1:something}',",
"'action'=>'stMakeEveryoneActive',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_MPLAYER,",
"'loopback' => ${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create multi player state defition, use tab to fill template parameters"
},
"Action in action.php": {
"prefix": ["action"],
"body": [
"public function ${1:actionName}() {",
"\tself::setAjaxMode();",
"\t\\$${2:arg} = self::getArg('${2:arg}', AT_posint, false, 0);",
"\t\\$this->game->action_${1:actionName}(\\$${2:arg});",
"\tself::ajaxResponse();",
"}"
]
},
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>
[[Category:Studio]]