https://en.doc.boardgamearena.com/api.php?action=feedcontributions&user=Volker78&feedformat=atomBoard Game Arena - User contributions [en]2024-03-29T12:57:57ZUser contributionsMediaWiki 1.39.0https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_yourgamename.game.php&diff=7604Main game logic: yourgamename.game.php2021-03-11T20:10:21Z<p>Volker78: /* Legacy games API */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
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.<br />
<br />
== File Structure ==<br />
<br />
The details of how the file is structured are described directly with comments in the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* Constructor: where you define global variables.<br />
* 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.<br />
* getAllDatas: where you retrieve all game data during a complete reload of the game. Returned value must include ['players'][playerId]['score'] for scores to populate when F5 is pressed.<br />
* getGameProgression: where you compute the game progression indicator.<br />
* Utility functions: your utility functions.<br />
* Player actions: the entry points for players actions. <br />
* 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]).<br />
* 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]).<br />
* zombieTurn: what to do it's the turn of a zombie player.<br />
* upgradeTableDb: function to migrate database if you change it after release on production.<br />
<br />
== Accessing player information ==<br />
<br />
'''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!<br />
<br />
<br />
; getPlayersNumber()<br />
: Returns the number of players playing at the table<br />
: Note: doesn't work in setupNewGame (use count($players) instead).<br />
<br />
; getActivePlayerId()<br />
: Get the "active_player", whatever what is the current state type.<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getActivePlayerName()<br />
: Get the "active_player" name<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; loadPlayersBasicInfos()<br />
: Get an associative array with generic data about players (ie: not game specific data).<br />
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.<br />
: The content of each value is:<br />
: * player_name - the name of the player<br />
: * player_color (ex: ff0000) - the color code of the player<br />
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3<br />
<br />
; getCurrentPlayerId()<br />
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).<br />
: '''Be careful''': This is not necessarily the active player!<br />
: In general, you shouldn't use this method, unless you are in "multiplayer" state.<br />
: '''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).<br />
<br />
; getCurrentPlayerName()<br />
: Get the "current_player" name<br />
: Be careful using this method (see above).<br />
<br />
; getCurrentPlayerColor()<br />
: Get the "current_player" color<br />
: Be careful using this method (see above).<br />
<br />
; isCurrentPlayerZombie()<br />
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.<br />
<br />
; isSpectator()<br />
: 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).<br />
<br />
; getActivePlayerColor()<br />
: This function does not seems to exist in API, if you need it here is implementation<br />
function getActivePlayerColor() {<br />
$player_id = self::getActivePlayerId();<br />
$players = self::loadPlayersBasicInfos();<br />
if( isset( $players[ $player_id ]) )<br />
return $players[ $player_id ]['player_color'];<br />
else<br />
return null;<br />
}<br />
<br />
== Accessing the database ==<br />
<br />
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.<br />
<br />
'''IMPORTANT'''<br />
<br />
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.<br />
<br />
; DbQuery( $sql )<br />
: This is the generic method to access the database.<br />
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database.<br />
: You should use it for UPDATE/DELETE/REPLACE/INSERT queries. For SELECT queries, the specialized methods below are much better.<br />
<br />
; getUniqueValueFromDB( $sql )<br />
: Returns a unique value from DB or null if no value is found.<br />
: $sql must be a SELECT query.<br />
: Raise an exception if more than 1 row is returned.<br />
<br />
; getCollectionFromDB( $sql, $bSingleValue=false )<br />
: Returns an associative array of rows for a sql SELECT query.<br />
: The key of the resulting associative array is the first field specified in the SELECT query.<br />
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.<br />
: First column must be a primary or alternate key.<br />
: The resulting collection can be empty.<br />
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"<br />
<br />
Example 1:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
1234 => 'myuser0',<br />
1235 => 'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getNonEmptyCollectionFromDB( $sql )<br />
: 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.<br />
<br />
; getObjectFromDB( $sql )<br />
: Returns one row for the sql SELECT query as an associative array or null if there is no result<br />
: Raise an exception if the query return more than one row<br />
<br />
Example:<br />
<pre><br />
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );<br />
<br />
Result:<br />
array(<br />
'id'=>1234, 'name'=>'myuser0', 'score'=>1 <br />
)<br />
</pre><br />
<br />
; getNonEmptyObjectFromDB( $sql )<br />
: Similar to previous one, but raise an exception if no row is found<br />
<br />
; getObjectListFromDB( $sql, $bUniqueValue=false )<br />
: Return an array of rows for a sql SELECT query.<br />
: The result is the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).<br />
: The result can be empty.<br />
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.<br />
<br />
Example 1:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
'myuser0',<br />
'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )<br />
: Return an associative array of associative array, from a SQL SELECT query.<br />
: First array level correspond to first column specified in SQL query.<br />
: Second array level correspond to second column specified in SQL query.<br />
: If bSingleValue = true, keep only third column on result<br />
<br />
<br />
; DbGetLastId()<br />
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).<br />
<br />
; DbAffectedRow()<br />
: Return the number of row affected by the last operation<br />
<br />
; escapeStringForDB( $string )<br />
: You must use this function on every string type data in your database that contains unsafe data.<br />
: (unsafe = can be modified by a player).<br />
: This method makes sure that no SQL injection will be done through the string used.<br />
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,<br />
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.<br />
<br />
<pre><br />
<br />
<br />
</pre><br />
<br />
Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.<br />
<br />
== Use globals ==<br />
<br />
Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.<br />
<br />
You can do this with the BGA framework "global." Your value will be stored in the "global" table in the database, and you can access it with simple methods.<br />
<br />
'''initGameStateLabels'''<br />
<br />
This method should be located at the beginning of ''yourgamename.php.'' This is where you define the globals used in your game logic, by assigning them IDs.<br />
<br />
You can define up to 80 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11<br />
) );<br />
</pre><br />
<br />
'''setGameStateInitialValue( $value_label, $value_value )'''<br />
<br />
Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method.<br />
<br />
'''getGameStateValue( $value_label )'''<br />
<br />
Retrieve the current value of a global.<br />
<br />
'''setGameStateValue( $value_label, $value_value )'''<br />
<br />
Set the current value of a global.<br />
<br />
'''incGameStateValue( $value_label, $increment )'''<br />
<br />
Increment the current value of a global. If increment is negative, decrement the value of the global.<br />
<br />
Return the final value of the global.<br />
<br />
== Game states and active players ==<br />
<br />
<br />
=== Activate player handling ===<br />
<br />
; $this->activeNextPlayer()<br />
: Make the next player active in the natural player order.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->activePrevPlayer()<br />
: Make the previous player active (in the natural player order).<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->gamestate->changeActivePlayer( $player_id )<br />
: You can call this method to make any player active.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->getActivePlayerId()<br />
: Return the "active_player" id<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"<br />
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.<br />
<br />
=== Multiple activate player handling ===<br />
<br />
; $this->gamestate->setAllPlayersMultiactive()<br />
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').<br />
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)<br />
<br />
Example of usage:<br />
<pre><br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
</pre><br />
<br />
And this is the state declaration:<br />
<pre><br />
2 => array(<br />
"name" => "playerTurnPlace",<br />
"description" => clienttranslate('Other player must place ships'),<br />
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),<br />
"type" => "multipleactiveplayer",<br />
'action' => 'multiPlayerDoSomething',<br />
'args' => 'arg_playerTurnPlace',<br />
"possibleactions" => array( "actionBla" ),<br />
"transitions" => array( "next" => 4, "last" => 99)<br />
),<br />
</pre><br />
<br />
; $this->gamestate->setAllPlayersNonMultiactive( $next_state )<br />
: All playing players are made inactive. Transition to next state<br />
<br />
; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )<br />
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.<br />
: "players" is the array of player id that should be made active.<br />
: If "exclusive" 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<br />
<br />
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )<br />
: During a multiactive game state, make the specified player inactive.<br />
: 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.<br />
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
Example of usage (see state declaration of playerTurnPlace above):<br />
<pre><br />
function actionBla($args) {<br />
self::checkAction('actionBla');<br />
// handle the action using $this->getCurrentPlayerId()<br />
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');<br />
}<br />
</pre><br />
<br />
; $this->gamestate->getActivePlayerList()<br />
: With this method you can retrieve the list of the active player at any time.<br />
: During a "game" type gamestate, it will return a void array.<br />
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).<br />
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.<br />
: Note: you should only use this method in the latter case.<br />
<br />
<br />
<br />
; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )<br />
: 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.<br />
Example: you have player teams and you want to activate all players in one team<br />
<pre><br />
$sql = "UPDATE player SET player_is_multiactive='0'";<br />
self::DbQuery( $sql );<br />
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";<br />
self::DbQuery( $sql );<br />
<br />
$this->gamestate->updateMultiactiveOrNextState( 'error' );<br />
</pre><br />
<br />
; updating database manually<br />
: Use this helper function to change multiactive state without sending notification<br />
<pre><br />
/**<br />
* Changes values of multiactivity in db, does not sent notifications.<br />
* To send notifications after use updateMultiactiveOrNextState<br />
* @param number $player_id, player id <=0 or null - means ALL<br />
* @param number $value - 1 multiactive, 0 non multiactive<br />
*/<br />
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {<br />
if (! $value)<br />
$value = 0;<br />
else<br />
$value = 1;<br />
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";<br />
if ($player_id > 0) {<br />
$sql .= " AND player_id = $player_id";<br />
}<br />
self::DbQuery($sql);<br />
}<br />
</pre><br />
<br />
=== States functions ===<br />
; $this->gamestate->nextState( $transition )<br />
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.<br />
<br />
; $this->checkAction( $actionName, $bThrowException=true )<br />
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.<br />
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).<br />
: This method MUST be the first one called in ALL your PHP methods that handle player actions, 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.<br />
: 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.<br />
<br />
; $this->gamestate->checkPossibleAction( $action )<br />
: (rarely used)<br />
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.<br />
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.<br />
: 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.<br />
<br />
This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute on js side do not checkAction on js side for this specific one.<br />
<br />
function actionUnpass() {<br />
$this->gamestate->checkPossibleAction('actionUnpass'); // player chane mind about passing while others were thinking<br />
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);<br />
}<br />
<br />
; $this->gamestate->state()<br />
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.<br />
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}<br />
<br />
== Players turn order ==<br />
<br />
'''getNextPlayerTable()'''<br />
<br />
Return an associative array which associate each player with the next player around the table.<br />
<br />
In addition, key 0 is associated to the first player to play.<br />
<br />
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:<br />
<pre><br />
array( <br />
1 => 2, <br />
2 => 3, <br />
3 => 1, <br />
0 => 1 <br />
);<br />
</pre><br />
<br />
'''getPrevPlayerTable()'''<br />
<br />
Same as above, but the associative array associate the previous player around the table. However there no 0 index here.<br />
<br />
'''getPlayerAfter( $player_id )'''<br />
<br />
Get player playing after given player in natural playing order.<br />
<br />
'''getPlayerBefore( $player_id )'''<br />
<br />
Get player playing before given player in natural playing order.<br />
<br />
Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database<br />
and have custom function to access it.<br />
<br />
'''createNextPlayerTable( $players, $bLoop=true )'''<br />
<br />
Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here. <br />
Parmeter $bLoop is true if last player points to first, false otherwise.<br />
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.<br />
<br />
Example of usage:<br />
<pre><br />
function getNextPlayerTableCustom() {<br />
$starting = $this->getStartingPlayer(); // custom function to get starting player<br />
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player<br />
return self::createNextPlayerTable($player_ids, false); // create next player table in custom order<br />
}<br />
</pre><br />
<br />
== Notify players ==<br />
<br />
To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.<br />
<br />
'''IMPORTANT'''<br />
<br />
Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.<br />
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.<br />
<br />
'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''<br />
<br />
Send a notification to all players of the game.<br />
<br />
* notification_type:<br />
A string that defines the type of your notification.<br />
<br />
Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).<br />
<br />
* notification_log:<br />
A string that defines what is to be displayed in the game log.<br />
<br />
You can use an empty string here (""). In this case, nothing is displayed in the game log.<br />
<br />
If you define a real string here, you should use "clienttranslate" method to make sure it can be translate.<br />
<br />
You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below). <br />
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.<br />
<br />
<br />
<br />
* notification_args:<br />
The arguments of your notifications, as an associative array.<br />
<br />
This array will be transmitted to the game interface logic, in order the game interface can be updated.<br />
<br />
Complete notifyAllPlayers example (from "Reversi"):<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
</pre><br />
<br />
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.<br />
<br />
'''Important''': NO private data must be sent with this method, as a cheater could see it even it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.<br />
<br />
'''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.<br />
<br />
Note: you CAN use some HTML inside your notification log, however it not recommended for many reasons:<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games reply and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game reply, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.<br />
<br />
If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].<br />
<br />
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<br />
an array itself, which contains 'log' and 'args', i.e.<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name} #${token_number}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
Special handling of arguments:<br />
* ${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.<br />
* ${player_name2} - same <br />
<br />
<br />
<br />
'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''<br />
<br />
Same as above, except that the notification is sent to one player only.<br />
<br />
This method must be used each time some private information must be transmitted to a player.<br />
<br />
Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. If you want a second player name in the log, name the variable ${player_name2}, etc.<br />
<br />
== About random and randomness ==<br />
<br />
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.<br />
<br />
Here's are a list of techniques you should use in these situations, from the best to the worst.<br />
<br />
=== Dice and bga_rand ===<br />
<br />
'''bga_rand( min, max )''' <br />
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.<br />
<br />
This is the preferred function you should use, because we are updating it when a better method is introduced.<br />
<br />
As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.<br />
<br />
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).<br />
<br />
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".<br />
<br />
=== shuffle and cards shuffling ===<br />
<br />
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.<br />
<br />
As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even it is 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").<br />
<br />
=== Other methods ===<br />
<br />
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.<br />
<br />
== Game statistics ==<br />
<br />
There are 2 types of statistics:<br />
* a "player" statistic is a statistic associated to a player<br />
* a "table" statistic is a statistic not associated to a player (global statistic for this game).<br />
<br />
See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.<br />
<br />
<br />
'''initStat( $table_or_player, $name, $value, $player_id = null )'''<br />
<br />
Create a statistic entry with a default value.<br />
<br />
This method must be called for each statistic of your game, in your setupNewGame method.<br />
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.<br />
<br />
<br />
'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.<br />
<br />
'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.<br />
<br />
'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.<br />
<br />
<br />
'''setStat( $value, $name, $player_id = null )'''<br />
<br />
Set a statistic $name to $value.<br />
<br />
If "$player_id" is not specified, setStat consider it is a TABLE statistic.<br />
<br />
If "$player_id" is specified, setStat consider it is a PLAYER statistic.<br />
<br />
<br />
'''incStat( $delta, $name, $player_id = null )'''<br />
<br />
Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.<br />
<br />
<br />
'''getStat( $name, $player_id = null )'''<br />
<br />
Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Manage player scores and Tie breaker ==<br />
<br />
=== Normal scoring ===<br />
<br />
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...<br />
<br />
During the game, you update player's score directly by updating "player_score" field of "player" table in database.<br />
<br />
Examples:<br />
<pre><br />
<br />
// +2 points to active player<br />
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
// Set score of active player to 5<br />
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
</pre><br />
<br />
Note: don't forget to notify the client side in order the score control can be updated accordingly.<br />
<br />
=== Tie breaker ===<br />
<br />
Tie breaker is used when two players get the same score at the end of a game.<br />
<br />
Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.<br />
<br />
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.<br />
<br />
When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:<br />
<br />
<pre><br />
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),<br />
</pre><br />
<br />
This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.<br />
<br />
=== Co-operative game ===<br />
<br />
To make everyone win/lose together in a full-coop game:<br />
<br />
Add the following in gameinfos.inc.php :<br />
'is_coop' => 1, // full cooperative<br />
<br />
Assign a score of zero to everyone if it's a loss.<br />
Assign the same score > 0 to everyone if it's a win.<br />
<br />
=== Semi-coop ===<br />
<br />
If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.<br />
<br />
=== Only "winners" and "losers" ===<br />
<br />
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...).<br />
<br />
Examples:<br />
* Coup<br />
* Not Alone<br />
* Werewolves<br />
* Quantum<br />
<br />
In this case:<br />
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.<br />
* Add the following lines to gameinfos.inc.php:<br />
<br />
<pre><br />
// 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 <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => true,<br />
</pre><br />
<br />
Werewolves and Coup are implemented like this, as you can see here:<br />
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults<br />
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults<br />
<br />
Adding this has the following effects:<br />
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".<br />
* 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").<br />
* 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.<br />
<br />
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).<br />
<br />
=== Solo ===<br />
<br />
If game supports solo variant, a negative or zero score means defeat, a positive score means victory.<br />
<br />
=== Player elimination ===<br />
<br />
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.<br />
<br />
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").<br />
<br />
Usage:<br />
<br />
* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).<br />
* In your PHP code:<br />
self::eliminatePlayer( <player_to_eliminate_id> );<br />
* the player is informed in a dialog box that he no longer have to played and can start another game if he/she wants too (whith 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.<br />
* 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.<br />
<br />
=== Scoring Helper functions ===<br />
<br />
These functions should have been API but they are not, just add them to your php game and use for every game.<br />
<br />
// get score<br />
function dbGetScore($player_id) {<br />
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");<br />
}<br />
<br />
// set score<br />
function dbSetScore($player_id, $count) {<br />
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");<br />
}<br />
<br />
// set aux score (tie breaker)<br />
function dbSetAuxScore($player_id, $score) {<br />
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");<br />
}<br />
<br />
// increment score (can be negative too)<br />
function dbIncScore($player_id, $inc) {<br />
$count = $this->dbGetScore($player_id);<br />
if ($inc != 0) {<br />
$count += $inc;<br />
$this->dbSetScore($player_id, $count);<br />
}<br />
return $count;<br />
}<br />
<br />
== Reflexion time ==<br />
<br />
; function giveExtraTime( $player_id, $specific_time=null )<br />
: Give standard extra time to this player.<br />
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).<br />
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).<br />
<br />
<br />
== Undo moves ==<br />
<br />
Please read our [[BGA Undo policy]] before.<br />
<br />
<br />
'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:<br />
'db_undo_support' => true<br />
<br />
<br />
; function undoSavepoint( )<br />
: Save the whole game situation inside an "Undo save point".<br />
: 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.<br />
: 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 matter if you transition to game state not to user state after), which may affect what you end up saved.<br />
<br />
<br />
; function undoRestorePoint()<br />
: Restore the situation previously saved as an "Undo save point".<br />
: 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).<br />
<br />
function actionUndo() {<br />
self::checkAction('actionUndo');<br />
$this->undoRestorePoint();<br />
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)<br />
}<br />
<br />
== Managing errors and exceptions ==<br />
<br />
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.<br />
<br />
; throw new BgaUserException ( $error_message)<br />
: Base class to notify a user error<br />
: You must throw this exception when a player wants to do something that he is not allowed to do.<br />
: The error message will be shown to the player as a "red message", so it must be translated.<br />
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.<br />
<br />
Example from Gomoku:<br />
<pre><br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
</pre><br />
<br />
<br />
; throw new BgaVisibleSystemException ( $error_message)<br />
: You must throw this exception when you detect something that is not supposed to happened in your code.<br />
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.<br />
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.<br />
<br />
; throw new BgaSystemException ( $error_message)<br />
: 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.<br />
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.<br />
<br />
== Zombie mode ==<br />
<br />
When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.<br />
<br />
While developing your zombie mode, keep in mind that:<br />
* Do not refer to the rules, because this situation is not planned by the rules.<br />
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?<br />
* The idea is NOT to develop an artificial intelligence for the game.<br />
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.<br />
<br />
Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.<br />
<br />
Each time a zombie player must play, your "zombieTurn" method is called.<br />
<br />
Parameters:<br />
* $state: the name of the current game state.<br />
* $active_player: the id of the active player.<br />
<br />
Most of the time, your zombieTurn method looks like this:<br />
<br />
<pre><br />
function zombieTurn( $state, $active_player )<br />
{<br />
$statename = $state['name'];<br />
<br />
if( $statename == 'myFirstGameState'<br />
|| $statename == 'my2ndGameState'<br />
|| $statename == 'my3rdGameState'<br />
....<br />
)<br />
{<br />
$this->gamestate->nextState( "zombiePass" );<br />
}<br />
else<br />
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );<br />
}<br />
</pre><br />
<br />
Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.<br />
<br />
'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.<br />
<br />
== Player color preferences ==<br />
<br />
<br />
BGA players (Club members) may now 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.<br />
<br />
Making your game compatible with colors preferences is very easy and requires only 1 line of PHP and 1 configuration change :<br />
<br />
On your gameinfos.inc.php file, add the following lines :<br />
<br />
// Favorite colors support : if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)<br />
// 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.<br />
'favorite_colors_support' => true,<br />
<br />
Then, on your main <your_game>.game.php file, find the "reloadPlayersBasicInfos" call in your "setupNewGame" method and replace :<br />
<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
self::reloadPlayersBasicInfos();<br />
<br />
By :<br />
<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
self::reattributeColorsBasedOnPreferences( $players, array( /* LIST HERE THE AVAILABLE COLORS OF YOUR GAME INSTEAD OF THESE ONES */"ff0000", "008000", "0000ff", "ffa500", "773300" ) );<br />
self::reloadPlayersBasicInfos();<br />
<br />
<br />
The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.<br />
<br />
Note that you must update the colors to indicate the colors available for your game.<br />
<br />
2 important remarks :<br />
* for some games (ex : Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (ex : Starting the game). Color preference mechanism must NOT be used in such a case.<br />
* 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.<br />
<br />
Colours currently listed as a choice in preferences:<br />
<br />
* #ff0000 Red<br />
* #008000 Green<br />
* #0000ff Blue<br />
* #ffa500 Yellow<br />
* #000000 Black<br />
* #ffffff White<br />
* #e94190 Pink<br />
* #982fff Purple<br />
* #72c3b1 Cyan<br />
* #f07f16 Orange<br />
* #bdd002 Khaki green<br />
* #7b7b7b Gray<br />
<br />
== Legacy games API ==<br />
<br />
For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.<br />
<br />
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:<br />
* keeping a player preference/settings (=> player preferences and game options should be used instead)<br />
* 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.<br />
<br />
You should use it for:<br />
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.<br />
* "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.<br />
<br />
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:<br />
<br />
try <br />
{<br />
$this->storeLegacyTeamData( 'my_variable', $my_data );<br />
}<br />
catch( feException $e )<br />
{<br />
if( $e->getCode() == FEX_legacy_size_exceeded )<br />
{<br />
// Do something here to free some space in Legacy data (ex: by removing some variables)<br />
}<br />
else<br />
throw $e;<br />
}<br />
<br />
The keys may only contain letters and numbers, underscore seems not to be allowed.<br />
<br />
; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )<br />
: Store some data associated with $key for the given user / current game<br />
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used<br />
: in a future table with the same game.<br />
: 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. <br />
: TTL is a time-to-live: the maximum, and default, is 365 days.<br />
: 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)<br />
<br />
; function retrieveLegacyData( $player_id, $key )<br />
: Get data associated with $key for the current game<br />
: This data is common to ALL tables from the same game for this player, and persist from one table to another.<br />
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible<br />
: Note: you can use '%' in $key to retrieve all keys matching the given patterns<br />
<br />
; function removeLegacyData( $player_id, $key )<br />
: Remove some legacy data with the given key<br />
: (useful to free some data to avoid going over 64k)<br />
<br />
<br />
<br />
; function storeLegacyTeamData( $key, $data, $ttl = 365 )<br />
: Same as storeLegacyData, except that it stores some data for the whole team within the current table<br />
: 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.<br />
: This is useful for games which are intended to be played several time by the same team.<br />
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens<br />
<br />
; function retrieveLegacyTeamData($key)<br />
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
; function removeLegacyTeamData()<br />
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
== Language dependent games API ==<br />
<br />
This API is used for games that are heavily language dependent. Two most common use cases are:<br />
* 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...)<br />
* 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...)<br />
<br />
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 he speaks.<br />
<br />
There is a new property language_dependency in gameinfos.inc.php which can be set like this:<br />
'language_dependecy' => false, //or if the property is missing, the game is not language dependent<br />
'language_dependecy' => true, //all players at the table must speak the same language<br />
'language_dependecy' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages<br />
<br />
In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.<br />
; function getGameLanguage()<br />
: Returns an index of the selected language as defined in gameinfos.inc.php.<br />
<br />
Languages currently available on BGA are:<br />
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic<br />
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian<br />
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali<br />
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian<br />
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan<br />
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech<br />
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish<br />
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German<br />
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek<br />
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English<br />
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish<br />
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian <br />
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish<br />
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French<br />
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew <br />
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi<br />
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian<br />
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian<br />
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian<br />
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian<br />
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian<br />
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese<br />
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese <br />
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean<br />
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian<br />
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian<br />
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch<br />
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian<br />
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan<br />
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish<br />
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese<br />
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian<br />
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian<br />
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak<br />
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian <br />
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian <br />
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish<br />
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish <br />
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian<br />
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)<br />
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)<br />
<br />
== Debugging and Tracing ==<br />
<br />
To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.<br />
<br />
self::debug("Ahh!");<br />
self::dump('my_var',$my_var);<br />
<br />
See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Gamehelprage&diff=6111Gamehelprage2020-11-09T21:45:16Z<p>Volker78: </p>
<hr />
<div>== Rage ==<br />
<br />
Rage is a bidding trick taking game from Amigo games.<br />
<br />
== Goal ==<br />
<br />
The game ends after 10 rounds, highest score wins; most correct bids breaks ties<br />
<br />
== Cards in play ==<br />
<br />
There are 110 cards:<br />
* 96: There are six (6) suits (Yellow Orange Red Purple Green & Blue) each with cards numbering 0-15<br />
* 14: There are 5 (gray) action cards<br />
** 2 (+5) - player taking the trick gets +5<br />
** 4 Change Trump (❗) - randomly changes trump color<br />
** 2 (-5) - player taking the trick gets -5<br />
** 4 No Trump (🚫) - no trump this trick, random trump chosen for the remainder of tricks<br />
** 2 Joker (Jester hat) - makes this card the highest number of whatever color the player wants (incl. trump)<br />
<br />
== Rules summary ==<br />
<br />
Each round starts with each playing bidding for how many tricks they will win (total may (far) outnumber available trick count)<br />
<br />
Each trick starts with a player leading a color, each other player follows suit, or, if they cannot, plays Action or any other color<br />
Highest card following suit or highest trump card played wins the trick.<br />
Player that won the last trick leads the next trick.<br />
<br />
At the end of the round, scoring is as follows:<br />
<br />
* +1 for each trick you won<br />
* +/-5 for each Bonus you took<br />
* -5 for missing your bid number<br />
* +10 for bidding exactly the number of tricks correctly</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Gamehelprage&diff=6092Gamehelprage2020-11-07T21:20:54Z<p>Volker78: </p>
<hr />
<div>== Rage ==<br />
<br />
Rage is a bidding trick taking game from Amigo games.<br />
<br />
== Goal ==<br />
<br />
The game ends after 10 rounds, highest score wins; most correct bids breaks ties<br />
<br />
== Cards in play ==<br />
<br />
There are 110 cards:<br />
* 96: There are six (6) suits (Yellow Orange Red Purple Green & Blue) each with cards numbering 0-15<br />
* 14: There are 5 (gray) action cards<br />
** 2 (+5) - player tacking the trick gets +5<br />
** 4 Change Trump (❗) - randomly changes trump color<br />
** 2 (-5) - player tacking the trick gets -5<br />
** 4 No Trump (🚫) - no trump this trick, random trump chosen for the remainder of tricks<br />
** 2 Joker (Jester hat) - makes this card the highest number of whatever color the player wants (incl. trump)<br />
<br />
== Rules summary ==<br />
<br />
Each round starts with each playing bidding for how many tricks they will win (total may (far) outnumber available trick count)<br />
<br />
Each trick starts with a player leading a color, each other player follows suit, or, if they cannot, plays Action or any other color<br />
Highest card following suit or highest trump card played wins the trick.<br />
Player that won the last trick leads the next trick.<br />
<br />
At the end of the round, scoring is as follows:<br />
<br />
* +1 for each trick you won<br />
* +/-5 for each Bonus or Mad Rage you took<br />
* -5 for missing your bid number<br />
* +10 for bidding exactly the number of tricks correctly (+5 if you bid 0)</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Gamehelprage&diff=6091Gamehelprage2020-11-07T21:19:46Z<p>Volker78: </p>
<hr />
<div>== Rage ==<br />
<br />
Rage is a bidding trick taking game from Amigo games.<br />
<br />
== Goal ==<br />
<br />
The game ends after 10 rounds, highest score wins; most correct bids breaks ties<br />
<br />
== Cards in play ==<br />
<br />
There are 110 cards:<br />
* 96: There are six (6) suits (Yellow Orange Red Purple Green & Blue) each with cards numbering 0-15<br />
* 14: There are 5 (gray) action cards<br />
** 2 Bonus Rage (+5) - player tacking the trick gets +5<br />
** 4 Change Trump (❗) - randomly changes trump color<br />
** 2 Mad Rage (-5) - player tacking the trick gets -5<br />
** 4 Out Rage (🚫) - no trump this trick, random trump chosen for the remainder of tricks<br />
** 2 Wild Rage (Jester hat) - makes this card the highest number of whatever color the player wants (incl. trump)<br />
<br />
== Rules summary ==<br />
<br />
Each round starts with each playing bidding for how many tricks they will win (total may (far) outnumber available trick count)<br />
<br />
Each trick starts with a player leading a color, each other player follows suit, or, if they cannot, plays Action or any other color<br />
Highest card following suit or highest trump card played wins the trick.<br />
Player that won the last trick leads the next trick.<br />
<br />
At the end of the round, scoring is as follows:<br />
<br />
* +1 for each trick you won<br />
* +/-5 for each Bonus or Mad Rage you took<br />
* -5 for missing your bid number<br />
* +10 for bidding exactly the number of tricks correctly (+5 if you bid 0)</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Gamehelphaiclue&diff=5869Gamehelphaiclue2020-10-14T21:18:21Z<p>Volker78: Created page with "== Setup == '''1. Put down the cards and tokens.''' Shuffle the cards and place the deck face down in the center of the table. Pour out the scoring tokens next to the cards...."</p>
<hr />
<div>== Setup ==<br />
'''1. Put down the cards and tokens.''' Shuffle the<br />
cards and place the deck face down in the center<br />
of the table. Pour out the scoring tokens next to<br />
the cards.<br />
<br />
'''2. Make four stacks of word tiles.''' On one side<br />
of the table, line up four cards, one of each color.<br />
Next to each card, make a stack of random word<br />
tiles. All the tiles should be white-side up. Each<br />
stack should have the following number of tiles:<br />
2 players (cooperative): 2 tiles per stack<br />
3-5 players: 3 tiles per stack<br />
6-8 players: 2 tiles per stack<br />
9-12 players: 1 tile per stack<br />
<br />
'''3. Distribute word tiles.''' Each player draws<br />
15 random word tiles from the box and lays<br />
them out in front of them, white-side up.<br />
<br />
'''4. Distribute guessing tiles.''' Each player takes<br />
four guessing tiles, one of each color.<br />
<br />
== Each Round ==<br />
'''1. Draw a card.''' Each player draws a card from<br />
the deck, privately looks at it, and then puts<br />
it face down in front of them. The card shows<br />
which of the four target words (the words on top<br />
of the stacks) belongs to the player.<br />
<br />
'''2. Make a clue.''' Simultaneously, each player<br />
uses their word tiles to make a clue about their<br />
target word. Clues must contain at least two<br />
word tiles. When you finish your clue, rotate it<br />
so the other players can easily read it, and then<br />
flip over the extra tiles that you did not use in<br />
your clue.<br />
<br />
'''3. Read and guess.''' When everyone has<br />
finished making their clues, the youngest player<br />
reads out loud the clue of the player to their<br />
left. Each player then secretly guesses which of<br />
the four target words is suggested by the clue<br />
by placing a guessing tile face down near the<br />
center of the table. The author of the clue does<br />
not guess.<br />
<br />
'''4. Score.''' When everyone is ready, each player<br />
reveals their guess, and the author reveals their<br />
card. Each player who guessed correctly takes<br />
a 1-point token from the center. The author of<br />
the clue takes one point for each correct guess.<br />
After scoring, the author discards their card.<br />
In a two-player game, you keep score as a<br />
team. The team earns one point each time a<br />
player guesses correctly.<br />
<br />
'''5. Repeat.''' Going clockwise, each player reads<br />
the clue of the player to their left, and the<br />
guessing and scoring process repeats.<br />
<br />
== Between Rounds ==<br />
'''1. After a white round, flip.''' After playing a<br />
round with the white side of the word tiles, flip<br />
over the four tiles on top of the stacks so that<br />
they are black-side up. Each player then flips over<br />
the tiles in their clue, so that all word tiles in play<br />
are black-side up, and a new round begins.<br />
<br />
'''2. After a black round, discard, flip, and pass.''' <br />
After playing a round with the black side<br />
of the word tiles, discard the tiles on top of the<br />
stacks to reveal four new target words. Each<br />
player then flips over the tiles in their clue so<br />
that all word tiles in play are white-side up.<br />
Finally, each player passes their 15 word tiles to<br />
the player to their left, and a new round begins.<br />
In a two-player game, the players swap word<br />
tiles instead of passing them to the left.<br />
<br />
'''3. When the stacks are empty, the game is over.''' <br />
When all of the word tiles in the stacks<br />
are discarded, the player with the most points<br />
wins. If there is a tie, all of the tied players win<br />
together.<br />
In a two-player game, the team must score six<br />
points to win. Eight points is a perfect score.</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_yourgamename.game.php&diff=5365Main game logic: yourgamename.game.php2020-08-25T12:22:16Z<p>Volker78: </p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
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.<br />
<br />
== File Structure ==<br />
<br />
The details of how the file is structured are described directly with comments in the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* EmptyGame (constructor): where you define global variables.<br />
* setupNewGame: initial setup of the game.<br />
* getAllDatas: where you retrieve all game data during a complete reload of the game.<br />
* getGameProgression: where you compute the game progression indicator.<br />
* Utility functions: your utility functions.<br />
* Player actions: the entry points for players actions. <br />
* 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]).<br />
* 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]).<br />
* zombieTurn: what to do it's the turn of a zombie player.<br />
<br />
== Accessing player information ==<br />
<br />
'''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!<br />
<br />
<br />
; getPlayersNumber()<br />
: Returns the number of players playing at the table<br />
: Note: doesn't work in setupNewGame (use count($players) instead).<br />
<br />
; getActivePlayerId()<br />
: Get the "active_player", whatever what is the current state type.<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getActivePlayerName()<br />
: Get the "active_player" name<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; loadPlayersBasicInfos()<br />
: Get an associative array with generic data about players (ie: not game specific data).<br />
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.<br />
: The content of each value is:<br />
: * player_name - the name of the player<br />
: * player_color (ex: ff0000) - the color code of the player<br />
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3<br />
<br />
; getCurrentPlayerId()<br />
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).<br />
: '''Be careful''': This is not necessarily the active player!<br />
: In general, you shouldn't use this method, unless you are in "multiplayer" state.<br />
: '''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).<br />
<br />
; getCurrentPlayerName()<br />
: Get the "current_player" name<br />
: Be careful using this method (see above).<br />
<br />
; getCurrentPlayerColor()<br />
: Get the "current_player" color<br />
: Be careful using this method (see above).<br />
<br />
; isCurrentPlayerZombie()<br />
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.<br />
<br />
== Accessing the database ==<br />
<br />
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.<br />
<br />
'''IMPORTANT'''<br />
<br />
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. 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.<br />
<br />
; DbQuery( $sql )<br />
: This is the generic method to access the database.<br />
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database.<br />
: You should use it for UPDATE/DELETE/REPLACE/INSERT queries. For SELECT queries, the specialized methods below are much better.<br />
<br />
; getUniqueValueFromDB( $sql )<br />
: Returns a unique value from DB or null if no value is found.<br />
: $sql must be a SELECT query.<br />
: Raise an exception if more than 1 row is returned.<br />
<br />
; getCollectionFromDB( $sql, $bSingleValue=false )<br />
: Returns an associative array of rows for a sql SELECT query.<br />
: The key of the resulting associative array is the first field specified in the SELECT query.<br />
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.<br />
: First column must be a primary or alternate key.<br />
: The resulting collection can be empty.<br />
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"<br />
<br />
Example 1:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
1234 => 'myuser0',<br />
1235 => 'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getNonEmptyCollectionFromDB( $sql )<br />
: Idem than previous one, but raise an exception if the collection is empty<br />
<br />
; getObjectFromDB( $sql )<br />
: Returns one row for the sql SELECT query as an associative array or null if there is no result<br />
: Raise an exception if the query return more than one row<br />
<br />
Example:<br />
<pre><br />
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );<br />
<br />
Result:<br />
array(<br />
'id'=>1234, 'name'=>'myuser0', 'score'=>1 <br />
)<br />
</pre><br />
<br />
; getNonEmptyObjectFromDB( $sql )<br />
: Idem than previous one, but raise an exception if no row is found<br />
<br />
; getObjectListFromDB( $sql, $bUniqueValue=false )<br />
: Return an array of rows for a sql SELECT query.<br />
: the result if the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).<br />
: The result can be empty.<br />
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.<br />
<br />
Example 1:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
'myuser0',<br />
'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )<br />
: Return an associative array of associative array, from a SQL SELECT query.<br />
: First array level correspond to first column specified in SQL query.<br />
: Second array level correspond to second column specified in SQL query.<br />
: If bSingleValue = true, keep only third column on result<br />
<br />
<br />
; DbGetLastId()<br />
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).<br />
<br />
; DbAffectedRow()<br />
: Return the number of row affected by the last operation<br />
<br />
; escapeStringForDB( $string )<br />
: You must use this function on every string type data in your database that contains unsafe data.<br />
: (unsafe = can be modified by a player).<br />
: This method makes sure that no SQL injection will be done through the string used.<br />
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,<br />
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.<br />
<br />
<pre><br />
<br />
<br />
</pre><br />
<br />
Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.<br />
<br />
== Use globals ==<br />
<br />
Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.<br />
<br />
You can do this with the BGA framework "global." Your value will be stored in the "global" table in the database, and you can access it with simple methods.<br />
<br />
'''initGameStateLabels'''<br />
<br />
This method should be located at the beginning of ''yourgamename.php.'' This is where you define the globals used in your game logic, by assigning them IDs.<br />
<br />
You can define up to 79 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11<br />
) );<br />
</pre><br />
<br />
'''setGameStateInitialValue( $value_label, $value_value )'''<br />
<br />
Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method.<br />
<br />
'''getGameStateValue( $value_label )'''<br />
<br />
Retrieve the current value of a global.<br />
<br />
'''setGameStateValue( $value_label, $value_value )'''<br />
<br />
Set the current value of a global.<br />
<br />
'''incGameStateValue( $value_label, $increment )'''<br />
<br />
Increment the current value of a global. If increment is negative, decrement the value of the global.<br />
<br />
Return the final value of the global.<br />
<br />
== Game states and active players ==<br />
<br />
<br />
=== Activate player handling ===<br />
<br />
; $this->activeNextPlayer()<br />
: Make the next player active in the natural player order.<br />
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->activePrevPlayer()<br />
: Make the previous player active (in the natural player order).<br />
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->gamestate->changeActivePlayer( $player_id )<br />
: You can call this method to make any player active.<br />
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->getActivePlayerId()<br />
: Return the "active_player" id<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
=== Multiactivate player handling ===<br />
<br />
; $this->gamestate->setAllPlayersMultiactive()<br />
: All playing players are made active. Update notification is sent to all players (triggers onUpdateActionButtons).<br />
: Usually, you use this method at the beginning (ex: "st" action method) of a multiplayer game state when all players have to do some action. Do not use method if you going to do some more chages in active player list, i.e. if you want to take away multi-active right after, use setPlayersMultiactive instead.<br />
<br />
Example of usage:<br />
<pre><br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
</pre><br />
And this is declaration of state:<br />
<pre><br />
2 => array(<br />
"name" => "playerTurnPlace",<br />
"description" => clienttranslate('Other player must place ships'),<br />
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),<br />
"type" => "multipleactiveplayer",<br />
'action' => 'st_MultiPlayerInit',<br />
'args' => 'arg_playerTurnPlace',<br />
"possibleactions" => array( "actionBla" ),<br />
"transitions" => array( "next" => 4, "last" => 99)<br />
),<br />
</pre><br />
<br />
; $this->gamestate->setAllPlayersNonMultiactive( $next_state )<br />
: All playing players are made inactive. Transition to next state<br />
<br />
; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )<br />
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players who's state changed.<br />
: "players" is the array of player id that should be made active.<br />
: If "exclusive" 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<br />
<br />
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )<br />
: During a multiactive game state, make the specified player inactive.<br />
: 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.<br />
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
Example of usage (see state declaration of playerTurnPlace above):<br />
<pre><br />
function actionBla($args) {<br />
self::checkAction('actionBla');<br />
// handle the action using $this->getCurrentPlayerId()<br />
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');<br />
}<br />
</pre><br />
; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )<br />
: 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.<br />
Example: you have player teams and you want to activate all players in one team<br />
<pre><br />
$sql = "UPDATE player SET player_is_multiactive='0'";<br />
self::DbQuery( $sql );<br />
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";<br />
self::DbQuery( $sql );<br />
<br />
$this->gamestate->updateMultiactiveOrNextState( 'error' );<br />
</pre><br />
<br />
; $this->gamestate->getActivePlayerList()<br />
: With this method you can retrieve the list of the active player at any time.<br />
: During a "game" type gamestate, it will return a void array.<br />
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).<br />
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.<br />
: Note: you should only use this method in the latter case.<br />
<br />
=== States functions ===<br />
; $this->gamestate->nextState( $transition )<br />
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.<br />
<br />
; $this->checkAction( $actionName, $bThrowException=true )<br />
: Check if an action is valid for the current game state, and optionally, throw an exception if it isn't.<br />
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).<br />
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game.<br />
: 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.<br />
<br />
; $this->gamestate->checkPossibleAction( $action )<br />
: (rarely used)<br />
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.<br />
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.<br />
: 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.<br />
<br />
; $this->gamestate->state()<br />
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.<br />
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}<br />
<br />
== Players turn order ==<br />
<br />
'''getNextPlayerTable()'''<br />
<br />
Return an associative array which associate each player with the next player around the table.<br />
<br />
In addition, key 0 is associated to the first player to play.<br />
<br />
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:<br />
<pre><br />
array( <br />
1 => 2, <br />
2 => 3, <br />
3 => 1, <br />
0 => 1 <br />
);<br />
</pre><br />
<br />
'''getPrevPlayerTable()'''<br />
<br />
Same as above, but the associative array associate the previous player around the table. Here seems also the "0" missing.<br />
<br />
'''getPlayerAfter( $player_id )'''<br />
<br />
Get player playing after given player in natural playing order.<br />
<br />
'''getPlayerBefore( $player_id )'''<br />
<br />
Get player playing before given player in natural playing order.<br />
<br />
Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database<br />
and have custom function to access it.<br />
<br />
== Notify players ==<br />
<br />
To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.<br />
<br />
'''IMPORTANT'''<br />
<br />
Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.<br />
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.<br />
<br />
'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''<br />
<br />
Send a notification to all players of the game.<br />
<br />
* notification_type:<br />
A string that defines the type of your notification.<br />
<br />
Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).<br />
<br />
* notification_log:<br />
A string that defines what is to be displayed in the game log.<br />
<br />
You can use an empty string here (""). In this case, nothing is displayed in the game log.<br />
<br />
If you define a real string here, you should use "clienttranslate" method to make sure it can be translate.<br />
<br />
You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below). <br />
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.<br />
<br />
<br />
<br />
* notification_args:<br />
The arguments of your notifications, as an associative array.<br />
<br />
This array will be transmitted to the game interface logic, in order the game interface can be updated.<br />
<br />
Complete notifyAllPlayers example (from "Reversi"):<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
</pre><br />
<br />
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.<br />
<br />
'''Important''': NO private data must be sent with this method, as a cheater could see it even it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.<br />
<br />
'''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.<br />
<br />
Note: you CAN use some HTML inside your notification log, however it not recommended for many reasons:<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games reply and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game reply, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.<br />
<br />
If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].<br />
<br />
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<br />
an array itself, which contains 'log' and 'args', i.e.<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name} #${token_number}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
<br />
<br />
'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''<br />
<br />
Same as above, except that the notification is sent to one player only.<br />
<br />
This method must be used each time some private information must be transmitted to a player.<br />
<br />
Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log<br />
<br />
== About random and randomness ==<br />
<br />
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.<br />
<br />
Here's are a list of techniques you should use in these situations, from the best to the worst.<br />
<br />
=== Dices and bga_rand ===<br />
<br />
'''bga_rand( min, max )''' <br />
This is a BGA framework function that provides you a random number between "min" and "max" (included), using the best available random method available on the system.<br />
<br />
This is the preferred function you should use, because we are updating it when a better method is introduced.<br />
<br />
At now, bga_rand is based on the PHP function "random_int", which ensure a cryptographic level of randomness.<br />
<br />
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).<br />
<br />
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".<br />
<br />
=== shuffle and cards shuffling ===<br />
<br />
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 ensure you that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.<br />
<br />
At now, the Deck component shuffle method is based on PHP "shuffle" method, which has a quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as their are based on PHP "shuffle" function (or similar, like "array_rand").<br />
<br />
=== Other methods ===<br />
<br />
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.<br />
<br />
== Game statistics ==<br />
<br />
There are 2 types of statistics:<br />
* a "player" statistic is a statistic associated to a player<br />
* a "table" statistics is a statistic not associated to a player (global statistic for this game).<br />
<br />
See [[Game statistics: stats.inc.php]] to see how you defines statistics for your game.<br />
<br />
<br />
'''initStat( $table_or_player, $name, $value, $player_id = null )'''<br />
<br />
Create a statistic entry with a default value.<br />
This method must be called for each statistics of your game, in your setupNewGame method.<br />
<br />
'$table_or_player' must be set to "table" if this is a table statistics, or "player" if this is a player statistics.<br />
<br />
'$name' is the name of your statistics, as it has been defined in your stats.inc.php file.<br />
<br />
'$value' is the initial value of the statistics. If this is a player statistics and if the player is not specified by "$player_id" argument, the value is set for ALL players.<br />
<br />
<br />
'''setStat( $value, $name, $player_id = null )'''<br />
<br />
Set a statistic $name to $value.<br />
<br />
If "$player_id" is not specified, setStat consider it is a TABLE statistic.<br />
<br />
If "$player_id" is specified, setStat consider it is a PLAYER statistic.<br />
<br />
<br />
'''incStat( $delta, $name, $player_id = null )'''<br />
<br />
Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.<br />
<br />
<br />
'''getStat( $name, $player_id = null )'''<br />
<br />
Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Manage player scores and Tie breaker ==<br />
<br />
=== Normal scoring ===<br />
<br />
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...<br />
<br />
During the game, you update player's score directly by updating "player_score" field of "player" table in database.<br />
<br />
Examples:<br />
<pre><br />
<br />
// +2 points to active player<br />
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
// Set score of active player to 5<br />
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
</pre><br />
<br />
Note: don't forget to notify the client side in order the score control can be updated accordingly.<br />
<br />
=== Tie breaker ===<br />
<br />
Tie breaker is used when two players get the same score at the end of a game.<br />
<br />
Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.<br />
<br />
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.<br />
<br />
When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:<br />
<br />
<pre><br />
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),<br />
</pre><br />
<br />
This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.<br />
<br />
=== Co-operative game ===<br />
<br />
To make everyone lose in full-coop game:<br />
<br />
Add the following in gameinfos.inc.php :<br />
'is_coop' => 1, // full cooperative<br />
<br />
And score zero to everyone.<br />
<br />
=== Semi-coop ===<br />
<br />
If the game is not full-coop, then everyone lose = everyone is tie. I.e. set score to 0 to everybody.<br />
<br />
=== Only "winners" and "losers" ===<br />
<br />
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...).<br />
<br />
Examples:<br />
* Coup<br />
* Not Alone<br />
* Werewolves<br />
* Quantum<br />
<br />
In this case:<br />
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.<br />
* Add the following lines to gameinfos.php:<br />
<br />
<pre><br />
// 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 <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => true,<br />
</pre><br />
<br />
Werewolves and Coup are implemented like this, as you can see here:<br />
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults<br />
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults<br />
<br />
Adding this has the following effects:<br />
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".<br />
* 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").<br />
* 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.<br />
<br />
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).<br />
<br />
=== Solo ===<br />
<br />
If game supports solo variant, a negative score means defeat, a positive score means victory.<br />
<br />
=== Player elimination ===<br />
<br />
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.<br />
<br />
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").<br />
<br />
Usage:<br />
<br />
* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).<br />
* In your PHP code:<br />
self::eliminatePlayer( <player_to_eliminate_id> );<br />
* the player is informed in a dialog box that he no longer have to played and can start another game if he/she wants too (whith 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.<br />
* 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.<br />
<br />
=== Scoring Helper functions ===<br />
<br />
// get score<br />
function dbGetScore($player_id) {<br />
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");<br />
}<br />
<br />
// set score<br />
function dbSetScore($player_id, $count) {<br />
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");<br />
}<br />
<br />
// set aux score (tie breaker)<br />
function dbSetAuxScore($player_id, $score) {<br />
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");<br />
}<br />
<br />
// increment score (can be negative too)<br />
function dbIncScore($player_id, $inc) {<br />
$count = $this->dbGetScore($player_id);<br />
if ($inc != 0) {<br />
$count += $inc;<br />
$this->dbSetScore($player_id, $count);<br />
}<br />
return $count;<br />
}<br />
<br />
== Reflexion time ==<br />
<br />
; function giveExtraTime( $player_id, $specific_time=null )<br />
: Give standard extra time to this player.<br />
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).<br />
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).<br />
<br />
<br />
== Undo moves ==<br />
<br />
Please read our [[BGA Undo policy]] before.<br />
<br />
<br />
'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:<br />
'db_undo_support' => true<br />
<br />
<br />
; function undoSavepoint( )<br />
: Save the whole game situation inside an "Undo save point".<br />
: There is only ONE undo save point available (see BGA Undo policy).<br />
<br />
<br />
; function undoRestorePoint()<br />
: Restore the situation previously saved as an "Undo save point".<br />
: 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).<br />
<br />
== Managing errors and exceptions ==<br />
<br />
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.<br />
<br />
; throw new BgaUserException ( $error_message)<br />
: Base class to notify a user error<br />
: You must throw this exception when a player wants to do something that he is not allowed to do.<br />
: The error message will be shown to the player as a "red message", so it must be translated.<br />
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.<br />
<br />
Example from Gomoku:<br />
<pre><br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
</pre><br />
<br />
<br />
; throw new BgaVisibleSystemException ( $error_message)<br />
: You must throw this exception when you detect something that is not supposed to happened in your code.<br />
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.<br />
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.<br />
<br />
; throw new BgaSystemException ( $error_message)<br />
: 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.<br />
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.<br />
<br />
== Zombie mode ==<br />
<br />
When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.<br />
<br />
While developing your zombie mode, keep in mind that:<br />
* Do not refer to the rules, because this situation is not planned by the rules.<br />
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?<br />
* The idea is NOT to develop an artificial intelligence for the game.<br />
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.<br />
<br />
Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.<br />
<br />
Each time a zombie player must play, your "zombieTurn" method is called.<br />
<br />
Parameters:<br />
* $state: the name of the current game state.<br />
* $active_player: the id of the active player.<br />
<br />
Most of the time, your zombieTurn method looks like this:<br />
<br />
<pre><br />
function zombieTurn( $state, $active_player )<br />
{<br />
$statename = $state['name'];<br />
<br />
if( $statename == 'myFirstGameState'<br />
|| $statename == 'my2ndGameState'<br />
|| $statename == 'my3rdGameState'<br />
....<br />
)<br />
{<br />
$this->gamestate->nextState( "zombiePass" );<br />
}<br />
else<br />
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );<br />
}<br />
</pre><br />
<br />
Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.<br />
<br />
'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.<br />
<br />
== Player color preferences ==<br />
<br />
<br />
BGA players (Club members) may now 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.<br />
<br />
Making your game compatible with colors preferences is very easy and requires only 1 line of PHP and 1 configuration change :<br />
<br />
On your gameinfos.inc.php file, add the following lines :<br />
<br />
// Favorite colors support : if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)<br />
// 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.<br />
'favorite_colors_support' => true,<br />
<br />
Then, on your main <your_game>.game.php file, find the "reloadPlayersBasicInfos" call in your "setupNewGame" method and replace :<br />
<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
self::reloadPlayersBasicInfos();<br />
<br />
By :<br />
<br />
$sql .= implode( $values, ',' );<br />
self::DbQuery( $sql );<br />
self::reattributeColorsBasedOnPreferences( $players, array( /* LIST HERE THE AVAILABLE COLORS OF YOUR GAME INSTEAD OF THESE ONES */"ff0000", "008000", "0000ff", "ffa500", "773300" ) );<br />
self::reloadPlayersBasicInfos();<br />
<br />
<br />
The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.<br />
<br />
Note that you must update the colors to indicate the colors available for your game.<br />
<br />
2 important remarks :<br />
* for some games (ex : Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (ex : Starting the game). Color preference mechanism must NOT be used in such a case.<br />
* 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.<br />
<br />
Colours currently listed as a choice in preferences:<br />
<br />
* #ff0000 Red<br />
* #008000 Green<br />
* #0000ff Blue<br />
* #ffa500 Yellow<br />
* #000000 Black<br />
* #ffffff White<br />
* #e94190 Pink<br />
* #982fff Purple<br />
* #72c3b1 Cyan<br />
* #f07f16 Orange<br />
* #bdd002 Khaki green<br />
* #7b7b7b Gray<br />
<br />
== Legacy games API ==<br />
<br />
For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.<br />
<br />
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:<br />
* keeping a player preference/settings (=> player preferences and game options should be used instead)<br />
* 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.<br />
<br />
You should use it for:<br />
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.<br />
* "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.<br />
<br />
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:<br />
<br />
try <br />
{<br />
$this->storeLegacyTeamData( 'my_variable', $my_data );<br />
}<br />
catch( feException $e )<br />
{<br />
if( $e->getCode() == FEX_legacy_size_exceeded )<br />
{<br />
// Do something here to free some space in Legacy data (ex: by removing some variables)<br />
}<br />
else<br />
throw $e;<br />
}<br />
<br />
<br />
; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )<br />
: Store some data associated with $key for the given user / current game<br />
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used<br />
: in a future table with the same game.<br />
: 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. <br />
: TTL is a time-to-live: the maximum, and default, is 365 days.<br />
: 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)<br />
<br />
; function retrieveLegacyData( $player_id, $key )<br />
: Get data associated with $key for the current game<br />
: This data is common to ALL tables from the same game for this player, and persist from one table to another.<br />
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible<br />
: Note: you can use '%' in $key to retrieve all keys matching the given patterns<br />
<br />
; function removeLegacyData( $player_id, $key )<br />
: Remove some legacy data with the given key<br />
: (useful to free some data to avoid going over 64k)<br />
<br />
<br />
<br />
; function storeLegacyTeamData( $data, $ttl = 365 )<br />
: Same as storeLegacyData, except that it stores some data for the whole team within the current table<br />
: 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.<br />
: This is useful for games which are intended to be played several time by the same team.<br />
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens<br />
<br />
; function retrieveLegacyTeamData()<br />
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
; function removeLegacyTeamData()<br />
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
== Debugging and Tracing ==<br />
<br />
To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.<br />
<br />
self::debug("Ahh!");<br />
self::dump('my_var',$my_var);<br />
<br />
See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Practical_debugging&diff=5284Practical debugging2020-08-16T11:15:05Z<p>Volker78: Description was wrong/not working</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This page gives you practical tips to debug your game during development. Don't hesitate to share your difficulties with us so that we can improve this section.<br />
<br />
== Tools ==<br />
<br />
To work on BGA Studio, we recommend that you use [http://www.google.com/chrome Google Chrome] as it's currently the fastest browser for the BGA platform, and it's available for all OSes.<br />
<br />
Another reason to use Chrome is that it embeds all the tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").<br />
<br />
A good practice is to use a second browser to develop the game, in order to verify that your game is working fine on this browser too.<br />
<br />
To debug with Firefox browser, we advise you to use these 2 extensions:<br />
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]<br />
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developer]<br />
<br />
To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...<br />
<br />
== General tip for debugging ==<br />
<br />
In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.<br />
<br />
You can save up to 3 different states.<br />
<br />
== Debugging my game when it cannot start ==<br />
<br />
If your game won't start because of an error, you are probably in one of these situations:<br />
* There is a SQL error in your dbmodel.sql file.<br />
* You have a syntax error in your PHP file.<br />
* Your PHP "setup" - or any method used during the game initial states - generates an exception.<br />
<br />
If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].<br />
More cases of why game can't start are described on the [[Troubleshooting]] page.<br />
<br />
== Debugging my PHP game logic (or my view) ==<br />
<br />
Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:<br />
<br />
* At first, I make sure that I can reproduce the needed game situation with one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.<br />
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be committed to the database.<br />
* Then, I use the '''var_dump''' function to dump PHP variables and check what's wrong, until it works.<br />
<br />
Example:<br />
<pre><br />
<br />
// (...my code to debug)<br />
<br />
var_dump( $my_variable );<br />
die('ok');<br />
<br />
// (...my code to debug)<br />
<br />
</pre><br />
<br />
=== Add traces to your code ===<br />
<br />
You can use the following functions in your game to add server side logging:<br />
<br />
'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
Check [[Studio logs]] for more details on how to access your logs.<br />
<br />
This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.<br />
<br />
Only the error log level will appear in production. This level should be used only for critical problems. <br />
Other levels will show only in the development environment and can be used as you see fit.<br />
<br />
== Debugging my HTML/CSS layout ==<br />
<br />
Example situations<br />
<br />
* Why doesn't my game element show up in the interface?<br />
* Why hasn't my CSS property been applied to this element?<br />
* Why is this game element displayed at this position?<br />
<br />
A useful tip when an element does not show up in the interface is to give it a red background:<br />
<pre><br />
#my_element {<br />
... some CSS definitions ...<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
This way, you know if the element is not visible because of some CSS property or because of something else.<br />
<br />
Another tip: sometimes, changing a CSS property has no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.<br />
<br />
Using Chrome "Elements" tab (the first one), you can:<br />
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.<br />
* Using the "magnifying glass", you can click on any part of your game interface and check its HTML code and associated CSS styles.<br />
* You can even modify directly some CSS properties and see how it looks immediately in the game interface.<br />
<br />
=== Debugging my Javascript game interface logic ===<br />
<br />
Compared to PHP debugging, Javascript debugging can sometimes be painful.<br />
<br />
Here are some tips to make your life easier while developing and debugging Javascript:<br />
<br />
=== Do complex things on the PHP side ===<br />
<br />
The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Do it in PHP, and transfer the results to your client interface using the "args" game state property.<br />
<br />
Note: See the Reversi tutorial for an example.<br />
<br />
=== Add traces in your code ===<br />
<br />
You can use the following:<br />
<br />
'''console.log( variable_to_inspect )'''<br />
<br />
It will give you the object structure of the variable in the Javascript console, without blocking the execution.<br />
<br />
It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.<br />
<br />
'''alert( variable_to_inspect )'''<br />
<br />
It will popup what you wish and pause the execution until you click ok.<br />
<br />
This won't be useful for complex structures; only native types will be plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.<br />
<br />
=== Use Browser Debugger (e.g. Chrome) ===<br />
<br />
Modern browsers also allow you to put breakpoints in your js code. <br />
<br />
This will stop code execution on that line and will launch the JavaScript debugger.<br />
<br />
In Chrome, to add a breakpoint: add a line to your .js file<br />
<br />
<pre>debugger; </pre><br />
<br />
Refresh the page F5, and make sure you have the Developer tools window open, press F12. <br />
When the break-point is hit you can then step through your code and visualise variables, etc.<br />
<br />
== Online format checkers ==<br />
Copy and paste code for a quick code sanity check like the right number of brackets.<br />
<br />
PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]<br />
<br />
JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]<br />
<br />
== Some frequent errors ==<br />
<br />
See [[Troubleshooting]].<br />
<br />
== Get the database matching a bug report ==<br />
<br />
For a way to automate the below steps, see this post: https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167<br />
<br />
---<br />
<br />
When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:<br />
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.<br />
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)<br />
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.<br />
* If the snapshot is correctly retrieved, you see a "Done!" message.<br />
* Go back to the tab with your studio table and click "Load 1".<br />
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.<br />
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).<br />
* Click on the "Go to game database" button<br />
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.<br />
* Tables to update:<br />
** player<br />
** global (value with ID 2 is the active player)<br />
** stats<br />
** tables specific to your schema that use player_ids<br />
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.<br />
* Then you should be able to play with the same state of the game as when the report was created in production.<br />
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).<br />
*<br />
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug() <br />
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1<br />
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.<br />
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window<br />
<br />
<pre><br />
public function LoadDebug()<br />
{<br />
<br />
// These are the id's from the BGAtable I need to debug.<br />
$id0 = '85268563';<br />
$id1 = '85278138'; <br />
<br />
//player<br />
self::DbQuery("UPDATE player SET player_id=2308257 WHERE player_id = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE player SET player_id=2308258 WHERE player_id = '" . $id1 . "'" );<br />
<br />
//global <br />
self::DbQuery("UPDATE global SET global_value=2308257 WHERE global_value = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE global SET global_value=2308258 WHERE global_value = '" . $id1 . "'" );<br />
<br />
//stats<br />
self::DbQuery("UPDATE stats SET stats_player_id=2308257 WHERE stats_player_id = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE stats SET stats_player_id=2308258 WHERE stats_player_id = '" . $id1 . "'" ); <br />
<br />
// 'other' game specific tables. example:<br />
// tables specific to your schema that use player_ids<br />
self::DbQuery("UPDATE card SET card_location_arg=2308257 WHERE card_location_arg = '" . $id0 . "'" );<br />
self::DbQuery("UPDATE card SET card_location_arg=2308258 WHERE card_location_arg = '" . $id1 . "'" );<br />
}<br />
</pre></div>Volker78https://en.doc.boardgamearena.com/index.php?title=Gamehelpturnthetide&diff=5013Gamehelpturnthetide2020-07-18T20:09:50Z<p>Volker78: Undo revision 4990 by Volker78 (talk)</p>
<hr />
<div>= Objective =<br />
Score the most points by playing cards that will keep your tide level low and your life preservers afloat through the rounds.<br />
There are as many rounds as there are players.<br />
The player with the most points at the end of the rounds wins the game.<br />
<br />
<br />
= Gameplay =<br />
Twelve hands make up one complete round. Your number of life preservers is determined by what cards you have in hand. The distribution of life preservers may seem unfair. However, the players with more life preservers have a higher concentration of Weather cards that are more difficult to play.<br />
<br />
Each player chooses one Weather card from her hand. When all players have selected their cards, everyone simultaneously turns their chosen card face up and compares numbers.<br />
<br />
The player who played the highest number Weather card must take the lower Tide Level card from the two face up next to the deck. That Tide Level card is then placed face up in front of him so that all of the other players can see it.<br />
<br />
Next, the player who played the second highest Weather card must take the remaining Tide Level card and do the same.<br />
<br />
When you receive a new Tide Level card, it is placed on top of the old one, if there was one.<br />
<br />
The player who now has the highest Tide Level card showing among all players loses a life preserver. If two players tie for the highest Tide Level, then both must turn over a life preserver.<br />
<br />
All played Weather cards are then discarded and two new Tide Level cards are revealed next to the deck.<br />
<br />
<br />
= Round elimination =<br />
If you loose your last life preserver, you get one last chance to stay in the round. You are only eliminated from the round when you loose once more (that is, when you must turn over another life preserver, but have none left to turn).<br />
<br />
If you are eliminated from the round, your Weather and Tide Level cards are discarded.<br />
<br />
<br />
= End of a round and scoring =<br />
A round ends after each player has played all 12 cards from his hand. Alternatively, the round ends instantly when there are only two players left in the game.<br />
<br />
At the end of the round, you are awarded one point for each remaining life preserver. If you have no life preservers, you get no points (0). If you were eliminated from the round because of a lack of life preservers, you receive one negative point (-1).<br />
<br />
In addition, the player who, at the end of the round, had the lowest Tide Level card showing, receives one additional bonus point. If two players are tied for the lowest Tide Level, then they each receive an additional point. A player with no Tide Level cards in his playing area has the lowest Tide Level.<br />
<br />
<br />
= Starting a new round =<br />
Your initial 12 Weather cards are passed to the player on your left, as well as the corresponding life preservers.<br />
The Tide Level cards are re-shuffle at the beginning of each round.</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Gamehelpturnthetide&diff=4990Gamehelpturnthetide2020-07-14T06:34:41Z<p>Volker78: </p>
<hr />
<div>= Ziel =<br />
Erziele die meisten Punkte, in dem Du Karten ausspielst, die Deine Flut niedrig halten und Deine Rettungsringe durch die Runden erhalten.<br />
Es gibt so viele Runden wie es Spieler gibt.<br />
Der Spieler mit den meisten Punkten am Ende der Runden gewinnt das Spiel.<br />
<br />
<br />
= Spielverlauf =<br />
Zwölf Runden bilden einen kompletten Durchgang. Die Anzahl der Rettungsringe richtet sich danach, welche Karten Du auf der Hand hast. Die Verteilung der Rettungsringe mag ungerecht erscheinen. Die Spieler mit mehr Rettungsringen haben jedoch eine höhere Anzahl von Wetterkarten, die schwieriger zu spielen sind.<br />
<br />
Jeder Spieler wählt eine Wetterkarte aus seinem Blatt aus. Wenn alle Spieler ihre Karten ausgewählt haben, decken alle gleichzeitig ihre gewählte Karte auf und vergleichen die Zahlen.<br />
<br />
Der Spieler, der die Wetterkarte mit der höchsten Zahl gespielt hat, muss die Karte mit dem niedrigeren Flutniveau von den beiden aufgedeckten Karten neben dem Stapel nehmen. Diese Karte wird dann aufgedeckt vor ihm abgelegt, so dass alle anderen Spieler sie sehen können.<br />
<br />
Als nächstes muss der Spieler, der die zweithöchste Wetterkarte ausgespielt hat, die verbleibende Karte mit dem Flutniveau nehmen und dasselbe tun.<br />
<br />
Wenn Du eine neue Flutkarte erhältst, wird sie auf die alte Karte gelegt, falls es eine gab.<br />
<br />
Der Spieler, der nun die höchste der aufgedeckten Flutkarten hat, verliert einen Rettungsring. Wenn zwei Spieler bei Gleichstand die höchste Flutkarte haben, müssen beide Spieler einen Rettungsring umdrehen.<br />
<br />
Alle gespielten Wetterkarten werden dann abgelegt und zwei neue Flutkarten werden neben dem Stapel aufgedeckt.<br />
<br />
<br />
= Ausscheidung aus einer Runde =<br />
Wenn Du Deinen letzten Rettungsring verlierst, bekommst Du eine letzte Chance, in der Runde zu bleiben. Du scheidest erst dann aus der Runde aus, wenn du noch einmal verlierst (d.h. wenn du einen anderen Rettungsring umdrehen musst, aber keinen mehr zum Drehen hast).<br />
<br />
Wenn Du aus der Runde ausscheidest, werden Deine Wetter- und Gezeitenkarten abgelegt.<br />
<br />
<br />
= Ende einer Runde und Wertung =<br />
Eine Runde endet, nachdem jeder Spieler alle 12 Karten aus seiner Hand gespielt hat. Alternativ endet die Runde sofort, wenn nur noch zwei Spieler im Spiel sind.<br />
<br />
Am Ende der Runde erhält man für jeden verbleibenden Rettungsring einen Punkt. Wenn du keine Rettungsringe hast, bekommst du keine Punkte (0). Wenn du wegen fehlender Rettungsringe aus der Runde ausgeschieden bist, bekommst du einen Minuspunkt (-1).<br />
<br />
Darüber hinaus erhält der Spieler, der am Ende der Runde die Karte mit dem niedrigsten Flutniveau ausliegen hat, einen zusätzlichen Bonuspunkt. Wenn zwei Spieler für die niedrigste Flutkarte gleichauf liegen, erhält jeder von ihnen einen zusätzlichen Punkt. Ein Spieler ohne Flutkarte in seinem Spielbereich hat das niedrigste Flutniveau.<br />
<br />
<br />
= Beginn einer neuen Runde =<br />
Deine ersten 12 Wetterkarten sowie die entsprechenden Rettungsringe werden an den Spieler zu deiner Linken weitergegeben.<br />
Die Flutkarten werden zu Beginn jeder Runde neu gemischt.</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Your_game_state_machine:_states.inc.php&diff=4983Your game state machine: states.inc.php2020-07-13T19:33:41Z<p>Volker78: It was not clear, if using private-args in description messages are ok, but it seems so after testing.</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This file describes the state machine of your game (all the game states properties, and the transitions to get from one state to another).<br />
<br />
Important: to understand the game state machine, it's recommended that you read this presentation first:<br />
<br />
[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]<br />
<br />
== Overall structure ==<br />
<br />
The machine states are described by a PHP associative array.<br />
<br />
Example:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
// The initial state. Please do not modify.<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 2 )<br />
),<br />
<br />
// Note: ID=2 => your first state<br />
<br />
2 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a card or pass'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a card or pass'),<br />
"type" => "activeplayer",<br />
"possibleactions" => array( "playCard", "pass" ),<br />
"transitions" => array( "playCard" => 2, "pass" => 2 )<br />
),<br />
</pre><br />
<br />
== Syntax ==<br />
<br />
=== id ===<br />
<br />
The keys determine game state IDs (in the example above: 1 and 2).<br />
<br />
IDs must be positive integers.<br />
<br />
ID=1 is reserved for the first game state and should not be used (and you must not modify it).<br />
<br />
ID=99 is reserved for the last game state (end of the game) (and you must not modify it).<br />
<br />
Note: you may use any ID, even an ID greater than 100. But you cannot use 1 or 99.<br />
<br />
Note²: You must not use the same ID twice.<br />
<br />
Note³: When a game is in prod and you change the ID of a state, all active games (including many turn based) will behave unpredictably.<br />
<br />
=== name ===<br />
<br />
('''Mandatory''')<br />
<br />
The name of a game state is used to identify it in your game logic.<br />
<br />
Several game states can share the same name; however, this is not recommended.<br />
<br />
Warning! Do not put spaces in the name. This could cause unexpected problems in some cases.<br />
<br />
PHP example:<br />
<pre><br />
<br />
// Get current game state<br />
$state = $this->gamestate->state();<br />
if( $state['name'] == 'myGameState' )<br />
{<br />
...<br />
}<br />
<br />
</pre><br />
<br />
JS example:<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
case 'myGameState':<br />
<br />
// Do some stuff at the beginning at this game state<br />
....<br />
<br />
break;<br />
</pre><br />
<br />
=== type ===<br />
<br />
('''Mandatory''')<br />
<br />
You can use 3 types of game states:<br />
* activeplayer (1 player is active and must play.)<br />
* multipleactiveplayer (1..N players can be active and must play.)<br />
* game (No player is active. This is a transitional state to do something automatic specified by the game rules.)<br />
<br />
'''Note:''' Make sure you don't mistype the value of this attribute. If you do (e.g. 'multiactiveplayer' instead of 'multipleactiveplayer'), things won't work, and you might have a hard time figuring out why.<br />
<br />
=== description ===<br />
<br />
('''Mandatory''')<br />
<br />
The description is the string that is displayed in the main action bar (top of the screen) when the state is active.<br />
<br />
When a string is specified as a description, you must use "clienttranslate" in order for the string to be translated on the client side:<br />
<br />
<pre><br />
"description" => clienttranslate('${actplayer} must play a card or pass'),<br />
</pre><br />
<br />
In the description string, you can use ${actplayer} to refer to the active player.<br />
<br />
You can also use custom arguments in your description. These custom arguments correspond to values returned by your "args" PHP method (see below "args" field).<br />
<br />
Example of custom field:<br />
<pre><br />
<br />
In states.inc.php:<br />
"description" => clienttranslate('${actplayer} must choose ${nbr} identical energies'),<br />
"args" => "argMyArgumentMethod"<br />
<br />
In mygame.game.php:<br />
function argMyArgumentMethod()<br />
{<br />
return array(<br />
'nbr' => 2 // In this case ${nbr} in the description will be replaced by "2"<br />
); <br />
}<br />
</pre><br />
<br />
Note: You may specify an empty string ("") here if it never happens that the game remains in this state (i.e., if this state immediately jumps to another state when activated).<br />
<br />
Note²: Usually, you specify a string for "activeplayer" and "multipleactiveplayer" game states, and you specify an empty string for "game" game states. BUT, if you are using synchronous notifications, the client can remain on a "game" type game state for a few seconds, and in this case it may be useful to display a description in the status bar while in this state.<br />
<br />
=== descriptionmyturn ===<br />
<br />
('''Mandatory''' when the state type is "activeplayer" or "multipleactiveplayer")<br />
<br />
"descriptionmyturn" has exactly the same role and properties as "description", except that this value is displayed to the current active player - or to all active players in case of a multipleactiveplayer game state.<br />
<br />
In general, we have this situation:<br />
<br />
<pre><br />
"description" => clienttranslate('${actplayer} can take some actions'),<br />
"descriptionmyturn" => clienttranslate('${you} can take some actions'),<br />
</pre><br />
<br />
Note: you can use ${you} in descriptionmyturn so the description will display "You" instead of the name of the player.<br />
<br />
=== action ===<br />
<br />
('''Mandatory''' when the state type is "game.")<br />
<br />
"action" specifies a PHP method to call when entering this game state.<br />
<br />
Example:<br />
<pre><br />
In states.inc.php:<br />
28 => array(<br />
"name" => "startPlayerTurn",<br />
"description" => '',<br />
"type" => "game",<br />
"action" => "stStartPlayerTurn",<br />
<br />
In mygame.game.php:<br />
function stStartPlayerTurn()<br />
{ <br />
// ... do something at the beginning of this game state<br />
</pre><br />
<br />
Usually, for a "game" state type, the action method is used to perform automatic functions specified by the rules (for example: check victory conditions, deal cards for a new round, go to the next player, etc.) and then jump to another game state.<br />
<br />
Note: a BGA convention specifies that PHP methods called with "action" are prefixed by "st".<br />
<br />
Note: this field CAN be used for player states to set something up; e.g., for multiplayer states, it can make all players active.<br />
<br />
=== transitions ===<br />
<br />
('''Mandatory''')<br />
<br />
With "transitions" you specify which game state(s) you can jump to from a given game state.<br />
<br />
Example:<br />
<pre><br />
25 => array(<br />
"name" => "myGameState",<br />
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),<br />
....<br />
}<br />
</pre><br />
<br />
In the example above, if "myGameState" is the current active game state, I can jump to the game state with ID 27 or the game state with ID 39.<br />
<br />
Example to jump to ID 27:<br />
<pre><br />
In mygame.game.php:<br />
$this->gamestate->nextState( "nextPlayer" );<br />
</pre><br />
<br />
Important: "nextPlayer" is the name of the transition, and NOT the name of the target game state. Multiple transitions can lead to the same game state.<br />
<br />
Note: If there is only 1 transition, you may give it an empty name.<br />
<br />
Example:<br />
<pre><br />
In states.inc.php:<br />
"transitions" => array( "" => 27 ),<br />
<br />
In mygame.game.php:<br />
$this->gamestate->nextState( ); // We don't need to specify a transition as there is only one here<br />
</pre><br />
<br />
=== possibleactions ===<br />
<br />
('''Mandatory''' when the game state is "activeplayer" or "multipleactiveplayer")<br />
<br />
"possibleactions" defines the actions possible by the players in this game state, and ensures they cannot cannot perform actions that are not allowed in this state.<br />
<br />
Example:<br />
<br />
<pre><br />
In states.game.php:<br />
"possibleactions" => array( "playCard", "pass" ),<br />
<br />
In mygame.game.php:<br />
function playCard( ...)<br />
{<br />
self::checkAction( "playCard" ); // Will fail if "playCard" is not specified in "possibleactions" in the current game state.<br />
<br />
....<br />
<br />
In mygame.js:<br />
playCard: function( ... )<br />
{<br />
if( this.checkAction( "playCard" ) ) // Will fail if "playCard" is not specified in "possibleactions" in the current game state.<br />
{ return ; }<br />
<br />
....<br />
<br />
</pre><br />
<br />
=== args ===<br />
<br />
(optional)<br />
<br />
Sometimes it happens that you need some information on the client side (i.e., for your game interface) only for a specific game state.<br />
<br />
Example 1 : in ''Reversi'', the list of possible moves during the playerTurn state.<br />
Example 2 : in ''Caylus'', the number of remaining king's favors to choose in the state where the player is choosing a favor.<br />
Example 3 : in ''Can't Stop'', the list of possible die combinations to be displayed to the active player so that he can choose from among them.<br />
<br />
In such a situation, you can specify a method name as the « args » argument for your game state. This method must retrieve some piece of information about the game (example: for ''Reversi'', the list of possible moves) and return it.<br />
<br />
Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.<br />
<br />
Let's see a complete example using args with « Reversi » game :<br />
<br />
In states.inc.php, we specify an « args » argument for gamestate « playerTurn » :<br />
<pre><br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn", <================================== HERE<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
</pre><br />
<br />
It corresponds to a « argPlayerTurn » method in our PHP code (reversi.game.php):<br />
<pre><br />
function argPlayerTurn() {<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves()<br />
);<br />
}<br />
</pre><br />
<br />
Then, when we enter into the « playerTurn » game state on the client side, we can highlight the possible moves on the board using information returned by argPlayerTurn :<br />
<br />
<pre><br />
onEnteringState: function( stateName, args ) {<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName ) {<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).<br />
<br />
Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (example: argPlayerTurn).<br />
<br />
'''Warning''': the "args" method can be called before the "action" method so don't expect data modifications by the "action" method to be available in the "args" method!<br />
<br />
==== Private info in args ====<br />
<br />
By default, all data provided through this method are PUBLIC TO ALL PLAYERS. Please do not send any private data with this method, as a cheater could see it even it is not used explicitly by the game interface logic.<br />
<br />
However, it is possible to specify that some data should be sent to specific players only.<br />
<br />
Example 1: send information to active player(s) only:<br />
<br />
<pre><br />
function argPlayerTurn() {<br />
return array(<br />
'_private' => array( // Using "_private" keyword, all data inside this array will be made private<br />
<br />
'active' => array( // Using "active" keyword inside "_private", you select active player(s)<br />
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)<br />
)<br />
),<br />
<br />
'possibleMoves' => self::getPossibleMoves() // will be sent to all players<br />
);<br />
}<br />
</pre><br />
<br />
Inside the js file, these variables will be available through `args.args._private`. (e.g. `args.args._private.somePrivateData` -- it is not `args._private.active.somePrivateData` nor is it `args.somePrivateData`)<br />
<br />
Example 2: send information to a specific player (<specific_player_id>) only:<br />
<br />
<pre><br />
function argPlayerTurn() {<br />
return array(<br />
'_private' => array( // Using "_private" keyword, all data inside this array will be made private<br />
<br />
<specific_player_id> => array( // select one specific player by id<br />
'somePrivateData' => self::getSomePrivateData() // will be sent only to <specific_player_id><br />
)<br />
),<br />
<br />
'possibleMoves' => self::getPossibleMoves() // will be sent to all players<br />
);<br />
}<br />
</pre><br />
<br />
IMPORTANT: in certain situations (example: "multipleactiveplayer" game state) these "private data" features can have a significant impact on performance. Please do not use if not needed.<br />
<br />
It is also possible to use these private args in the "description" messages, like "${you} have to play ${_private.count} cards".<br />
<br />
=== updateGameProgression ===<br />
<br />
(optional)<br />
<br />
If you specify "updateGameProgression => true" in a game state, your "getGameProgression" PHP method will be called at the beginning of this game state - and thus the game progression of the game will be updated.<br />
<br />
''At least one'' of your game states (any one) must specify "updateGameProgression=>true".<br />
<br />
== Implementation Notes ==<br />
<br />
<br />
=== Using Named Constants for States ===<br />
<br />
Using numeric constants is prone to errors. If you want you can declare state constants as PHP named constants. This way you can<br />
use them in the states file and in game.php as well<br />
<br />
EXAMPLE:<br />
<br />
states.inc.php:<br />
<br />
<pre><br />
// define contants for state ids<br />
if (!defined('STATE_END_GAME')) { // ensure this block is only invoked once, since it is included multiple times<br />
define("STATE_PLAYER_TURN", 2);<br />
define("STATE_GAME_TURN", 3);<br />
define("STATE_PLAYER_TURN_CUBES", 4);<br />
define("STATE_END_GAME", 99);<br />
}<br />
<br />
$machinestates = array(<br />
<br />
...<br />
<br />
STATE_PLAYER_TURN => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must select an Action Space or Pass'),<br />
"descriptionmyturn" => clienttranslate('${you} must select an Action Space or Pass'),<br />
"type" => "activeplayer",<br />
"args" => 'arg_playerTurn',<br />
"possibleactions" => array( "selectWorkerAction", "pass" ),<br />
"transitions" => array( <br />
"loopback" => STATE_PLAYER_TURN,<br />
"playCubes" => STATE_PLAYER_TURN_CUBES,<br />
"pass" => STATE_GAME_TURN )<br />
),<br />
</pre><br />
<br />
=== Example of multipleactiveplayer state ===<br />
<br />
This is an example of a multipleactiveplayer state:<br />
<br />
2 => array (<br />
'name' => 'playerTurnSetup',<br />
'type' => 'multipleactiveplayer',<br />
'description' => clienttranslate('Other players must choose one Objective'),<br />
'descriptionmyturn' => clienttranslate('${you} must choose one Objective card to keep'),<br />
'possibleactions' => array ('playKeep' ),<br />
'transitions' => array ( 'next' => 5, 'loopback' => 2, ),<br />
'action' => 'st_MultiPlayerInit',<br />
'args' => 'arg_playerTurnSetup',<br />
),<br />
<br />
In game.php:<br />
// this will make all players multiactive just before entering the state<br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
<br />
When ending the player action, instead of a state transition, deactivate player.<br />
<br />
function action_playKeep($cardId) {<br />
$this->checkAction('playKeep');<br />
$player_id = $this->getCurrentPlayerId(); // CURRENT!!! not active<br />
... // some logic here<br />
$this->gamestate->setPlayerNonMultiactive($player_id, 'next'); // deactivate player; if none left, transition to 'next' state<br />
}<br />
<br />
<br />
=== Diffrence between Single active and Multi active states ===<br />
In a classic "activePlayer" state:<br />
<br />
* You cannot change the active player DURING the state. This is to ensure that during 1 activePlayer state, only ONE player is active<br />
* As a consequence, you must set the active player BEFORE entering the activePlayer state<br />
* Finally, during onEnteringState, on JS side, the active player is signaled as active and the information is reliable and usable.<br />
<br />
In a "multiplePlayer" state:<br />
<br />
* You can (and must) change the active players DURING the state<br />
* During such a state, players can be activated/desactivated anytime during the state, giving you the maximum of possibilities.<br />
* You shouldn't set actives player before entering the state. But you can set it in "state initialized" php function (see example above st_MultiPlayerInit)<br />
* Finally, during onEnteringState, on JS side, the active players are NOT actives yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.</div>Volker78https://en.doc.boardgamearena.com/index.php?title=Game_interface_logic:_yourgamename.js&diff=4841Game interface logic: yourgamename.js2020-07-01T20:14:23Z<p>Volker78: Correct dojo.place doc</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game interface. Here you will define:<br />
<br />
* Which actions on the page will generate calls to the server.<br />
* What happens when you get a notification for a change from the server and how it will show in the browser. <br />
<br />
== File structure ==<br />
<br />
The details of how the file is structured are described below with comments on the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* '''constructor''': here you can define global variables for your whole interface.<br />
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.<br />
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.<br />
* '''onLeavingState''': this method is called when leaving a game state.<br />
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.<br />
* ''(utility methods)'': this is where you can define your utility methods.<br />
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).<br />
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.<br />
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.<br />
<br />
== General tips ==<br />
<br />
; this.player_id<br />
: ID of the player on whose browser the code is running.<br />
<br />
; this.isSpectator<br />
: Flag set to true if the user at the table is a spectator (not a player).<br />
: Note: This is a variable, not a function.<br />
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].<br />
<br />
; this.gamedatas<br />
: Contains the initial set of data to init the game, created at game start or by game refresh (F5).<br />
: You can update it as needed to keep an up-to-date reference of the game on the client side if you need it. (Most of the time this is unnecessary).<br />
<br />
; this.isCurrentPlayerActive()<br />
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play).<br />
<br />
; this.getActivePlayerId()<br />
: Return the ID of the active player, or null if we are not in an "activeplayer" type state.<br />
<br />
; this.getActivePlayers()<br />
: Return an array with the IDs of players who are currently active (or an empty array if there are none).<br />
<br />
; this.bRealtime<br />
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.<br />
<br />
== Dojo framework ==<br />
<br />
BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].<br />
<br />
The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.<br />
<br />
To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.<br />
<br />
== ShrinkSafe minimization ==<br />
<br />
For performance reasons, when deploying a game the js code is minimized using ShrinkSafe (based on ECMASCRIPT version 3). Some advanced syntax may not be compatible with this process. In particular:<br />
* You should not use reserved keywords from the javascript language as variables.<br />
* You should not declare default argument values in function declarations. The following syntax is invalid for ShrinkSafe: '''function myFunc(requiredArg, optionalArg = 'defaultValue') {}'''<br />
<br />
'''Tip:''' a developer encountering some problems with this has successfully used [http://plugins.netbeans.org/plugin/58580/jshint JSHint] on NetBeans to evaluate code to make it compatible for ECMAScript 3. With the plugin installed, set the below options in '''.jshintrc''' file, and then open '''Action Items''' window (in NetBeans):<pre>{ "maxerr": 999, "esversion": 3 }</pre><br />
<br />
'''Tip:''' some online tools also allow to convert between different versions of javascript, such as https://www.typescriptlang.org/play<br />
<br />
== Accessing and manipulating the DOM ==<br />
<br />
'''$('some_html_element_id')'''<br />
<br />
The $() function is used to get an HTML element using its "id" attribute.<br />
<br />
Example 1: modify the content of a "span" element:<br />
<br />
<pre><br />
In your HTML code:<br />
<span id="a_value_in_the_game_interface">1234</span><br />
<br />
In your Javascript code:<br />
$('a_value_in_the_game_interface').innerHTML = "9999";<br />
</pre><br />
<br />
Note: $() is the standard method to access some HTML element with the BGA Framework. You should not use the '''getElementById''' function.<br />
<br />
<br />
'''dojo.style'''<br />
<br />
With dojo.style you can modify the CSS property of any HTML element in your interface.<br />
<br />
Examples:<br />
<br />
<pre><br />
// Make an element disappear<br />
dojo.style( 'my_element', 'display', 'none' );<br />
<br />
// Give an element a 2px border<br />
dojo.style( 'my_element', 'borderWidth', '2px' );<br />
<br />
// Change the background position of an element<br />
// (very practical when you are using CSS sprites to transform an element to another)<br />
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );<br />
</pre><br />
<br />
Note: you must always use dojo.style to modify the CSS properties of HTML elements.<br />
<br />
Note²: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).<br />
<br />
'''dojo CSS classes manipulation'''<br />
<br />
In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).<br />
<br />
Advantages are:<br />
* All your CSS stuff remains in your CSS file.<br />
* You can add/remove a list of CSS modifications with a simple function and without error.<br />
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.<br />
<br />
Example from ''Reversi'':<br />
<br />
<pre><br />
// We add "possibleMove" to an element<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
<br />
// In our CSS file, the class is defined as:<br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
<br />
// So we've applied 4 CSS property changes in one line of code.<br />
<br />
// ... and when we need to check if a square is a possible move on the client side:<br />
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{ ... }<br />
<br />
// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
</pre><br />
<br />
Conclusion: We encourage you to use '''dojo.addClass''', '''dojo.removeClass''' and '''dojo.hasClass''' to make your life easier :)<br />
<br />
'''dojo.query'''<br />
<br />
With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.<br />
<br />
Example:<br />
<pre><br />
// All elements with class "possibleMove":<br />
var elements = dojo.query( '.possibleMove' );<br />
<br />
// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):<br />
dojo.query( '#board .token' ).length;<br />
</pre><br />
<br />
But what is really cool with dojo.query is that you can combine it with almost all methods above.<br />
<br />
Examples:<br />
<pre><br />
// Trigger a method when the mouse enter in any element with class "meeple":<br />
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );<br />
<br />
// Hide all meeples who are on the board<br />
dojo.query( '#board .meeple' ).style( 'display', 'none' );<br />
</pre><br />
<br />
'''dojo.place'''<br />
<br />
dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.<br />
<br />
<pre><br />
// Insert your HTML code as a child of a container element<br />
dojo.place( "<your html code>", "your_container_element_id" );<br />
<br />
// Replace the container element with your new html<br />
dojo.place( "<your html code>", "your_container_element_id", "replace" );<br />
<br />
</pre><br />
<br />
The third parameter of dojo.place can take various interesting value.<br />
<br />
values possibles :<br />
<br />
"replace" : (see description above).<br />
<br />
"first" : Places the node as a child of the reference node. The node is placed as the first child.<br />
<br />
"last" (default) : Places the node as a child of the reference node. The node is placed as the last child.<br />
<br />
"before" : places the node right before the reference node.<br />
<br />
"after" : places the node right after the reference node.<br />
<br />
"only" : replaces all children of the reference node with the node.<br />
<br />
positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child. <br />
<br />
See also full doc on dojo.place : [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]<br />
<br />
Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".<br />
<br />
'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''<br />
<br />
Same as dojo.style(), but for all the nodes set with the specified cssClassName<br />
<br />
=== Animations ===<br />
<br />
'''Dojo Animations'''<br />
<br />
BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).<br />
<br />
However, most of the time, you can just use methods below, which are built on top of Dojo Animation.<br />
<br />
Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.<br />
<br />
'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''<br />
<br />
You can use slideToObject to "slide" an element to a target position.<br />
<br />
Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.<br />
<br />
The parameters are:<br />
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.<br />
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.<br />
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.<br />
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.<br />
<br />
BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.<br />
<br />
Example:<br />
<pre><br />
this.slideToObject( "some_token", "some_place_on_board" ).play();<br />
</pre><br />
<br />
<br />
'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''<br />
<br />
This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".<br />
<br />
Example: slide a token to some place on the board, 10 pixels to the bottom:<br />
<pre><br />
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();<br />
</pre><br />
<br />
'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''<br />
<br />
This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.<br />
<br />
slideTemporaryObject does all of this for you:<br />
* mobile_obj_html is a piece of HTML code that represent the object to slide.<br />
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.<br />
* from is the ID of the origin of the slide.<br />
* to is the ID of the target of the slide.<br />
* duration/delay works exactly like in "slideToObject"<br />
<br />
Example:<br />
<pre><br />
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );<br />
</pre><br />
<br />
'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''<br />
<br />
This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.<br />
<br />
It works the same as this.slideToObject and takes the same arguments. <br />
<br />
Example:<br />
<pre><br />
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );<br />
</pre><br />
<br />
'''this.fadeOutAndDestroy( node, duration, delay )'''<br />
<br />
This function fade out the target HTML node, then destroy it.<br />
<br />
Example:<br />
<pre><br />
this.fadeOutAndDestroy( "a_card_that_must_disappear" );<br />
</pre><br />
<br />
CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.<br />
<br />
'''Rotating elements'''<br />
<br />
You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.<br />
<br />
This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.<br />
<br />
IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):<br />
<br />
<pre><br />
var transform;<br />
dojo.forEach(<br />
['transform', 'WebkitTransform', 'msTransform',<br />
'MozTransform', 'OTransform'],<br />
function (name) {<br />
if (typeof dojo.body().style[name] != 'undefined') {<br />
transform = name;<br />
}<br />
});<br />
// ... and then use "transform" as the name of your CSS property for rotation<br />
</pre><br />
<br />
'''Animation Callbacks'''<br />
<br />
If you wish to run some code only after an animation has completed you can do this by linking a callback method.<br />
<br />
<pre><br />
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );<br />
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));<br />
animation_id.play();<br />
<br />
…<br />
<br />
callback_function: function(params) {<br />
// this will be called after the animation ends<br />
},<br />
</pre><br />
<br />
If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).<br />
<br />
=== Moving elements ===<br />
<br />
'''this.placeOnObject( mobile_obj, target_obj )'''<br />
<br />
placeOnObject works exactly like "slideToObject", except that the effect is immediate.<br />
<br />
This is not really an animation, but placeOnObject is frequently used before starting an animation.<br />
<br />
Example:<br />
<pre><br />
// (We just created an object "my_new_token")<br />
<br />
// Place the new token on current player board<br />
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );<br />
<br />
// Then slide it to its position on the board<br />
this.slideToObject( "my_new_token", "a_place_on_board" ).play();<br />
</pre><br />
<br />
'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''<br />
<br />
This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".<br />
<br />
'''this.attachToNewParent( mobile_obj, target_obj )'''<br />
<br />
With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of <br />
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.<br />
<br />
Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.<br />
<br />
Why using this method?<br />
<br />
Changing the HTML parent of an element can be useful for the following reasons:<br />
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.<br />
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.<br />
<br />
CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).<br />
<br />
== Players input ==<br />
<br />
'''dojo.connect'''<br />
<br />
Used to associate a player event with one of your notification method.<br />
<br />
Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):<br />
<pre><br />
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );<br />
</pre><br />
<br />
Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.<br />
<br />
'''this.checkAction( "my_action_name" )'''<br />
<br />
Usage: checkAction: function( action, nomessage )<br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
* interface locking (a player can't do any action if an action is already in progress)<br />
<br />
Restricted arguments names (please don't use them):<br />
<br />
* "action"<br />
* "module"<br />
* "class"<br />
return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).<br />
<br />
return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".<br />
<br />
Example:<br />
<pre><br />
function onClickOnGameElement( evt )<br />
{<br />
if( this.checkAction( "my_action" ) )<br />
{<br />
// Do the action<br />
}<br />
}<br />
</pre><br />
<br />
'''this.checkPossibleActions( "my_action_name" )'''<br />
<br />
Usage: checkPossibleActions: function( action, nomessage )<br />
<br />
* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. <br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
* interface locking (a player can't do any action if an action is already in progress)<br />
<br />
Restricted arguments names (please don't use them):<br />
* "action"<br />
* "module"<br />
* "class"<br />
<br />
'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''<br />
<br />
This method must be used to send a player input to the game server.<br />
<br />
* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"<br />
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.<br />
* obj_callback: must be set to "this".<br />
* callback: a function to trigger when the server returns and everything went fine.<br />
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.<br />
<br />
Usage:<br />
<pre><br />
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true, <br />
arg1: myarg1, <br />
arg2: myarg2, <br />
...<br />
}, this, function( result ) {<br />
// Do some stuff after a successful call<br />
} );<br />
</pre><br />
<br />
'''this.confirmationDialog()'''<br />
<br />
Display a confirmation dialog with a yes/no choice.<br />
<br />
We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.<br />
<br />
Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );<br />
<br />
Example:<br />
<pre><br />
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),<br />
dojo.hitch( this, function() {<br />
this.ajaxcall( '/seasons/seasons/useBonus.html',<br />
{ id:bonus_id, lock:true }, this, function( result ) {} );<br />
} ) ); <br />
</pre><br />
<br />
<br />
; addEventToClass: function( cssClassName, eventName, functionName )<br />
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName<br />
<br />
'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''<br />
<br />
You can use this method to add an action button in the main action status bar.<br />
<br />
Arguments:<br />
* id: an element ID that should be unique in your HTML DOM document.<br />
* label: the text of the button. Should be translatable (use _() function).<br />
* method: the name of your method that must be triggered when the player clicks on this button.<br />
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.<br />
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.<br />
* color: could be '''blue''' (default), '''red''' or '''gray'''.<br />
<br />
You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hearts example):<br />
<br />
<pre><br />
onUpdateActionButtons: function( stateName, args ) {<br />
<br />
if (this.isCurrentPlayerActive()) { <br />
switch( stateName ) {<br />
case 'giveCards':<br />
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' ); <br />
break;<br />
}<br />
}<br />
}, <br />
</pre><br />
<br />
In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.<br />
<br />
Example using blinking red button:<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red'); <br />
</pre><br />
<br />
Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''', <br />
if you don't like it you have to change css display value<br />
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Notifications ==<br />
<br />
When something happens on the server side, your game interface Javascript logic received a notification.<br />
<br />
Here's how you can handle these notifications on the client side.<br />
<br />
=== Subscribe to notifications ===<br />
<br />
Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.<br />
<br />
Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):<br />
<br />
<pre><br />
// In setupNotifications method:<br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
</pre><br />
<br />
Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.<br />
<br />
Then, you have to define your "notif_playDisc" method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".<br />
<br />
Example:<br />
<pre><br />
// If you did this on PHP side:<br />
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );<br />
<br />
// On Javascript side, you can access the "myArgument" like this:<br />
notif_myNotification: function( notif )<br />
{<br />
alert( "myArgument = " + notif.args.myArgument );<br />
}<br />
</pre><br />
<br />
<br />
=== Synchronous notifications ===<br />
<br />
When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.<br />
<br />
However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.<br />
<br />
As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.<br />
<br />
Here's how we do this, right after our subscription:<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler<br />
</pre><br />
<br />
<br />
=== Pre-defined notification types ===<br />
<br />
'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.<br />
<br />
'''message''' - This defines notification that shows on players log and have no other effect<br />
<br />
// You can call this on php side without doing anything on client side<br />
self::notifyAllPlayers( 'message', 'hello', array( ) );<br />
<br />
== Tooltips ==<br />
<br />
'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''<br />
<br />
Add a simple text tooltip to the DOM node.<br />
<br />
Specify 'helpString' to display some information about "what is this game element?".<br />
Specify 'actionString' to display some information about "what happens when I click on this element?".<br />
<br />
You must specify both helpString and actionString. Most of the time, you should use only one and specify a void string ("") for the other one.<br />
<br />
Usually, _() must be used for the text to be marked for translation.<br />
<br />
"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).<br />
<br />
Example:<br />
<pre><br />
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );<br />
</pre><br />
<br />
'''this.addTooltipHtml( nodeId, html, delay )'''<br />
<br />
Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''<br />
<br />
Add a simple text tooltip to all the DOM nodes set with this cssClass. <br />
<br />
IMPORTANT: all concerned nodes must have IDs to get tooltips.<br />
<br />
'''this.addTooltipHtmlToClass( cssClass, html, delay )'''<br />
<br />
Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
IMPORTANT: all concerned nodes must have IDs to get tooltips<br />
<br />
'''this.removeTooltip( nodeId )'''<br />
<br />
Remove a tooltip from the DOM node.<br />
<br />
== Dialogs, warning messages, confirmation dialogs, ... ==<br />
<br />
=== Warning messages ===<br />
<br />
Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.<br />
<br />
Ex: someone fulfill one of the end of the game condition, so this is the last turn.<br />
<br />
'''this.showMessage( msg, type )'''<br />
<br />
showMessage shows a message in a big rectangular area on the top of the screen of current player.<br />
<br />
* "msg" is the string to display. It should be translated.<br />
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.<br />
<br />
Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.<br />
<br />
=== Confirmation dialog ===<br />
<br />
'''confirmationDialog( message, yesHandler, noHandler )'''<br />
<br />
<br />
When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.<br />
<br />
CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.<br />
<br />
The situation where you should use a confirmation dialog are the following:<br />
* It must not happen very often during a game.<br />
* It must be linked to an action that can really "kill a game" if the player do not pay attention.<br />
* It must be something that can be done by mistake (ex: a link on the action status bar).<br />
<br />
How to display a confirmation dialog:<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {<br />
this.bakeThePie();<br />
} ) ); <br />
return; // nothing should be called or done after calling this, all action must be done in the handler <br />
</pre><br />
<br />
=== Multiple choice dialog ===<br />
You can use this dialog to give user a choice with small amount of options:<br />
<pre><br />
var keys = [1,5,10];<br />
this.multipleChoiceDialog(<br />
_('How many bugs to fix?"), keys, <br />
dojo.hitch(this, function(choice) {<br />
var bugchoice = keys[choice];<br />
console.log('dialog callback with '+bugchoice);<br />
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));<br />
</pre><br />
<br />
=== Dialogs ===<br />
<br />
As a general rule, you shouldn't use dialogs windows.<br />
<br />
BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.<br />
<br />
Sometimes although, you need to display a dialog window. Here is how you do this:<br />
<br />
<br />
<br />
// Create the new dialog over the play zone. You should store the handler in a member variable to access it later<br />
this.myDlg = new ebg.popindialog();<br />
this.myDlg.create( 'myDialogUniqueId' );<br />
this.myDlg.setTitle( _("my dialog title to translate") );<br />
this.myDlg.setMaxWidth( 500 ); // Optional<br />
<br />
// Create the HTML of my dialog. <br />
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]<br />
var html = this.format_block( 'jstpl_myDialogTemplate', { <br />
arg1: myArg1,<br />
arg2: myArg2,<br />
...<br />
} ); <br />
<br />
// Show the dialog<br />
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog<br />
this.myDlg.show();<br />
<br />
// Now that the dialog has been displayed, you can connect your method to some dialog elements<br />
// Example, if you have an "OK" button in the HTML of your dialog:<br />
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){<br />
evt.preventDefault();<br />
this.myDlg.destroy();<br />
} );<br />
<br />
If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:<br />
// Removes the default close icon<br />
this.myDlg.hideCloseIcon();<br />
<br />
// Replace the function call when it's clicked<br />
this.myDlg.replaceQuitCallback( function() { ... } );<br />
<br />
=== Scoring dialogs ===<br />
<br />
Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.<br />
<br />
Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.<br />
<br />
Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.<br />
<br />
Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":<br />
<pre><br />
// on PHP side:<br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table<br />
) ); <br />
</pre><br />
<br />
The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.<br />
<br />
Example: display an 3x3 array of strings<br />
<pre><br />
$table = array(<br />
array( "one", "two", "three" ), // This is my first line<br />
array( "four", "five", "six" ), // This is my second line<br />
array( "seven", "height", "nine" ) // This is my third line<br />
);<br />
</pre><br />
<br />
As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:<br />
<pre><br />
$table = array(<br />
array( "one", "two", array( "str" => clienttranslate("a string with an ${argument}"), "args" => array( 'argument' => 'argument_value' ) ) ),<br />
array( "four", "five", "six" ), <br />
array( "seven", "height", "nine" )<br />
);<br />
</pre><br />
<br />
This is especially useful when you want to display player names with colors. Example from "Hearts":<br />
<pre><br />
$firstRow = array( '' );<br />
foreach( $players as $player_id => $player )<br />
{<br />
$firstRow[] = array( 'str' => '${player_name}',<br />
'args' => array( 'player_name' => $player['player_name'] ),<br />
'type' => 'header'<br />
);<br />
}<br />
$table[] = $firstRow;<br />
</pre><br />
<br />
You can also use three extra attributes in the parameter array for the notification:<br />
<br />
<pre><br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table,<br />
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),<br />
'args' => array( 'number' => 3 ),<br />
),<br />
"footer" => '<div>Some footer</div>',<br />
"closing" => clienttranslate( "Closing button label" )<br />
) ); <br />
</pre><br />
<br />
*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors). <br />
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)<br />
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).<br />
<br />
=== Scoring animated display ===<br />
<br />
Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.<br />
You can do it with:<br />
<br />
<pre><br />
this.displayScoring( anchor_id, color, score, duration );<br />
</pre><br />
<br />
'''anchor_id''': ID of the element to place the animated score onto (without the '#') <br />
<br />
'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.<br />
<br />
'''score''': numeric score to display, prefixed by a '+'<br />
<br />
'''duration''': animation duration in milliseconds<br />
<br />
=== Speech bubble ===<br />
<br />
For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.<br />
This is done with:<br />
<br />
<pre><br />
this.showBubble( anchor_id, text, delay, duration, custom_class )<br />
</pre><br />
<br />
delay in milliseconds is optional (default 0)<br />
<br />
duration in milliseconds is optional (default 3000)<br />
<br />
custom_class is optional, if you need to override the default bubble style<br />
<br />
'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.<br />
<br />
== Update players score ==<br />
<br />
Increase a player score (with a positive or negative number):<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].incValue( score_delta );<br />
</pre><br />
<br />
Set a player score to a specific value:<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].setValue( new_score );<br />
</pre><br />
<br />
== Players panels ==<br />
<br />
=== Adding stuff to player's panel ===<br />
<br />
At first, create a new "JS template" string in your template (tpl) file:<br />
<br />
(from Gomoku example)<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Then, you add this piece of code in your JS file to add this template to each player panel:<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
(Note: the code above is of course from your "setup" function in your Javascript).<br />
<br />
Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".<br />
<br />
=== Player's panel disabling/enabling ===<br />
<br />
'''this.disablePlayerPanel( player_id )'''<br />
<br />
Disable given player panel (the panel background become gray).<br />
<br />
Usually, this is used to signal that this played passes, or will be inactive during a while.<br />
<br />
Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.<br />
<br />
'''this.enablePlayerPanel( player_id )'''<br />
<br />
Enable a player panel that has been disabled before.<br />
<br />
'''this.enableAllPlayerPanels()'''<br />
<br />
Enable all player panels that has been disabled before.<br />
<br />
== Image loading ==<br />
<br />
See also [[Game_art:_img_directory]].<br />
<br />
'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.<br />
<br />
'''dontPreloadImage( image_file_name )'''<br />
<br />
Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.<br />
<br />
Example of use:<br />
<pre><br />
this.dontPreloadImage( 'cards.png' );<br />
</pre><br />
<br />
This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.<br />
<br />
Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.<br />
<pre><br />
// By default, do not preload anything<br />
this.dontPreloadImage( 'cards.png' );<br />
this.dontPreloadImage( 'clan1.png' );<br />
this.dontPreloadImage( 'clan2.png' );<br />
this.dontPreloadImage( 'clan3.png' );<br />
this.dontPreloadImage( 'clan4.png' );<br />
this.dontPreloadImage( 'clan5.png' );<br />
this.dontPreloadImage( 'clan6.png' );<br />
this.dontPreloadImage( 'clan7.png' );<br />
this.dontPreloadImage( 'clan8.png' );<br />
this.dontPreloadImage( 'clan9.png' );<br />
this.dontPreloadImage( 'clan10.png' );<br />
var to_preload = [];<br />
for( i in this.gamedatas.clans )<br />
{<br />
var clan_id = this.gamedatas.clans[i];<br />
to_preload.push( 'clan'+clan_id+'.png' );<br />
}<br />
if( to_preload.length == 5 )<br />
{<br />
this.ensureSpecificGameImageLoading( to_preload );<br />
}<br />
</pre><br />
<br />
'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.<br />
<br />
== Other useful stuff ==<br />
<br />
<br />
'''dojo.hitch'''<br />
<br />
With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.<br />
<br />
Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:<br />
<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {<br />
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );<br />
} ) ); <br />
</pre><br />
<br />
In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.<br />
<br />
<br />
; updateCounters(counters)<br />
: Useful for updating game counters in the player panel (such as resources). <br />
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]<br />
: All counters must be referenced in this.gamedatas.counters and will be updated.<br />
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.<br />
<br />
<br />
'''onScreenWidthChange()'''<br />
This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the viewport size at the start of the game too.<br />
<br />
<br />
'''updatePageTitle()'''<br />
This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling the function, it allows to update the turn description without changing state.<br />
<br />
Example from Terra Mystica:<br />
<pre><br />
onClickFavorTile: function( evt )<br />
{<br />
[...]<br />
<br />
if ( ... ) {<br />
<br />
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');<br />
this.updatePageTitle();<br />
this.removeActionButtons();<br />
<br />
this.addActionButton( 'action_confirm1', _("Fire"),<br />
function() { ... }<br />
);<br />
this.addActionButton( 'action_confirm2', _("Water"),<br />
function() { ... }<br />
);<br />
this.addActionButton( 'action_confirm3', _("Earth"),<br />
function() { ... }<br />
);<br />
this.addActionButton( 'action_confirm4', _("Air"),<br />
function() { ... }<br />
);<br />
<br />
this.addActionButton( 'action_cancel', _("Cancel"), function() { ... }, false, false, 'gray'<br />
);<br />
<br />
return;<br />
}<br />
<br />
[...]<br />
<br />
}<br />
</pre><br />
<br />
== BGA GUI components ==<br />
<br />
BGA framework provides some useful ready-to-use components for the game interface:<br />
<br />
[[Studio#BGA_Studio_game_components_reference]]<br />
<br />
Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.<br />
<br />
Example if you are using "ebg.stock":<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/stock" /// <=== we are using ebg.stock module<br />
],<br />
</pre></div>Volker78https://en.doc.boardgamearena.com/index.php?title=Counter&diff=4552Counter2020-05-31T19:33:24Z<p>Volker78: /* Update counter */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
<br />
== Dependency ==<br />
<br />
Don't forget to add '''ebg/counter''' as a dependency:<br />
<br />
// in your game js<br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter" /// <==== HERE],<br />
<br />
== Setup a counter ==<br />
<br />
<pre><br />
player.handSizeCounter = new ebg.counter();<br />
player.handSizeCounter.create('hand_size_player_' + player_id);<br />
</pre><br />
<br />
== Functions on counter ==<br />
<br />
<pre><br />
player.handSizeCounter.getValue();<br />
player.handSizeCounter.incValue(by);<br />
player.handSizeCounter.setValue(player.handSize);<br />
</pre><br />
<br />
== Players panels ==<br />
<br />
=== Adding stuff to player's panel ===<br />
<br />
First, create a new JS template string in your template (tpl) file.<br />
<br />
From the ''Gomoku'' example:<br />
<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Then, add this piece of code in the '''setup''' function of your JS file to add this template to each player panel:<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
Often, you have to distinguish between the current player and other players. In this case, create another JS template (ex: jstpl_otherplayer_board) and use it where "player_id" is different than "this.player_id".</div>Volker78